rray. The output from this example is

Matched on yon, Yon, son, con.

Substitution

Once you get the hang of pattern matching, substitutions are quite straightforward and very powerful. The substitution operator is s/// that resembles the match operator but has three rather than two slashes. As with the match operator, any other character may be substituted for forward slashes, and the optional i, g, and o switches may be used.

The pattern to be replaced goes between the first and second delimiters, and the replacement pattern goes between the second and third. To take a simple example,

$house = "henhouse";
$house =~ s/hen/dog/;

change $house from henhouse to doghouse. Note that it isn't possible to use the =~ operation with a literal string in the way we did when matching; that's because you can't modify a literal constant. Instead, store the string in a variable and modify that.

Chapter 8 -- Perl Special Variables

Chapter 8

Perl Special Variables

This section looks in detail at the special variables used in Perl. Understanding these variables is crucial to programming effectively in Perl. Some of the variables are essential for nearly all Perl programs, while others are merely useful shortcuts that can avoid the need to run external programs that extract information from the system.

Each variable may have three possible names:

Most existing Perl programs use only the short name form. This is unfortunate, as the short name is usually a cryptic symbol. The use of these symbols in Perl programs may be daunting at first, especially in complex expressions comprising multiple variables. However, with the aid of this chapter, it soon becomes easy to identify their meaning and thus understand the programs.

The long name was introduced in Perl 5. This chapter lists all the special variables of this English name, in alphabetical order. In Perl 4, you must use the short name. In Perl 5, you can use any of the name forms, but if you want to use the long English name, you must include the following command:

Use English;

This command enables the long names in the Perl 5 program.

Sometimes (in particular where the same variable also exists in awk, the UNIX report processor) an intermediate name is also allowed. Again this requires the use of the English module and so is not available in Perl 4. This means that those who are used to the awk conventions can use them if they wish.

This chapter categorizes special variables in several ways to make it easier for you to use the list as a reference source. The most important of these categories is Scope, which can have the following values:

The other important special-variable category used in this chapter is File Handle Call. Special variables that implicitly refer to the current active file handle can be explicitly bound to any existing file handle. This facility must be activated by the following call:

use FileHandle;

This enables calls of the forms

FILEHANDLE->method(EXPR)
method FILEHANDLE EXPR

The relevant method name usually is the full long name of the special variable. The
optional EXPR is an expression for changing the current value of the file handle, as well as referring to another file handle for the purposes of the special-variable reference. This syntax may seem confusing at first, but when used consistently, it can make Perl programs with formatting much more readable.

Both the long English names and the use of file handles in references to formats are new features in Perl 5. If you are using Perl 4, you must use the short names and allow format operations to take place in relation to the current active file handle, which you can change by using the select() function.

$<I<digit>>

Compliance

    

Syntax
Short Name:          $1, $2, ... $<N>
Scope:               local (read-only)
Definition

These variables are used to refer back to pattern matches. In any pattern to be matched, sets of parentheses are used to mark subpatterns. These subpatterns are numbered from left to right. After a match has been made, each subpattern match is referenced by these variables, up to and including the number of subpatterns that are actually specified. $1 is the first subpattern, $2 is the second, and so on, up to and including $<N>, the Nth subpattern specified.

All subpatterns after the last one ($<N+1>, for example), are equal to undef.

Example
$_ = "AlphaBetaGamma";
/^(Alpha)(.*)(Gamma)$/;
print "$1 then $2 then $3\n";
Tip
If you have alternative patterns and do not know which one may have matched, try using $LAST_PAREN_MATCH instead.

