=head1 NAME
-perlfaq7 - Perl Language Issues ($Revision: 1.1 $, $Date: 2001/09/20 03:03:00 $)
+perlfaq7 - General Perl Language Issues ($Revision: 1.27 $, $Date: 2005/10/28 17:38:32 $)
=head1 DESCRIPTION
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/$/>) from the handle FILE in scalar context, or I<all> lines
+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<< <> >> 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,
This is like this
------------ ---------------
- $foo{line} $foo{"line"}
- bar => stuff "bar" => stuff
+ $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
($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?
If you are running Perl 5.6.0 or better, the C<use warnings> pragma
$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:
=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>.
-
-Here's a convenient template you might wish you use when starting your
-own module. Make sure to change the names appropriately.
-
- package Some::Module; # assumes Some/Module.pm
-
- use strict;
- use warnings;
-
- BEGIN {
- use Exporter ();
- our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
-
- ## set the version for version checking; uncomment to use
- ## $VERSION = 1.00;
-
- # if using RCS/CVS, this next line may be preferred,
- # but beware two-digit versions.
- $VERSION = do{my@r=q$Revision: 1.1 $=~/\d+/g;sprintf '%d.'.'%02d'x$#r,@r};
-
- @ISA = qw(Exporter);
- @EXPORT = qw(&func1 &func2 &func3);
- %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
-
- # your exported package globals go here,
- # as well as any optionally exported functions
- @EXPORT_OK = qw($Var1 %Hashit);
- }
- our @EXPORT_OK;
-
- # exported package globals go here
- our $Var1;
- our %Hashit;
-
- # non-exported package globals go here
- our @more;
- our $stuff;
-
- # initialize package globals, first exported ones
- $Var1 = '';
- %Hashit = ();
-
- # then the others (which are still accessible as $Some::Module::stuff)
- $stuff = '';
- @more = ();
+(contributed by brian d foy)
- # all file-scoped lexicals must be created before
- # the functions below that use them.
+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.
- # file-private lexicals go here
- my $priv_var = '';
- my %secret_hash = ();
+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.
- # here's a file-private function as a closure,
- # callable as &$priv_func; it cannot be prototyped.
- my $priv_func = sub {
- # stuff goes here.
- };
+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.
- # make all your functions, whether exported or not;
- # remember to put something interesting in the {} stubs
- sub func1 {} # no prototype
- sub func2() {} # proto'd void
- sub func3($$) {} # proto'd to 2 scalars
-
- # this one isn't exported, but could be called!
- sub func4(\%) {} # proto'd to 1 hash ref
-
- END { } # module clean-up code here (global destructor)
-
- 1; # modules must return true
-
-The h2xs program will create stubs for all the important stuff for you:
-
- % h2xs -XA -n My::Module
+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.
=head2 How do I create a class?
=head2 How can I tell if a variable is tainted?
-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):
-
- sub is_tainted {
- return ! eval { join('',@_), kill 0; 1; };
- }
-
-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?
Here's a classic function-generating function:
sub add_function_generator {
- return sub { shift + shift };
+ return sub { shift() + shift() };
}
$add_sub = add_function_generator();
sub make_adder {
my $addpiece = shift;
- return sub { shift + $addpiece };
+ return sub { shift() + $addpiece };
}
$f1 = make_adder(20);
=head2 What is variable suicide and how can I prevent it?
-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:
+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";
+ my $f = 'foo';
sub T {
- while ($i++ < 3) { my $f = $f; $f .= "bar"; print $f, "\n" }
+ while ($i++ < 3) { my $f = $f; $f .= $i; 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
+
The $f that has "bar" added to it three times should be a new C<$f>
-(C<my $f> should create a new local variable each time through the loop).
-It isn't, however. This was a bug, now fixed in the latest releases
-(tested against 5.004_05, 5.005_03, and 5.005_56).
+C<my $f> should create a new lexical variable each time through the loop.
+The expected output is:
+
+ foobar
+ foobar
+ foobar
+ Finally foo
=head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
objects. See L<perlsub/"Pass by Reference"> for this particular
question, and L<perlref> for information on references.
-See ``Passing Regexes'', below, for information on passing regular
+See "Passing Regexes", below, for information on passing regular
expressions.
=over 4
=item Passing Filehandles
-To pass filehandles to subroutines, 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.
+As of Perl 5.6, you can represent filehandles with scalar variables
+which you treat as any other scalar.
-Here's an excerpt:
+ open my $fh, $filename or die "Cannot open $filename! $!";
+ func( $fh );
-If you're passing around filehandles, you could usually just use the bare
-typeglob, like *STDOUT, but typeglobs references would be better because
-they'll still work properly under C<use strict 'refs'>. For example:
-
- splutter(\*STDOUT);
- sub splutter {
- my $fh = shift;
- print $fh "her um well a hmmm\n";
- }
-
- $rec = get_rec(\*STDIN);
- sub get_rec {
- my $fh = shift;
- return scalar <$fh>;
- }
+ sub func {
+ my $passed_fh = shift;
-If you're planning on generating new filehandles, you could do this:
+ my $line = <$fh>;
+ }
- sub openit {
- my $path = shift;
- local *FH;
- return open (FH, $path) ? *FH : undef;
- }
- $fh = openit('< /etc/motd');
- print <$fh>;
+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.
=item Passing Regexes
=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.
-
-Here's code to implement a function-private variable:
+(contributed by brian d foy)
+
+Perl doesn't have "static" variables, which can only be accessed from
+the function in which they are declared. You can get the same effect
+with lexical variables, though.
+
+You can fake a static variable by using a lexical variable which goes
+out of scope. In this example, you define the subroutine 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 $counter = 42;
- sub prev_counter { return --$counter }
- sub next_counter { return $counter++ }
+ my $count = 1;
+ sub counter { $count++ }
}
-Now prev_counter() and next_counter() share a private variable $counter
-that was initialized at compile time.
+ my $start = count();
+
+ .... # code that calls count();
-To declare a file-private variable, you'll still use a my(), putting
-the declaration at the outer scope level at the top of the file.
-Assume this is in file Pax.pm:
+ my $end = count();
- package Pax;
- my $started = scalar(localtime(time()));
+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.
- sub begun { return $started }
+ BEGIN {
+ my $count = 1;
+ sub increment_count { $count++ }
+ sub return_count { $count }
+ }
-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.
+To declare a file-private variable, you still use a lexical variable.
+A file is also a scope, so a lexical variable defined in the file
+cannot be seen from any other file.
-See L<perlsub/"Persistent Private Variables"> for details.
+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()?
variables. It gives a global variable a temporary value. my() is
what you're looking for if you want private variables.
-See L<perlsub/"Private Variables via my()"> and
+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 "my($foo) = <FILE>;" work right?
+=head2 Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
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
elsif (/pat2/) { } # do something else
elsif (/pat3/) { } # do something else
else { } # default
- }
+ }
Here's a simple example of a switch based on pattern matching, this
time lined up in a way to make it look more like a switch statement.
-We'll do a multi-way conditional based on the type of reference stored
+We'll do a multiway conditional based on the type of reference stored
in $whatchamacallit:
SWITCH: for (ref $whatchamacallit) {
}
-See C<perlsyn/"Basic BLOCKs and Switch Statements"> for many other
+See C<perlsyn/"Basic BLOCKs and Switch Statements"> for many other
examples in this style.
Sometimes you should change the positions of the constant and the variable.
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.
+A totally different approach is to create a hash of function references.
my %commands = (
"happy" => \&joy,
$commands{$string}->();
} else {
print "No such command: $string\n";
- }
+ }
-=head2 How can I catch accesses to undefined variables/functions/methods?
+=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:
+under C<use warnings>, you can promote the warning to an error.
- $SIG{__WARN__} = sub {
-
- for ( $_[0] ) { # voici un switch statement
-
- /Use of uninitialized value/ && do {
- # promote warning to a fatal
- die $_;
- };
-
- # other warning cases to catch could go here;
-
- warn $_;
- }
-
- };
+ use warnings FATAL => qw(uninitialized);
=head2 Why can't a method included in this same file be found?
=head2 How can I comment out a large block of perl code?
-Use embedded POD to discard it:
+You can use embedded POD to discard it. Enclose the blocks you want
+to comment out in POD markers. The <=begin> directive marks a section
+for a specific formatter. Use the C<comment> format, which no formatter
+should claim to understand (by policy). Mark the end of the block
+with <=end>.
# program is here
- =for nobody
- This paragraph is commented out
-
- # program continues
-
- =begin comment text
+ =begin comment
all of this stuff
here will be ignored
by everyone
- =end comment text
+ =end comment
=cut
-This can't go just anywhere. You have to put a pod directive where
-the parser is expecting a new statement, not just in the middle
-of an expression or some other arbitrary yacc grammar production.
+ # program continues
+
+The pod directives cannot go just anywhere. You must put a
+pod directive where the parser is expecting a new statement,
+not just in the middle of an expression or some other
+arbitrary grammar production.
+
+See L<perlpod> for more details.
=head2 How do I clear a package?
sub scrub_package {
no strict 'refs';
my $pack = shift;
- die "Shouldn't delete main package"
+ die "Shouldn't delete main package"
if $pack eq "" || $pack eq "main";
my $stash = *{$pack . '::'}{HASH};
my $name;
}
}
-Or, if you're using a recent release of Perl, you can
+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?
(like C<%main::>) instead of a user-defined hash. The solution is to
use your own hash or a real reference instead.
- $fred = 23;
+ $USER_VARS{"fred"} = 23;
$varname = "fred";
$USER_VARS{$varname}++; # not $$varname++
$name = "fred";
$$name{WIFE} = "wilma"; # set %fred
- $name = "barney";
+ $name = "barney";
$$name{WIFE} = "betty"; # set %barney
This is still a symbolic reference, and is still saddled with the
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.
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 AUTHOR AND COPYRIGHT
-Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington.
-All rights reserved.
+Copyright (c) 1997-2005 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.