=head1 NAME
-perlfaq7 - Perl Language Issues ($Revision: 1.15 $)
+perlfaq7 - General Perl Language Issues
=head1 DESCRIPTION
=head2 Can I get a BNF/yacc/RE for the Perl language?
-No, in the words of Chaim Frenkel: "Perl's grammar can not be reduced
-to BNF. The work of parsing perl is distributed between yacc, the
-lexer, smoke and mirrors."
+There is no BNF, but you can paw your way through the yacc grammar in
+perly.y in the source distribution if you're particularly brave. The
+grammar relies on very smart tokenizing code, so be prepared to
+venture into toke.c as well.
-=head2 What are all these $@%* punctuation signs, and how do I know when to use them?
+In the words of Chaim Frenkel: "Perl's grammar can not be reduced to BNF.
+The work of parsing perl is distributed between yacc, the lexer, smoke
+and mirrors."
-They are type specifiers, as detailed in L<perldata>:
+=head2 What are all these $@%&* punctuation signs, and how do I know when to use them?
- $ for scalar values (number, string or reference)
- @ for arrays
- % for hashes (associative arrays)
- * for all types of that symbol name. In version 4 you used them like
- pointers, but in modern perls you can just use references.
+They are type specifiers, as detailed in L<perldata>:
-While there are a few places where you don't actually need these type
-specifiers, you should always use them.
+ $ for scalar values (number, string or reference)
+ @ for arrays
+ % for hashes (associative arrays)
+ & for subroutines (aka functions, procedures, methods)
+ * for all types of that symbol name. In version 4 you used them like
+ pointers, but in modern perls you can just use references.
-A couple of others that you're likely to encounter that aren't
-really type specifiers are:
+There are couple of other symbols that you're likely to encounter that aren't
+really type specifiers:
- <> are used for inputting a record from a filehandle.
- \ takes a reference to something.
+ <> are used for inputting a record from a filehandle.
+ \ takes a reference to something.
-Note that E<lt>FILEE<gt> is I<neither> the type specifier for files
-nor the name of the handle. It is the C<E<lt>E<gt>> operator applied
-to the handle FILE. It reads one line (well, record - see
-L<perlvar/$/>) from the handle FILE in scalar context, or I<all> lines
+Note that <FILE> is I<neither> the type specifier for files
+nor the name of the handle. It is the C<< <> >> operator applied
+to the handle FILE. It reads one line (well, record--see
+L<perlvar/$E<sol>>) from the handle FILE in scalar context, or I<all> lines
in list context. When performing open, close, or any other operation
-besides C<E<lt>E<gt>> on files, or even talking about the handle, do
+besides C<< <> >> on files, or even when talking about the handle, do
I<not> use the brackets. These are correct: C<eof(FH)>, C<seek(FH, 0,
2)> and "copying from STDIN to FILE".
Normally, a bareword doesn't need to be quoted, but in most cases
probably should be (and must be under C<use strict>). But a hash key
consisting of a simple word (that isn't the name of a defined
-subroutine) and the left-hand operand to the C<=E<gt>> operator both
+subroutine) and the left-hand operand to the C<< => >> operator both
count as though they were quoted:
- This is like this
- ------------ ---------------
- $foo{line} $foo{"line"}
- bar => stuff "bar" => stuff
+ This is like this
+ ------------ ---------------
+ $foo{line} $foo{'line'}
+ bar => stuff 'bar' => stuff
The final semicolon in a block is optional, as is the final comma in a
list. Good style (see L<perlstyle>) says to put them in except for
one-liners:
- if ($whoops) { exit 1 }
- @nums = (1, 2, 3);
+ if ($whoops) { exit 1 }
+ @nums = (1, 2, 3);
- if ($whoops) {
- exit 1;
- }
- @lines = (
+ if ($whoops) {
+ exit 1;
+ }
+
+ @lines = (
"There Beren came from mountains cold",
"And lost he wandered under leaves",
- );
+ );
=head2 How do I skip some return values?
One way is to treat the return values as a list and index into it:
- $dir = (getpwnam($user))[7];
+ $dir = (getpwnam($user))[7];
Another way is to use undef as an element on the left-hand-side:
- ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
+ ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
+
+You can also use a list slice to select only the elements that
+you need:
+
+ ($dev, $ino, $uid, $gid) = ( stat($file) )[0,1,4,5];
=head2 How do I temporarily block warnings?
-The C<$^W> variable (documented in L<perlvar>) controls
-runtime warnings for a block:
+If you are running Perl 5.6.0 or better, the C<use warnings> pragma
+allows fine control of what warning are produced.
+See L<perllexwarn> for more details.
+
+ {
+ no warnings; # temporarily turn off warnings
+ $a = $b + $c; # I know these might be undef
+ }
+
+Additionally, you can enable and disable categories of warnings.
+You turn off the categories you want to ignore and you can still
+get other categories of warnings. See L<perllexwarn> for the
+complete details, including the category names and hierarchy.
+
+ {
+ no warnings 'uninitialized';
+ $a = $b + $c;
+ }
- {
+If you have an older version of Perl, the C<$^W> variable (documented
+in L<perlvar>) controls runtime warnings for a block:
+
+ {
local $^W = 0; # temporarily turn off warnings
$a = $b + $c; # I know these might be undef
- }
+ }
Note that like all the punctuation variables, you cannot currently
use my() on C<$^W>, only local().
-A new C<use warnings> pragma is in the works to provide finer control
-over all this. The curious should check the perl5-porters mailing list
-archives for details.
-
=head2 What's an extension?
-A way of calling compiled C code from Perl. Reading L<perlxstut>
-is a good place to learn more about extensions.
+An extension is a way of calling compiled C code from Perl. Reading
+L<perlxstut> is a good place to learn more about extensions.
=head2 Why do Perl operators have different precedence than C operators?
Actually, they don't. All C operators that Perl copies have the same
precedence in Perl as they do in C. The problem is with operators that C
doesn't have, especially functions that give a list context to everything
-on their right, eg print, chmod, exec, and so on. Such functions are
+on their right, eg. print, chmod, exec, and so on. Such functions are
called "list operators" and appear as such in the precedence table in
L<perlop>.
A common mistake is to write:
- unlink $file || die "snafu";
+ unlink $file || die "snafu";
This gets interpreted as:
- unlink ($file || die "snafu");
+ unlink ($file || die "snafu");
To avoid this problem, either put in extra parentheses or use the
super low precedence C<or> operator:
- (unlink $file) || die "snafu";
- unlink $file or die "snafu";
+ (unlink $file) || die "snafu";
+ unlink $file or die "snafu";
The "English" operators (C<and>, C<or>, C<xor>, and C<not>)
deliberately have precedence lower than that of list operators for
just such situations as the one above.
Another operator with surprising precedence is exponentiation. It
-binds more tightly even than unary minus, making C<-2**2> product a
+binds more tightly even than unary minus, making C<-2**2> produce a
negative not a positive four. It is also right-associating, meaning
that C<2**3**2> is two raised to the ninth power, not eight squared.
+Although it has the same precedence as in C, Perl's C<?:> operator
+produces an lvalue. This assigns $x to either $a or $b, depending
+on the trueness of $maybe:
+
+ ($maybe ? $a : $b) = $x;
+
=head2 How do I declare/create a structure?
In general, you don't "declare" a structure. Just use a (probably
anonymous) hash reference. See L<perlref> and L<perldsc> for details.
Here's an example:
- $person = {}; # new anonymous hash
- $person->{AGE} = 24; # set field AGE to 24
- $person->{NAME} = "Nat"; # set field NAME to "Nat"
+ $person = {}; # new anonymous hash
+ $person->{AGE} = 24; # set field AGE to 24
+ $person->{NAME} = "Nat"; # set field NAME to "Nat"
If you're looking for something a bit more rigorous, try L<perltoot>.
=head2 How do I create a module?
-A module is a package that lives in a file of the same name. For
-example, the Hello::There module would live in Hello/There.pm. For
-details, read L<perlmod>. You'll also find L<Exporter> helpful. If
-you're writing a C or mixed-language module with both C and Perl, then
-you should study L<perlxstut>.
+(contributed by brian d foy)
-Here's a convenient template you might wish you use when starting your
-own module. Make sure to change the names appropriately.
+L<perlmod>, L<perlmodlib>, L<perlmodstyle> explain modules
+in all the gory details. L<perlnewmod> gives a brief
+overview of the process along with a couple of suggestions
+about style.
- package Some::Module; # assumes Some/Module.pm
+If you need to include C code or C library interfaces in
+your module, you'll need h2xs. h2xs will create the module
+distribution structure and the initial interface files
+you'll need. L<perlxs> and L<perlxstut> explain the details.
- use strict;
+If you don't need to use C code, other tools such as
+ExtUtils::ModuleMaker and Module::Starter, can help you
+create a skeleton module distribution.
- BEGIN {
- use Exporter ();
- use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
+You may also want to see Sam Tregar's "Writing Perl Modules
+for CPAN" ( http://apress.com/book/bookDisplay.html?bID=14 )
+which is the best hands-on guide to creating module
+distributions.
- ## set the version for version checking; uncomment to use
- ## $VERSION = 1.00;
+=head2 How do I adopt or take over a module already on CPAN?
- # if using RCS/CVS, this next line may be preferred,
- # but beware two-digit versions.
- $VERSION = do{my@r=q$Revision: 1.15 $=~/\d+/g;sprintf '%d.'.'%02d'x$#r,@r};
+(contributed by brian d foy)
- @ISA = qw(Exporter);
- @EXPORT = qw(&func1 &func2 &func3);
- %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
+The easiest way to take over a module is to have the current
+module maintainer either make you a co-maintainer or transfer
+the module to you.
- # your exported package globals go here,
- # as well as any optionally exported functions
- @EXPORT_OK = qw($Var1 %Hashit);
- }
- use vars @EXPORT_OK;
+If you can't reach the author for some reason (e.g. email bounces),
+the PAUSE admins at modules@perl.org can help. The PAUSE admins
+treat each case individually.
- # non-exported package globals go here
- use vars qw( @more $stuff );
+=over 4
- # initialize package globals, first exported ones
- $Var1 = '';
- %Hashit = ();
+=item
- # then the others (which are still accessible as $Some::Module::stuff)
- $stuff = '';
- @more = ();
+Get a login for the Perl Authors Upload Server (PAUSE) if you don't
+already have one: http://pause.perl.org
- # all file-scoped lexicals must be created before
- # the functions below that use them.
+=item
- # file-private lexicals go here
- my $priv_var = '';
- my %secret_hash = ();
+Write to modules@perl.org explaining what you did to contact the
+current maintainer. The PAUSE admins will also try to reach the
+maintainer.
- # here's a file-private function as a closure,
- # callable as &$priv_func; it cannot be prototyped.
- my $priv_func = sub {
- # stuff goes here.
- };
+=item
- # make all your functions, whether exported or not;
- # remember to put something interesting in the {} stubs
- sub func1 {} # no prototype
- sub func2() {} # proto'd void
- sub func3($$) {} # proto'd to 2 scalars
+Post a public message in a heavily trafficked site announcing your
+intention to take over the module.
- # this one isn't exported, but could be called!
- sub func4(\%) {} # proto'd to 1 hash ref
+=item
- END { } # module clean-up code here (global destructor)
+Wait a bit. The PAUSE admins don't want to act too quickly in case
+the current maintainer is on holiday. If there's no response to
+private communication or the public post, a PAUSE admin can transfer
+it to you.
- 1; # modules must return true
+=back
=head2 How do I create a class?
+X<class, creation> X<package>
-See L<perltoot> for an introduction to classes and objects, as well as
-L<perlobj> and L<perlbot>.
+(contributed by brian d foy)
-=head2 How can I tell if a variable is tainted?
+In Perl, a class is just a package, and methods are just subroutines.
+Perl doesn't get more formal than that and lets you set up the package
+just the way that you like it (that is, it doesn't set up anything for
+you).
-See L<perlsec/"Laundering and Detecting Tainted Data">. Here's an
-example (which doesn't use any system calls, because the kill()
-is given no processes to signal):
+The Perl documentation has several tutorials that cover class
+creation, including L<perlboot> (Barnyard Object Oriented Tutorial),
+L<perltoot> (Tom's Object Oriented Tutorial), L<perlbot> (Bag o'
+Object Tricks), and L<perlobj>.
- sub is_tainted {
- return ! eval { join('',@_), kill 0; 1; };
- }
+=head2 How can I tell if a variable is tainted?
-This is not C<-w> clean, however. There is no C<-w> clean way to
-detect taintedness - take this as a hint that you should untaint
-all possibly-tainted data.
+You can use the tainted() function of the Scalar::Util module, available
+from CPAN (or included with Perl since release 5.8.0).
+See also L<perlsec/"Laundering and Detecting Tainted Data">.
=head2 What's a closure?
Closures are documented in L<perlref>.
I<Closure> is a computer science term with a precise but
-hard-to-explain meaning. Closures are implemented in Perl as anonymous
-subroutines with lasting references to lexical variables outside their
-own scopes. These lexicals magically refer to the variables that were
-around when the subroutine was defined (deep binding).
-
-Closures make sense in any programming language where you can have the
-return value of a function be itself a function, as you can in Perl.
-Note that some languages provide anonymous functions but are not
-capable of providing proper closures; the Python language, for
+hard-to-explain meaning. Usually, closures are implemented in Perl as
+anonymous subroutines with lasting references to lexical variables
+outside their own scopes. These lexicals magically refer to the
+variables that were around when the subroutine was defined (deep
+binding).
+
+Closures are most often used in programming languages where you can
+have the return value of a function be itself a function, as you can
+in Perl. Note that some languages provide anonymous functions but are
+not capable of providing proper closures: the Python language, for
example. For more information on closures, check out any textbook on
functional programming. Scheme is a language that not only supports
but encourages closures.
-Here's a classic function-generating function:
+Here's a classic non-closure function-generating function:
- sub add_function_generator {
- return sub { shift + shift };
- }
+ sub add_function_generator {
+ return sub { shift() + shift() };
+ }
- $add_sub = add_function_generator();
- $sum = &$add_sub(4,5); # $sum is 9 now.
+ $add_sub = add_function_generator();
+ $sum = $add_sub->(4,5); # $sum is 9 now.
-The closure works as a I<function template> with some customization
-slots left out to be filled later. The anonymous subroutine returned
-by add_function_generator() isn't technically a closure because it
-refers to no lexicals outside its own scope.
+The anonymous subroutine returned by add_function_generator() isn't
+technically a closure because it refers to no lexicals outside its own
+scope. Using a closure gives you a I<function template> with some
+customization slots left out to be filled later.
Contrast this with the following make_adder() function, in which the
returned anonymous function contains a reference to a lexical variable
that Perl return a proper closure, thus locking in for all time the
value that the lexical had when the function was created.
- sub make_adder {
- my $addpiece = shift;
- return sub { shift + $addpiece };
- }
+ sub make_adder {
+ my $addpiece = shift;
+ return sub { shift() + $addpiece };
+ }
- $f1 = make_adder(20);
- $f2 = make_adder(555);
+ $f1 = make_adder(20);
+ $f2 = make_adder(555);
Now C<&$f1($n)> is always 20 plus whatever $n you pass in, whereas
C<&$f2($n)> is always 555 plus whatever $n you pass in. The $addpiece
Closures are often used for less esoteric purposes. For example, when
you want to pass in a bit of code into a function:
- my $line;
- timeout( 30, sub { $line = <STDIN> } );
+ my $line;
+ timeout( 30, sub { $line = <STDIN> } );
+
+If the code to execute had been passed in as a string,
+C<< '$line = <STDIN>' >>, there would have been no way for the
+hypothetical timeout() function to access the lexical variable
+$line back in its caller's scope.
+
+Another use for a closure is to make a variable I<private> to a
+named subroutine, e.g. a counter that gets initialized at creation
+time of the sub and can only be modified from within the sub.
+This is sometimes used with a BEGIN block in package files to make
+sure a variable doesn't get meddled with during the lifetime of the
+package:
+
+ BEGIN {
+ my $id = 0;
+ sub next_id { ++$id }
+ }
+
+This is discussed in more detail in L<perlsub>, see the entry on
+I<Persistent Private Variables>.
+
+=head2 What is variable suicide and how can I prevent it?
+
+This problem was fixed in perl 5.004_05, so preventing it means upgrading
+your version of perl. ;)
+
+Variable suicide is when you (temporarily or permanently) lose the value
+of a variable. It is caused by scoping through my() and local()
+interacting with either closures or aliased foreach() iterator variables
+and subroutine arguments. It used to be easy to inadvertently lose a
+variable's value this way, but now it's much harder. Take this code:
+
+ my $f = 'foo';
+ sub T {
+ while ($i++ < 3) { my $f = $f; $f .= "bar"; print $f, "\n" }
+ }
+
+ T;
+ print "Finally $f\n";
+
+If you are experiencing variable suicide, that C<my $f> in the subroutine
+doesn't pick up a fresh copy of the C<$f> whose value is <foo>. The output
+shows that inside the subroutine the value of C<$f> leaks through when it
+shouldn't, as in this output:
+
+ foobar
+ foobarbar
+ foobarbarbar
+ Finally foo
-If the code to execute had been passed in as a string, C<'$line =
-E<lt>STDINE<gt>'>, there would have been no way for the hypothetical
-timeout() function to access the lexical variable $line back in its
-caller's scope.
+The $f that has "bar" added to it three times should be a new C<$f>
+C<my $f> should create a new lexical variable each time through the loop.
+The expected output is:
-=head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regexp}?
+ foobar
+ foobar
+ foobar
+ Finally foo
-With the exception of regexps, you need to pass references to these
+=head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
+
+With the exception of regexes, you need to pass references to these
objects. See L<perlsub/"Pass by Reference"> for this particular
question, and L<perlref> for information on references.
+See "Passing Regexes", later in L<perlfaq7>, for information on
+passing regular expressions.
+
=over 4
=item Passing Variables and Functions
-Regular variables and functions are quite easy: just pass in a
+Regular variables and functions are quite easy to pass: just pass in a
reference to an existing or anonymous variable or function:
- func( \$some_scalar );
+ func( \$some_scalar );
- func( \$some_array );
- func( [ 1 .. 10 ] );
+ func( \@some_array );
+ func( [ 1 .. 10 ] );
- func( \%some_hash );
- func( { this => 10, that => 20 } );
+ func( \%some_hash );
+ func( { this => 10, that => 20 } );
- func( \&some_func );
- func( sub { $_[0] ** $_[1] } );
+ func( \&some_func );
+ func( sub { $_[0] ** $_[1] } );
=item Passing Filehandles
-To create filehandles you can pass to subroutines, you can use C<*FH>
-or C<\*FH> notation ("typeglobs" - see L<perldata> for more information),
-or create filehandles dynamically using the old FileHandle or the new
-IO::File modules, both part of the standard Perl distribution.
-
- use Fcntl;
- use IO::File;
- my $fh = new IO::File $filename, O_WRONLY|O_APPEND;
- or die "Can't append to $filename: $!";
- func($fh);
-
-=item Passing Regexps
-
-To pass regexps around, you'll need to either use one of the highly
-experimental regular expression modules from CPAN (Nick Ing-Simmons's
-Regexp or Ilya Zakharevich's Devel::Regexp), pass around strings
-and use an exception-trapping eval, or else be be very, very clever.
-Here's an example of how to pass in a string to be regexp compared:
-
- sub compare($$) {
- my ($val1, $regexp) = @_;
- my $retval = eval { $val =~ /$regexp/ };
- die if $@;
- return $retval;
- }
+As of Perl 5.6, you can represent filehandles with scalar variables
+which you treat as any other scalar.
+
+ open my $fh, $filename or die "Cannot open $filename! $!";
+ func( $fh );
- $match = compare("old McDonald", q/d.*D/);
+ sub func {
+ my $passed_fh = shift;
-Make sure you never say something like this:
+ my $line = <$passed_fh>;
+ }
- return eval "\$val =~ /$regexp/"; # WRONG
+Before Perl 5.6, you had to use the C<*FH> or C<\*FH> notations.
+These are "typeglobs"--see L<perldata/"Typeglobs and Filehandles">
+and especially L<perlsub/"Pass by Reference"> for more information.
-or someone can sneak shell escapes into the regexp due to the double
-interpolation of the eval and the double-quoted string. For example:
+=item Passing Regexes
- $pattern_of_evil = 'danger ${ system("rm -rf * &") } danger';
+To pass regexes around, you'll need to be using a release of Perl
+sufficiently recent as to support the C<qr//> construct, pass around
+strings and use an exception-trapping eval, or else be very, very clever.
- eval "\$string =~ /$pattern_of_evil/";
+Here's an example of how to pass in a string to be regex compared
+using C<qr//>:
-Those preferring to be very, very clever might see the O'Reilly book,
-I<Mastering Regular Expressions>, by Jeffrey Friedl. Page 273's
-Build_MatchMany_Function() is particularly interesting. A complete
-citation of this book is given in L<perlfaq2>.
+ sub compare($$) {
+ my ($val1, $regex) = @_;
+ my $retval = $val1 =~ /$regex/;
+ return $retval;
+ }
+ $match = compare("old McDonald", qr/d.*D/i);
=item Passing Methods
To pass an object method into a subroutine, you can do this:
- call_a_lot(10, $some_obj, "methname")
- sub call_a_lot {
- my ($count, $widget, $trick) = @_;
- for (my $i = 0; $i < $count; $i++) {
- $widget->$trick();
- }
- }
+ call_a_lot(10, $some_obj, "methname")
+ sub call_a_lot {
+ my ($count, $widget, $trick) = @_;
+ for (my $i = 0; $i < $count; $i++) {
+ $widget->$trick();
+ }
+ }
-or you can use a closure to bundle up the object and its method call
-and arguments:
+Or, you can use a closure to bundle up the object, its
+method call, and arguments:
- my $whatnot = sub { $some_obj->obfuscate(@args) };
- func($whatnot);
- sub func {
- my $code = shift;
- &$code();
- }
+ my $whatnot = sub { $some_obj->obfuscate(@args) };
+ func($whatnot);
+ sub func {
+ my $code = shift;
+ &$code();
+ }
You could also investigate the can() method in the UNIVERSAL class
(part of the standard perl distribution).
=head2 How do I create a static variable?
-As with most things in Perl, TMTOWTDI. What is a "static variable" in
-other languages could be either a function-private variable (visible
-only within a single function, retaining its value between calls to
-that function), or a file-private variable (visible only to functions
-within the file it was declared in) in Perl.
+(contributed by brian d foy)
+
+In Perl 5.10, declare the variable with C<state>. The C<state>
+declaration creates the lexical variable that persists between calls
+to the subroutine:
+
+ sub counter { state $count = 1; $counter++ }
+
+You can fake a static variable by using a lexical variable which goes
+out of scope. In this example, you define the subroutine C<counter>, and
+it uses the lexical variable C<$count>. Since you wrap this in a BEGIN
+block, C<$count> is defined at compile-time, but also goes out of
+scope at the end of the BEGIN block. The BEGIN block also ensures that
+the subroutine and the value it uses is defined at compile-time so the
+subroutine is ready to use just like any other subroutine, and you can
+put this code in the same place as other subroutines in the program
+text (i.e. at the end of the code, typically). The subroutine
+C<counter> still has a reference to the data, and is the only way you
+can access the value (and each time you do, you increment the value).
+The data in chunk of memory defined by C<$count> is private to
+C<counter>.
+
+ BEGIN {
+ my $count = 1;
+ sub counter { $count++ }
+ }
-Here's code to implement a function-private variable:
+ my $start = counter();
- BEGIN {
- my $counter = 42;
- sub prev_counter { return --$counter }
- sub next_counter { return $counter++ }
- }
+ .... # code that calls counter();
-Now prev_counter() and next_counter() share a private variable $counter
-that was initialized at compile time.
+ my $end = counter();
-To declare a file-private variable, you'll still use a my(), putting
-it at the outer scope level at the top of the file. Assume this is in
-file Pax.pm:
+In the previous example, you created a function-private variable
+because only one function remembered its reference. You could define
+multiple functions while the variable is in scope, and each function
+can share the "private" variable. It's not really "static" because you
+can access it outside the function while the lexical variable is in
+scope, and even create references to it. In this example,
+C<increment_count> and C<return_count> share the variable. One
+function adds to the value and the other simply returns the value.
+They can both access C<$count>, and since it has gone out of scope,
+there is no other way to access it.
- package Pax;
- my $started = scalar(localtime(time()));
+ BEGIN {
+ my $count = 1;
+ sub increment_count { $count++ }
+ sub return_count { $count }
+ }
- sub begun { return $started }
+To declare a file-private variable, you still use a lexical variable.
+A file is also a scope, so a lexical variable defined in the file
+cannot be seen from any other file.
-When C<use Pax> or C<require Pax> loads this module, the variable will
-be initialized. It won't get garbage-collected the way most variables
-going out of scope do, because the begun() function cares about it,
-but no one else can get it. It is not called $Pax::started because
-its scope is unrelated to the package. It's scoped to the file. You
-could conceivably have several packages in that same file all
-accessing the same private variable, but another file with the same
-package couldn't get to it.
+See L<perlsub/"Persistent Private Variables"> for more information.
+The discussion of closures in L<perlref> may help you even though we
+did not use anonymous subroutines in this answer. See
+L<perlsub/"Persistent Private Variables"> for details.
=head2 What's the difference between dynamic and lexical (static) scoping? Between local() and my()?
-C<local($x)> saves away the old value of the global variable C<$x>,
-and assigns a new value for the duration of the subroutine, I<which is
+C<local($x)> saves away the old value of the global variable C<$x>
+and assigns a new value for the duration of the subroutine I<which is
visible in other functions called from that subroutine>. This is done
at run-time, so is called dynamic scoping. local() always affects global
variables, also called package variables or dynamic variables.
C<my($x)> creates a new variable that is only visible in the current
-subroutine. This is done at compile-time, so is called lexical or
+subroutine. This is done at compile-time, so it is called lexical or
static scoping. my() always affects private variables, also called
lexical variables or (improperly) static(ly scoped) variables.
For instance:
- sub visible {
- print "var has value $var\n";
- }
+ sub visible {
+ print "var has value $var\n";
+ }
- sub dynamic {
- local $var = 'local'; # new temporary value for the still-global
- visible(); # variable called $var
- }
+ sub dynamic {
+ local $var = 'local'; # new temporary value for the still-global
+ visible(); # variable called $var
+ }
- sub lexical {
- my $var = 'private'; # new private variable, $var
- visible(); # (invisible outside of sub scope)
- }
+ sub lexical {
+ my $var = 'private'; # new private variable, $var
+ visible(); # (invisible outside of sub scope)
+ }
- $var = 'global';
+ $var = 'global';
- visible(); # prints global
- dynamic(); # prints local
- lexical(); # prints global
+ visible(); # prints global
+ dynamic(); # prints local
+ lexical(); # prints global
Notice how at no point does the value "private" get printed. That's
because $var only has that value within the block of the lexical()
variables. It gives a global variable a temporary value. my() is
what you're looking for if you want private variables.
-See also L<perlsub>, which explains this all in more detail.
+See L<perlsub/"Private Variables via my()"> and
+L<perlsub/"Temporary Values via local()"> for excruciating details.
=head2 How can I access a dynamic variable while a similarly named lexical is in scope?
-You can do this via symbolic references, provided you haven't set
-C<use strict "refs">. So instead of $var, use C<${'var'}>.
+If you know your package, you can just mention it explicitly, as in
+$Some_Pack::var. Note that the notation $::var is B<not> the dynamic $var
+in the current package, but rather the one in the "main" package, as
+though you had written $main::var.
- local $var = "global";
- my $var = "lexical";
+ use vars '$var';
+ local $var = "global";
+ my $var = "lexical";
- print "lexical is $var\n";
+ print "lexical is $var\n";
+ print "global is $main::var\n";
- no strict 'refs';
- print "global is ${'var'}\n";
+Alternatively you can use the compiler directive our() to bring a
+dynamic variable into the current lexical scope.
-If you know your package, you can just mention it explicitly, as in
-$Some_Pack::var. Note that the notation $::var is I<not> the dynamic
-$var in the current package, but rather the one in the C<main>
-package, as though you had written $main::var. Specifying the package
-directly makes you hard-code its name, but it executes faster and
-avoids running afoul of C<use strict "refs">.
+ require 5.006; # our() did not exist before 5.6
+ use vars '$var';
+
+ local $var = "global";
+ my $var = "lexical";
+
+ print "lexical is $var\n";
+
+ {
+ our $var;
+ print "global is $var\n";
+ }
=head2 What's the difference between deep and shallow binding?
are effectively shallowly bound. Consider this just one more reason
not to use them. See the answer to L<"What's a closure?">.
-=head2 Why doesn't "local($foo) = <FILE>;" work right?
+=head2 Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
-C<local()> gives list context to the right hand side of C<=>. The
-E<lt>FHE<gt> read operation, like so many of Perl's functions and
-operators, can tell which context it was called in and behaves
-appropriately. In general, the scalar() function can help. This
-function does nothing to the data itself (contrary to popular myth)
-but rather tells its argument to behave in whatever its scalar fashion
-is. If that function doesn't have a defined scalar behavior, this of
-course doesn't help you (such as with sort()).
+C<my()> and C<local()> give list context to the right hand side
+of C<=>. The <FH> read operation, like so many of Perl's
+functions and operators, can tell which context it was called in and
+behaves appropriately. In general, the scalar() function can help.
+This function does nothing to the data itself (contrary to popular myth)
+but rather tells its argument to behave in whatever its scalar fashion is.
+If that function doesn't have a defined scalar behavior, this of course
+doesn't help you (such as with sort()).
To enforce scalar context in this particular case, however, you need
merely omit the parentheses:
- local($foo) = <FILE>; # WRONG
- local($foo) = scalar(<FILE>); # ok
- local $foo = <FILE>; # right
+ local($foo) = <FILE>; # WRONG
+ local($foo) = scalar(<FILE>); # ok
+ local $foo = <FILE>; # right
You should probably be using lexical variables anyway, although the
issue is the same here:
- my($foo) = <FILE>; # WRONG
- my $foo = <FILE>; # right
+ my($foo) = <FILE>; # WRONG
+ my $foo = <FILE>; # right
-=head2 How do I redefine a built-in function, operator, or method?
+=head2 How do I redefine a builtin function, operator, or method?
Why do you want to do that? :-)
If you want to override a predefined function, such as open(),
then you'll have to import the new definition from a different
-module. See L<perlsub/"Overriding Builtin Functions">. There's
+module. See L<perlsub/"Overriding Built-in Functions">. There's
also an example in L<perltoot/"Class::Template">.
If you want to overload a Perl operator, such as C<+> or C<**>,
=head2 What's the difference between calling a function as &foo and foo()?
-When you call a function as C<&foo>, you allow that function access to
-your current @_ values, and you by-pass prototypes. That means that
-the function doesn't get an empty @_, it gets yours! While not
-strictly speaking a bug (it's documented that way in L<perlsub>), it
-would be hard to consider this a feature in most cases.
+(contributed by brian d foy)
+
+Calling a subroutine as C<&foo> with no trailing parentheses ignores
+the prototype of C<foo> and passes it the current value of the argument
+list, C<@_>. Here's an example; the C<bar> subroutine calls C<&foo>,
+which prints what its arguments list:
+
+ sub bar { &foo }
+
+ sub foo { print "Args in foo are: @_\n" }
+
+ bar( qw( a b c ) );
+
+When you call C<bar> with arguments, you see that C<foo> got the same C<@_>:
+
+ Args in foo are: a b c
+
+Calling the subroutine with trailing parentheses, with or without arguments,
+does not use the current C<@_> and respects the subroutine prototype. Changing
+the example to put parentheses after the call to C<foo> changes the program:
-When you call your function as C<&foo()>, then you do get a new @_,
-but prototyping is still circumvented.
+ sub bar { &foo() }
-Normally, you want to call a function using C<foo()>. You may only
-omit the parentheses if the function is already known to the compiler
-because it already saw the definition (C<use> but not C<require>),
-or via a forward reference or C<use subs> declaration. Even in this
-case, you get a clean @_ without any of the old values leaking through
-where they don't belong.
+ sub foo { print "Args in foo are: @_\n" }
+
+ bar( qw( a b c ) );
+
+Now the output shows that C<foo> doesn't get the C<@_> from its caller.
+
+ Args in foo are:
+
+The main use of the C<@_> pass-through feature is to write subroutines
+whose main job it is to call other subroutines for you. For further
+details, see L<perlsub>.
=head2 How do I create a switch or case statement?
-This is explained in more depth in the L<perlsyn>. Briefly, there's
-no official case statement, because of the variety of tests possible
-in Perl (numeric comparison, string comparison, glob comparison,
-regexp matching, overloaded comparisons, ...). Larry couldn't decide
-how best to do this, so he left it out, even though it's been on the
-wish list since perl1.
+In Perl 5.10, use the C<given-when> construct described in L<perlsyn>:
+
+ use 5.010;
-Here's a simple example of a switch based on pattern matching. We'll
-do a multi-way conditional based on the type of reference stored in
-$whatchamacallit:
+ given ( $string ) {
+ when( 'Fred' ) { say "I found Fred!" }
+ when( 'Barney' ) { say "I found Barney!" }
+ when( /Bamm-?Bamm/ ) { say "I found Bamm-Bamm!" }
+ default { say "I don't recognize the name!" }
+ };
- SWITCH:
- for (ref $whatchamacallit) {
+If one wants to use pure Perl and to be compatible with Perl versions
+prior to 5.10, the general answer is to use C<if-elsif-else>:
+
+ for ($variable_to_test) {
+ if (/pat1/) { } # do something
+ elsif (/pat2/) { } # do something else
+ elsif (/pat3/) { } # do something else
+ else { } # default
+ }
+
+Here's a simple example of a switch based on pattern matching,
+lined up in a way to make it look more like a switch statement.
+We'll do a multiway conditional based on the type of reference stored
+in $whatchamacallit:
+
+ SWITCH: for (ref $whatchamacallit) {
/^$/ && die "not a reference";
}
-=head2 How can I catch accesses to undefined variables/functions/methods?
+See L<perlsyn> for other examples in this style.
+
+Sometimes you should change the positions of the constant and the variable.
+For example, let's say you wanted to test which of many answers you were
+given, but in a case-insensitive way that also allows abbreviations.
+You can use the following technique if the strings all start with
+different characters or if you want to arrange the matches so that
+one takes precedence over another, as C<"SEND"> has precedence over
+C<"STOP"> here:
+
+ chomp($answer = <>);
+ if ("SEND" =~ /^\Q$answer/i) { print "Action is send\n" }
+ elsif ("STOP" =~ /^\Q$answer/i) { print "Action is stop\n" }
+ elsif ("ABORT" =~ /^\Q$answer/i) { print "Action is abort\n" }
+ elsif ("LIST" =~ /^\Q$answer/i) { print "Action is list\n" }
+ elsif ("EDIT" =~ /^\Q$answer/i) { print "Action is edit\n" }
+
+A totally different approach is to create a hash of function references.
+
+ my %commands = (
+ "happy" => \&joy,
+ "sad", => \&sullen,
+ "done" => sub { die "See ya!" },
+ "mad" => \&angry,
+ );
+
+ print "How are you? ";
+ chomp($string = <STDIN>);
+ if ($commands{$string}) {
+ $commands{$string}->();
+ } else {
+ print "No such command: $string\n";
+ }
+
+Starting from Perl 5.8, a source filter module, C<Switch>, can also be
+used to get switch and case. Its use is now discouraged, because it's
+not fully compatible with the native switch of Perl 5.10, and because,
+as it's implemented as a source filter, it doesn't always work as intended
+when complex syntax is involved.
+
+=head2 How can I catch accesses to undefined variables, functions, or methods?
The AUTOLOAD method, discussed in L<perlsub/"Autoloading"> and
L<perltoot/"AUTOLOAD: Proxy Methods">, lets you capture calls to
undefined functions and methods.
When it comes to undefined variables that would trigger a warning
-under C<-w>, you can use a handler to trap the pseudo-signal
-C<__WARN__> like this:
-
- $SIG{__WARN__} = sub {
-
- for ( $_[0] ) {
-
- /Use of uninitialized value/ && do {
- # promote warning to a fatal
- die $_;
- };
-
- # other warning cases to catch could go here;
+under C<use warnings>, you can promote the warning to an error.
- warn $_;
- }
-
- };
+ use warnings FATAL => qw(uninitialized);
=head2 Why can't a method included in this same file be found?
Some possible reasons: your inheritance is getting confused, you've
misspelled the method name, or the object is of the wrong type. Check
-out L<perltoot> for details on these. You may also use C<print
-ref($object)> to find out the class C<$object> was blessed into.
+out L<perltoot> for details about any of the above cases. You may
+also use C<print ref($object)> to find out the class C<$object> was
+blessed into.
Another possible reason for problems is because you've used the
indirect object syntax (eg, C<find Guru "Samy">) on a class name
before Perl has seen that such a package exists. It's wisest to make
sure your packages are all defined before you start using them, which
will be taken care of if you use the C<use> statement instead of
-C<require>. If not, make sure to use arrow notation (eg,
-C<Guru->find("Samy")>) instead. Object notation is explained in
+C<require>. If not, make sure to use arrow notation (eg.,
+C<< Guru->find("Samy") >>) instead. Object notation is explained in
L<perlobj>.
-=head2 How can I find out my current package?
+Make sure to read about creating modules in L<perlmod> and
+the perils of indirect objects in L<perlobj/"Method Invocation">.
-If you're just a random program, you can do this to find
-out what the currently compiled package is:
+=head2 How can I find out my current or calling package?
- my $packname = ref bless [];
+(contributed by brian d foy)
-But if you're a method and you want to print an error message
-that includes the kind of object you were called on (which is
-not necessarily the same as the one in which you were compiled):
+To find the package you are currently in, use the special literal
+C<__PACKAGE__>, as documented in L<perldata>. You can only use the
+special literals as separate tokens, so you can't interpolate them
+into strings like you can with variables:
- sub amethod {
- my $self = shift;
- my $class = ref($self) || $self;
- warn "called me from a $class object";
- }
+ my $current_package = __PACKAGE__;
+ print "I am in package $current_package\n";
+
+This is different from finding out the package an object is blessed
+into, which might not be the current package. For that, use C<blessed>
+from C<Scalar::Util>, part of the Standard Library since Perl 5.8:
+
+ use Scalar::Util qw(blessed);
+ my $object_package = blessed( $object );
+
+Most of the time, you shouldn't care what package an object is blessed
+into, however, as long as it claims to inherit from that class:
+
+ my $is_right_class = eval { $object->isa( $package ) }; # true or false
+
+If you want to find the package calling your code, perhaps to give better
+diagnostics as C<Carp> does, use the C<caller> built-in:
+
+ sub foo {
+ my @args = ...;
+ my( $package, $filename, $line ) = caller;
+
+ print "I was called from package $package\n";
+ );
+
+By default, your program starts in package C<main>, so you should
+always be in some package unless someone uses the C<package> built-in
+with no namespace. See the C<package> entry in L<perlfunc> for the
+details of empty packages.
+
+=head2 How can I comment out a large block of Perl code?
+
+(contributed by brian d foy)
+
+The quick-and-dirty way to comment out more than one line of Perl is
+to surround those lines with Pod directives. You have to put these
+directives at the beginning of the line and somewhere where Perl
+expects a new statement (so not in the middle of statements like the #
+comments). You end the comment with C<=cut>, ending the Pod section:
+
+ =pod
+
+ my $object = NotGonnaHappen->new();
+
+ ignored_sub();
+
+ $wont_be_assigned = 37;
+
+ =cut
+
+The quick-and-dirty method only works well when you don't plan to
+leave the commented code in the source. If a Pod parser comes along,
+you're multiline comment is going to show up in the Pod translation.
+A better way hides it from Pod parsers as well.
+
+The C<=begin> directive can mark a section for a particular purpose.
+If the Pod parser doesn't want to handle it, it just ignores it. Label
+the comments with C<comment>. End the comment using C<=end> with the
+same label. You still need the C<=cut> to go back to Perl code from
+the Pod comment:
+
+ =begin comment
+
+ my $object = NotGonnaHappen->new();
+
+ ignored_sub();
+
+ $wont_be_assigned = 37;
+
+ =end comment
+
+ =cut
+
+For more information on Pod, check out L<perlpod> and L<perlpodspec>.
+
+=head2 How do I clear a package?
+
+Use this code, provided by Mark-Jason Dominus:
+
+ sub scrub_package {
+ no strict 'refs';
+ my $pack = shift;
+ die "Shouldn't delete main package"
+ if $pack eq "" || $pack eq "main";
+ my $stash = *{$pack . '::'}{HASH};
+ my $name;
+ foreach $name (keys %$stash) {
+ my $fullname = $pack . '::' . $name;
+ # Get rid of everything with that name.
+ undef $$fullname;
+ undef @$fullname;
+ undef %$fullname;
+ undef &$fullname;
+ undef *$fullname;
+ }
+ }
+
+Or, if you're using a recent release of Perl, you can
+just use the Symbol::delete_package() function instead.
+
+=head2 How can I use a variable as a variable name?
+
+Beginners often think they want to have a variable contain the name
+of a variable.
+
+ $fred = 23;
+ $varname = "fred";
+ ++$$varname; # $fred now 24
+
+This works I<sometimes>, but it is a very bad idea for two reasons.
+
+The first reason is that this technique I<only works on global
+variables>. That means that if $fred is a lexical variable created
+with my() in the above example, the code wouldn't work at all: you'd
+accidentally access the global and skip right over the private lexical
+altogether. Global variables are bad because they can easily collide
+accidentally and in general make for non-scalable and confusing code.
+
+Symbolic references are forbidden under the C<use strict> pragma.
+They are not true references and consequently are not reference counted
+or garbage collected.
+
+The other reason why using a variable to hold the name of another
+variable is a bad idea is that the question often stems from a lack of
+understanding of Perl data structures, particularly hashes. By using
+symbolic references, you are just using the package's symbol-table hash
+(like C<%main::>) instead of a user-defined hash. The solution is to
+use your own hash or a real reference instead.
+
+ $USER_VARS{"fred"} = 23;
+ $varname = "fred";
+ $USER_VARS{$varname}++; # not $$varname++
+
+There we're using the %USER_VARS hash instead of symbolic references.
+Sometimes this comes up in reading strings from the user with variable
+references and wanting to expand them to the values of your perl
+program's variables. This is also a bad idea because it conflates the
+program-addressable namespace and the user-addressable one. Instead of
+reading a string and expanding it to the actual contents of your program's
+own variables:
+
+ $str = 'this has a $fred and $barney in it';
+ $str =~ s/(\$\w+)/$1/eeg; # need double eval
+
+it would be better to keep a hash around like %USER_VARS and have
+variable references actually refer to entries in that hash:
+
+ $str =~ s/\$(\w+)/$USER_VARS{$1}/g; # no /e here at all
+
+That's faster, cleaner, and safer than the previous approach. Of course,
+you don't need to use a dollar sign. You could use your own scheme to
+make it less confusing, like bracketed percent symbols, etc.
+
+ $str = 'this has a %fred% and %barney% in it';
+ $str =~ s/%(\w+)%/$USER_VARS{$1}/g; # no /e here at all
+
+Another reason that folks sometimes think they want a variable to
+contain the name of a variable is because they don't know how to build
+proper data structures using hashes. For example, let's say they
+wanted two hashes in their program: %fred and %barney, and that they
+wanted to use another scalar variable to refer to those by name.
+
+ $name = "fred";
+ $$name{WIFE} = "wilma"; # set %fred
+
+ $name = "barney";
+ $$name{WIFE} = "betty"; # set %barney
+
+This is still a symbolic reference, and is still saddled with the
+problems enumerated above. It would be far better to write:
+
+ $folks{"fred"}{WIFE} = "wilma";
+ $folks{"barney"}{WIFE} = "betty";
+
+And just use a multilevel hash to start with.
+
+The only times that you absolutely I<must> use symbolic references are
+when you really must refer to the symbol table. This may be because it's
+something that can't take a real reference to, such as a format name.
+Doing so may also be important for method calls, since these always go
+through the symbol table for resolution.
+
+In those cases, you would turn off C<strict 'refs'> temporarily so you
+can play around with the symbol table. For example:
+
+ @colors = qw(red blue green yellow orange purple violet);
+ for my $name (@colors) {
+ no strict 'refs'; # renege for the block
+ *$name = sub { "<FONT COLOR='$name'>@_</FONT>" };
+ }
+
+All those functions (red(), blue(), green(), etc.) appear to be separate,
+but the real code in the closure actually was compiled only once.
+
+So, sometimes you might want to use symbolic references to directly
+manipulate the symbol table. This doesn't matter for formats, handles, and
+subroutines, because they are always global--you can't use my() on them.
+For scalars, arrays, and hashes, though--and usually for subroutines--
+you probably only want to use hard references.
+
+=head2 What does "bad interpreter" mean?
+
+(contributed by brian d foy)
+
+The "bad interpreter" message comes from the shell, not perl. The
+actual message may vary depending on your platform, shell, and locale
+settings.
+
+If you see "bad interpreter - no such file or directory", the first
+line in your perl script (the "shebang" line) does not contain the
+right path to perl (or any other program capable of running scripts).
+Sometimes this happens when you move the script from one machine to
+another and each machine has a different path to perl--/usr/bin/perl
+versus /usr/local/bin/perl for instance. It may also indicate
+that the source machine has CRLF line terminators and the
+destination machine has LF only: the shell tries to find
+/usr/bin/perl<CR>, but can't.
+
+If you see "bad interpreter: Permission denied", you need to make your
+script executable.
+
+In either case, you should still be able to run the scripts with perl
+explicitly:
+
+ % perl script.pl
+
+If you get a message like "perl: command not found", perl is not in
+your PATH, which might also mean that the location of perl is not
+where you expect it so you need to adjust your shebang line.
+
+=head1 REVISION
+
+Revision: $Revision$
+
+Date: $Date$
+
+See L<perlfaq> for source control details and availability.
=head1 AUTHOR AND COPYRIGHT
-Copyright (c) 1997 Tom Christiansen and Nathan Torkington.
-All rights reserved. See L<perlfaq> for distribution information.
+Copyright (c) 1997-2009 Tom Christiansen, Nathan Torkington, and
+other authors as noted. All rights reserved.
+
+This documentation is free; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+Irrespective of its distribution, all code examples in this file
+are hereby placed into the public domain. You are permitted and
+encouraged to use this code in your own programs for fun
+or for profit as you see fit. A simple comment in the code giving
+credit would be courteous but is not required.
+