$[

Compliance
    
Syntax
Short Name:          $[
Scope:               localize
Definition

This variable, which is usually set to a value of 0, represents the index of the first element in any array. Programmers who are used to using 1 as the index of the first element of an array could change the value of this variable to suit their preference.

Example
$[ = 1;
$_ = "AlphaBetaGamma";
$tmp = index($_,"Beta");
print "Beta located at: $tmp\n";
$[ = 0;
$_ = "AlphaBetaGamma";
$tmp = index($_,"Beta");
print "Beta located at: $tmp\n";

$ACCUMULATOR

Compliance
  
Syntax
Short Name:          $^A
Scope:               always global
Definition

This variable allows direct access to the line of output built up with the Perl formatting commands. Normally, this access is not necessary, but it is possible.

Example
$tmp = formline<<'FINISH', Alpha, Beta, Gamma;
@<<<<<<<<<< @|||||||||||| @<<<<<<<<<
FINISH
print "Accumulator now contains:\n $^A\n";
$^A = "";

$ARG

Compliance
    
Syntax
Short Name:          $_
Scope:               localize
Definition

This variable is the default pattern space. When reading a file, $ARG usually takes on the value of each line in turn. You can assign a value to $ARG directly. Many functions and operators take this variable as the default upon which to operate, so you can make the code more concise by using $ARG.

Example
$_ = "\$\_ is the default for many operations including print().\n";
print;

$ARGV

Compliance
    
Syntax
Short Name:          $ARGV
Scope:               always global
Definition

When processing an input file, this variable provides access to the name of this file.

Example
print("Assuming this script has been called with an argument as a i/p file:_
while (<>){
      print "$ARGV\n";
      };

$BASETIME

Compliance
    
Syntax
Short Name:          $^T
Scope:               localize
Definition

This variable is the time when the Perl program was started, as measured in basic time units (seconds since the start of 1970).

Example
$nicetime = localtime($^T);
print "This program started at $^T (i.e.
$nicetime).\n";

$CHILD_ERROR

Compliance
    
Syntax
Short Name:          $?
Scope:               localize
Definition

If a Perl script spawns child processes, you can examine their error codes by using this variable.

Example
'ls -lgd /vir';
print "Child Process error was: $?\n";
šš See the $OS_ERROR variable for system error
messages, p. 220

$DEBUGGING

Compliance
    
Syntax
Short Name:          $^D
Scope:               localize
Definition

Perl can be run in debugging mode. This variable allows the value of this flag to be accessed and altered.

Note
Debugging is only allowed if the version of Perl you are using was compiled with DEBUGGING specifically set.

Example
print "The debug flags are: $^D\n";

$EFFECTIVE_GROUP_ID

Compliance
    
Syntax
Short Name:          $)
Intermediate Name:   $EGID
Scope:               localize
Definition

In systems that support users and groups, as well as setting new users and groups within a process, Perl can access both the original and the effective user and group information. The effective group variable provides access to a list of numbers that represent the effective group identifiers (GIDs).

Example
print("Effective Group ID is a list of GIDs: $)\n");

$EFFECTIVE_USER_ID

Compliance
    
Syntax
Short Name:          $>
Intermediate Name:   $EUID
Scope:               localize
Definition

In systems that support users and groups, as well as setting new users and groups within a process, Perl can access both the original and the effective user and group information. The effective user variable provides access to a single number that represents the effective user identifier (UID).

Example
print("Effective User ID is one UID: $>\n");

$EVAL_ERROR

Compliance
    
Syntax
Short Name:          $@
Scope:               localize
Definition

Perl allows explicit calls to the eval() function to evaluate Perl syntax with a Perl script. This variable allows access to the returned error after such an operation. The error is a string that contains the relevant error message.

Example
print "Passing eval a malformed Perl expression:\n";
eval 'print "Hello';

print "Error: $@\n";

$EXECUTABLE_NAME

Compliance
    
Syntax
Short Name:          $^X
Scope:               localize
Definition

This variable provides access to the name of the Perl executable used by the script.

Example
print "Executable name of Perl is: $^X\n";

$FORMAT_FORMFEED

Compliance
  
Syntax
Short Name:          $^L
Scope:               always global
File Handle Call:    format_formfeed FILEHANDLE EXPR
Definition

When you use the Perl formatting commands, you can specify formats to manipulate centering and other formatting of the text. One additional option is to specify the exact code to be inserted between pages of output in the file. The default value is a form-feed character (\f), but this can be changed.

Example
if ($^L = '\f')
{
print "The formfeed character is the default break
between pages.\n";
}

$FORMAT_LINES_LEFT

Compliance
    
Syntax
Short Name:          $-
Scope:               always global
File Handle Call:    format_lines_left FILEHANDLE EXPR
Definition

When you use the Perl formatting commands, this counter, which exists for each file handle with an associated format, is decremented every time a line is output until it reaches zero, when a new page is generated. You can manually set this variable to zero to force a page break in the output.

Example
format EG_FORMAT =
@<<<<<<<<<<  @|||||||||||| @>>>>>>>>> ^||||||||||
$one,      $two,         $three     $fitme
.
open(EG_FORMAT,">-");
select(EG_FORMAT);
$one = 'Left';
$two = 'Center';
$three = 'Right';
$fitme= "";
write;
$one = $-;
$two = $-;
$three = $-;
write;
$one = $-;
$two = $-;
$three = $-;
write;
select(STDOUT);

$FORMAT_LINES_PER_PAGE

Compliance
    
Syntax
Short Name:          $=
Scope:               always global
File Handle Call:    format_lines_per_page FILEHANDLE
EXPR
Definition

Each format file handle has an associated number of lines per page, which you can access and change by using this variable.

Example
select (EG_FORMAT);
$one = 'Left';
$two = 'Center';
$three = 'Right';
$fitme= "";
write;
$one = $=;
$two = $=;
$three = $=;
write;
select(STDOUT);

$FORMAT_LINE_BREAK_CHARACTERS

Compliance
    
Syntax
Short Name:          $:
Scope:               localize
File Handle Call:    format_line_break_characters
FILEHANDLE EXPR
Definition

When you are outputting a value to a formatted area by using the following format code

^||||||||||||||

(or the other multiple-line formats), the line-break character determines how strings are split into lines to fit into the formatted space. By default, the legal break characters are space, hyphen, and new line.

Example
select(EG_FORMAT);
$: = ' \n-';
$one = 1;
$two = 2;
$three = 3;
$fitme= "One-One-One-One-One-One";
write;
write;
write;
select(STDOUT);

$FORMAT_NAME

Compliance
    
Syntax
Short Name:          $~
Scope:               always global
File Handle Call:    format_name FILEHANDLE EXPR
Definition

Each format has a name, which may also be the name of the file handle. You can access the name directly through this variable.

Example
select(EG_FORMAT);
$one = $~;
$two = $~;
$three = $~;
write;
select(STDOUT);

$FORMAT_PAGE_NUMBER

Compliance
    
Syntax
Short Name:          $%
Scope:               always global
File Handle Call:    format_page_number FILEHANDLE EXPR
Definition

Because each format can produce multiple pages of output, this counter simply counts them.

Example
select(EG_FORMAT);
$one = $%;
$two = $%;
$three = $%;
write;
select(STDOUT);

$FORMAT_TOP_NAME

Compliance
    
Syntax
Short Name:          $^
Scope:               always global
File Handle Call:    format_top_name FILEHANDLE EXPR
Definition

Each format can have an associated format that is reproduced each time a new page is generated. (No equivalent automatic page footer exists.) By default, these are given the same name as the base format with a TOP suffix, although any name can be set.

Example
format EG_TOP =
           [Sample Page Header]
To the left  In the center To the right
------------------------------------
.
open(EG_FORMAT,">-");
select(EG_FORMAT);
$- = 0;
$^ = EG_TOP;
$one = '111';
$two = '222';
$three = '333';
$fitme= "";
write;
write;
write;
select(STDOUT);

$INPLACE_EDIT

Compliance
    
Syntax
Short Name:          $^I
Scope:               localize
Definition

Perl is often used to edit files, and sometimes, the input file is also the output file (the result replaces the original). In this case, you can specify (with command-line options) the suffix to be used for the temporary file created while the edits are in progress. You can set or simply access this value from within the script itself by using this variable.

Example
$^I=bak;
print "Tmp file extension when editing in place...
$^I\n";

$INPUT_LINE_NUMBER

Compliance
    
Syntax
Short Name:          $.
Intermediate Name:   $NR
Scope:               localize (read-only)
File Handle Call:    input_line_number FILEHANDLE EXPR
Definition

This variable counts the number of lines of input from a file and is reset when the file is closed. The variable counts lines cumulatively across all input files read with the <> construct because these are not closed explicitly.

Example
print "The last file read had $. lines\n";

$INPUT_RECORD_SEPARATOR

Compliance
    
Syntax
Short Name:          $/
Intermediate Name:   $RS
Scope:               localize
File Handle Call:    input_record_separator FILEHANDLE
EXPR
Definition

By default, an input file is split into records, each of which comprises one line. The
input-record separator is a newline character. This variable can be set to have no value (in which case entire input files are read in at the same time) or to have other values, as required.

Example
undef $/;
open(INFILE,"infile.tst");
$buffer = <INFILE>;
print "$buffer\n";

$LAST_PAREN_MATCH

Compliance
    
Syntax
Short Name:          $+
Scope:               local
Definition

This variable returns the value of the last pattern marked with parentheses. In most contexts, you could simply use $1, $2, and so on rather than $+. When the pattern has a series of sets of parentheses as alternatives to be matched, using $+ is useful.

Example
$_ = "AlphaBetaDeltaGamma";
/Alpha(.*)Delta(.*)/;
print "The last match was $+\n";

$LIST_SEPARATOR

Compliance
    
Syntax
Short Name:          $"
Scope:               localize
Definition

When arrays are converted to strings, the elements are separated by spaces by default, which, for example, is what happens when arrays are printed. This variable allows you to specify any string as the list separator, which may be useful for output formatting or for other reasons.

Example
$" = ' ! ';
@thisarray = (Alpha, Beta, Gamma);
print "@thisarray.\n";
$" = ' ';

$MATCH

Compliance
    
Syntax
Short Name:          $&
Scope:               local (read-only)
Definition

This variable references the entire pattern that matched the most recent pattern matching operation.

Example
$_ = "AlphaBetaGamma";
/B[aet]*/;
print "Matched: $&\n";

$MULTILINE_MATCHING

Compliance
    
Syntax
Short Name:          $*
Scope:               localize
Definition

By default, Perl optimizes pattern matching on the assumption that each pattern does not contain embedded new lines; that is, it is optimized for single-line matching. If you are using a pattern that has embedded new lines, you should set this variable to a value of 1 so that this optimization is disabled and the correct result is obtained.

Example
print("\nTest 26 Perl Version ($])\n");
$_ = "Alpha\nBeta\nGamma\n";
$* = 0; # Assume string comprises a single line
/^.*$/;
print "a) Assuming single line: $& ";
print "(which is wrong - the assumption was wrong).\n";
$* = 1; # Do not assume string comprises a single line
/^.*$/;
print "a) Not assuming single line: $& (which is correct).\n";
$* = 0;

$OFMT

Compliance
    
Syntax
Short Name:          $#
Scope:               localize
Definition

This variable mimics the UNIX awk utility variable of the same name, which permits numeric formatting. The default value is

%.2g

See the UNIX awk documentation for information about the possible values.

Example
$# = "%.6g";
print 5467.4567, "\n";
$# = "%.8g";
print 5467.4567, "\n";

Tip
Use of the $OFMT variable is discouraged. You can format values by using the print() function.

$OS_ERROR

Compliance
    
Syntax
Short Name:          $!
Intermediate Name:   $ERRNO
Scope:               localize
Definition

If an operating-system-error condition exists, this variable is set to the error number and, if it is evaluated in a string context, to the equivalent error message. You can manually set the error number and then access the relevant error message in a string context.

Example
ls -lgd /vir';
print "OS Error was $!\n";
šš See the $CHILD_ERROR variable for subprocess errors, which are not necessarily system errors,
p. 208

$OUTPUT_AUTOFLUSH

Compliance
    
Syntax
Short Name:          $|
Scope:               always global
File Handle Call:    autoflush FILEHANDLE EXPR
Definition

If this Boolean variable, which is associated with a file handle, has a nonzero value, that file is autoflushed (the output is written after each print or write operation) rather than buffered.

Tip
When the output file is a pipe, it is best to set autoflush on so that other programs can access the pipe immediately after each write or print operation.

Example
select(STDERR);
$| = 1;
select(STDOUT);
print "Autoflush setting for STDOUT is $|\n";

$OUTPUT_FIELD_SEPARATOR

Compliance
    
Syntax
Short Name:          $,
Intermediate Name:   $OFS
Scope:               localize
File Handle Call:    output_field_separator FILEHANDLE
EXPR
Definition

This variable can alter the behavior of the print() function. The default behavior of print(), when it is given a comma-separated list of arguments, is to print each argument with no output separator. You can use this variable to specify any string as a separator.

Example
$, = "=";
print STDOUT a, b, c, "\n";
$, = "";

$OUTPUT_RECORD_SEPARATOR

Compliance
    
Syntax
Short Name:          $\
Intermediate Name:   $ORS
Scope:               localize
File Handle Call:    output_record_separator FILEHANDLE EXPR
Definition

This variable can alter the behavior of the print() function. The default behavior of print(), when it is given a comma-separated list of arguments, is to print each argument. If a new line is required at the end, you must add it explicitly. You can use this record-separator variable to specify any string as the end-of-record string, and you most commonly set it to the newline character to avert the need for explicit new lines.

Example
$\ = "\n";
print "No need for an explicit new line now.";
$\ = "";

$PERLDB

Compliance
    
Syntax
Short Name:          $^P
Scope:               localize
Definition

This flag represents the debug level of the Perl script. Normally, $PERLDB is used internally by the debugger to disable debugging of the debugger script itself.

Example
print "Value of internal Boolean debug flag: $^P\n";

$PERL_VERSION

Compliance
    
Syntax
Short Name:          $]
Scope:               localize
Definition

This variable represents the version string that identifies the Perl version that is being run. You can assign a value to the variable, if necessary. In a numeric context, the variable evaluates to a number made up of the version plus the (patch level/1000).

Example
$ver = $]+0;
print "So every test has tested the version $] (numeric
$ver).\n";

