This is Info file perl.info, produced by Makeinfo version 1.68 from the
input file bigperl.texi.
settitle perl
File: perl.info, Node: perlref, Next: perldsc, Prev: perlreftut, Up: Top
Perl references and nested data structures
******************************************
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 *Note
Perlreftut: perlreftut,.
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"', *Note Perlobj: perlobj, for a detailed explanation.)
If that thing happens to be an object, the object is destructed. See
`"Two-Phased Garbage Collection"', *Note Perlobj: perlobj, 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 of 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 *Note Perlobj: perlobj,.
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};
All of these are self-explanatory except for `*foo{IO}'. It returns
the IO handle, used for file handles (`open', *Note Perlfunc:
perlfunc,), sockets (`socket', *Note Perlfunc: perlfunc, and
`socketpair', *Note Perlfunc: perlfunc,), and directory handles
(`opendir', *Note Perlfunc: perlfunc,). For compatibility with
previous versions of Perl, `*foo{FILEHANDLE}' is a synonym for
`*foo{IO}'.
`*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"', *Note Perldata: perldata, 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 *Note Perlobj: perlobj,, 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', *Note Perlfunc: perlfunc, 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 *Note
Perlobj: perlobj,.
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.
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
*Note Fields: (pm.info)fields,.
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, a closure is an anonymous function with access to
the lexical variables visible when that function was compiled. 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 { "@_" };
}
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 ($) { "$_[0]" };
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. 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 *Note Perldsc: perldsc, and *Note Perllol: perllol, for how to
use references to create complex data structures, and *Note Perltoot:
perltoot,, *Note Perlobj: perlobj,, and *Note Perlbot: perlbot, for how to
use them to create objects.
File: perl.info, Node: perlreftut, Next: perlref, Prev: perllocale, Up: Top
Mark's very short tutorial about references
*******************************************
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: 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 "Bill Clinton".
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 "Bill Clinton", 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
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'.
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*
If `$aref' contains a reference to an array, then you can put `{$aref}'
anywhere you would normally put 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', and the right-hand versions operate on
the array that is referred to by `$aref', but once they find the array
they're operating on, they 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
*Use Rule 2*
`${$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.
Most often, when you have an array or a hash, you want to get or set a
single element from it. `${$aref}[3]' and `${$href}{'red'}' have too much
punctuation, and Perl lets you abbreviate.
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] >>, we can write `$a[0][1]'; 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 while (<>) {
2 chomp;
3 my ($city, $country) = split /, /;
4 push @{$table{$country}}, $city;
5 }
6
7 foreach $country (sort keys %table) {
8 print "$country: ";
9 my @cities = @{$table{$country}};
10 print join ', ', sort @cities;
11 print ".\n";
12 }
The program has two pieces: Lines 1-5 read the input and build a data
structure, and lines 7-12 analyze the data and print out the report.
In the first part, line 4 is the important one. We're going to have a
hash, `%table', whose keys are country names, and whose values are
(references to) arrays of city names. After acquiring a city and country
name, the program looks up `$table{$country}', which holds (a reference
to) the list of cities seen in that country so far. Line 4 is totally
analogous to
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.
In the second part, line 9 is the important one. Again,
`$table{$country}' is (a reference to) the list of cities in the country,
so we can recover the original list, and copy it into the array `@cities',
by using `@{$table{$country}}'. Line 9 is totally analogous to
@cities = @array;
except that the name array has been replaced by the reference
`{$table{$country}}'. The `@' tells Perl to get the entire array.
The rest of the program is just familiar uses of chomp, split, sort,
print, and doesn't involve references at all.
There's one fine point I skipped. Suppose the program has just read
the first line in its input that happens to mention Greece. Control is at
line 4, `$country' is `'Greece'', and `$city' is `'Athens''. Since this
is the first city in Greece, `$table{$country}' is undefined--in fact
there isn't an `'Greece'' key in `%table' at all. What does line 4 do
here?
4 push @{$table{$country}}, $city;
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 in the table, and then
pushes `Athens' onto it. This is called `autovivification'.
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 *Note Perlref:
perlref, manual page, which discusses 100% of the details.
Some of the highlights of *Note Perlref: perlref,:
* 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.
* 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*.
You might prefer to go on to *Note Perllol: perllol, instead of *Note
Perlref: perlref,; it discusses lists of lists and multidimensional arrays
in detail. After that, you should move on to *Note Perldsc: perldsc,;
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://tpj.com)
volume 3, #2. Reprinted with permission.
The original title was *Understand References Today*.
Distribution Conditions
-----------------------
Copyright 1998 The Perl Journal.
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 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.
File: perl.info, Node: perlrun, Next: perlfunc, Prev: perlre, Up: Top
how to execute the Perl interpreter
***********************************
NAME
====
perlrun - how to execute the Perl interpreter
SYNOPSIS
========
*perl* [ *-CsTuUWX* ] [ *-hv* ] [ -V[:*configvar*] ]
[ *-cw* ] [ -d[:*debugger*] ] [ -D[*number/list*] ]
[ *-pna* ] [ -Fpattern ] [ -l[*octal*] ] [ -0[*octal*] ]
[ -Idir ] [ -m[-]module ] [ -M[-]*'module...'* ] [ -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 *Note Perldebug: perldebug, 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' in this node.)
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 -0digits 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
`ALTERNATIVE_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
A Macintosh perl program will have the appropriate Creator and Type,
so that double-clicking them will invoke the perl application.
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 Plan9 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 "Hello world\n""
*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[digits]
specifies the input record separator ($/) as an octal 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 character with that value.
-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
enables Perl to use the native wide character APIs on the target
system. The magic variable `${^WIDE_SYSTEM_CALLS}' reflects the
state of this switch. See `"${^WIDE_SYSTEM_CALLS}"', *Note Perlvar:
perlvar,.
This feature is currently only implemented on the Win32 platform.
-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
runs the program under the Perl debugger. See *Note Perldebug:
perldebug,.
*-d:*foo
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. See *Note Perldebug:
perldebug,.
-Dletters
-Dnumber
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. 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
4 l Context (loop) stack processing
8 t Trace execution
16 o Method and overloading resolution
32 c String/numeric conversions
64 P Print preprocessor command for -P
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 L Memory leaks (needs -DLEAKTEST when compiling Perl)
8192 H Hash dump -- usurps values()
16384 X Scratchpad allocation
32768 D Cleaning up
65536 S Thread synchronization
All these flags require *-DDEBUGGING* when you compile the Perl
executable. 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
# 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 *Note Perldebug: perldebug, 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.
-Fpattern
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.
-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', *Note Perlfunc: perlfunc,).
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?', *Note Perlfaq5:
perlfaq5,.
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...
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.
-Idirectory
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]...*
-mmodule executes use module `();' before executing your program.
-Mmodule 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.
-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 older than 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
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
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".)
-s
enables rudimentary switch parsing for switches on the command line
after the program name but before any filename arguments (or before a
-). 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" }
-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 #!. 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
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
*Note Perlsec: perlsec, 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 *Note B: (pm.info)B, and
*Note B/Bytecode: (pm.info)B/Bytecode, for details.
-U
allows Perl to do unsafe operations. Currently the only "unsafe"
operations are the unlinking of 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:*name
Prints to STDOUT the value of the named configuration variable. For
example,
$ perl -V:man.dir
will provide strong clues about what your MANPATH variable should be
set to in order to access the Perl documentation.
-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 doesn'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 *Note Perlvar: perlvar, and `warn',
*Note Perlfunc: perlfunc,. See also `warn', *Note Perldiag:
perldiag, and `warn', *Note Perltrap: perltrap,. A new, fine-grained
warning facility is also available if you want to manipulate entire
classes of warnings; see `warn', *Note Warnings: (pm.info)warnings,
or `warn', *Note Perllexwarn: perllexwarn,.
-W
Enables all warnings regardless of `no warnings' or $^W. See *Note
Perllexwarn: perllexwarn,.
-X
Disables all warnings regardless of `use warnings' or $^W. See *Note
Perllexwarn: perllexwarn,.
-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 colon-separated 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.
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 *-[DIMUdmw]*
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.
PERLLIB
A colon-separated 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' }
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/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_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.
Perl also has environment variables that control how Perl handles data
specific to particular natural languages. See *Note Perllocale:
perllocale,.
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)};