$POSTMATCH

Compliance
    
Syntax
Short Name:          $'
Scope:               local (read-only)
Definition

When a string is matched by pattern, the pattern is actually split into three parts: the part of the string before the match, the part of the string that matched, and the part of the string after the match. Any of these parts could be empty, of course. This variable refers to the part of the string after the match.

Example
$_ = "AlphaBetaGamma";
/Beta/;
print "Postmatch = $'\n";

$PREMATCH

Compliance

    

Syntax
Short Name:          $'
Scope:               local (read-only)
Definition

When a string is matched by pattern, the pattern is actually split into three parts: the part of the string before the match, the part of the string that matched, and the part of the string after the match. Any of these parts could be empty, of course. This variable refers to the part of the string before the match.

Example
$_ = "AlphaBetaGamma";
/Beta/;
print "Prematch = $`\n";

$PROCESS_ID

Compliance
    
Syntax
Short Name:          $$
Intermediate Name:   $PID

Scope:               localize

Definition

In systems that support multiple processes, Perl can identify the process number of the Perl script current process (i.e. the process that is executing the Perl script itself) via this variable.

Example
print "The process ID (PID) is: $$\n";

$PROGRAM_NAME

Compliance
    
Syntax
Short Name:          $0
Scope:               localize
Definition

This variable contains the name of the Perl script that is being executed. You can alter this variable if you want the script to identify itself to the operating system as having a particular name.

Example
print "The program name is: $0\n";

$REAL_GROUP_ID

Compliance
    
Syntax
Short Name:          $(
Intermediate Name:   $GID
Scope:               localize
Definition

In systems that support users and groups, as well as setting new users and groups within a process, Perl can access both the original and the effective user and group information. The real group variable provides access to a list of numbers that represent the real group identifiers (GIDs). Effective GIDs may be set using flags in the script or explicit calls to functions. This will not alter the real GIDs.

Example
print("The Real Group ID is a list of GIDs: $(\n");

$REAL_USER_ID

Compliance
    
Syntax
Short Name:          $<
Intermediate Name:   $UID
Scope:               localize
Definition

In systems that support users and groups, as well as setting new users and groups within a process, Perl can access both the original and the effective user and group information. The real user variable provides access to a list of numbers that represent the real user identifier (UID). An effective UID may be set by flags on the script or explicit calls to functions. This does not alter the real UID.

Example
print("The Real User ID is a list of UID: $<\n");

$SUBSCRIPT_SEPARATOR

Compliance
    
Syntax
Short Name:          $;
Intermediate Name:   $SUBSEP
Scope:               localize
Definition

This variable is used in emulating multidimensional arrays. The value must be one that is not used by any element in the array. The default value is \034.

Perl 5 directly supports multidimensional arrays directly, so the use of $SUBSCRIPT_SEPARATOR ($;) is not necessary.

$SYSTEM_FD_MAX

Compliance
    
Syntax
FACE="Courier">Short Name:          $^F
Scope:               localize
Definition

By default, Perl treats three files as system files: 0, 1, and 2 normally, STDIN, STDOUT, and STDERR. The value of $^F is 2 by default. System files are treated specially; in particular, the file descriptors are passed to exec() processes.

Thus, file descriptors that number greater than $^F are automatically closed to child processes.

Example
print "The default maximum file descriptors is $^F\n";

$WARNING

Compliance
    
Syntax
Short Name:          $^W
Scope:               localize
Definition

This variable is a Boolean warning flag that you normally set to true by using the
command-line -w switch, although you can set it within the script, if necessary. When this variable is on, the Perl program reports more verbose warnings.

Example
print "Boolean warning flag is set to: $^W\n";

%ENV{<variable_name>,<variable_value>}

Compliance
    
Syntax
Short Name:         
%ENV{<variable_name>,<variable_value>}
Scope:               always global
Definition

This variable is an associative array that links the names of the environment variables to their values. This variable makes it easy to look up a value with the appropriate name.

Example
$tmp = $ENV{SHELL};
print "The current SHELL is set to $tmp\n";

%INC{<filename>,<file-load-status>}

Compliance
    
Syntax
Short Name:          %INC{<file-name>,<file-load-status>}
Scope:               always global
Definition

This variable is an associate array that links the names of the required files to a status (whether they were successfully loaded). Normally, the Perl script itself uses this array to determine whether files have already been loaded so as to minimize the number of file loads that are carried out.

Example
require 'another.pl';
$tmp = $INC{'another.pl'};
print "The required file did exist: $tmp\n";

%SIG{<signal-name>,<signal-value>}

Compliance
    
Syntax
Short Name:          %SIG{<signal-name>,<signal-value>}
Scope:               always global
Definition

This variable is an associative array that links the standard signals to values. These values dictate the way that the script processes those signals. You can assign signal-handling subroutines to certain signals or set the script to ignore certain signals.

Example
$SIG{'HUP'} = 'IGNORE';
print "This process now ignores hangup signals.\n";

@ARGV[<N>]

Compliance
    
Syntax
Short Name: