3 perlfaq7 - General Perl Language Issues
7 This section deals with general Perl language issues that don't
8 clearly fit into any of the other sections.
10 =head2 Can I get a BNF/yacc/RE for the Perl language?
12 There is no BNF, but you can paw your way through the yacc grammar in
13 perly.y in the source distribution if you're particularly brave. The
14 grammar relies on very smart tokenizing code, so be prepared to
15 venture into toke.c as well.
17 In the words of Chaim Frenkel: "Perl's grammar can not be reduced to BNF.
18 The work of parsing perl is distributed between yacc, the lexer, smoke
21 =head2 What are all these $@%&* punctuation signs, and how do I know when to use them?
23 They are type specifiers, as detailed in L<perldata>:
25 $ for scalar values (number, string or reference)
27 % for hashes (associative arrays)
28 & for subroutines (aka functions, procedures, methods)
29 * for all types of that symbol name. In version 4 you used them like
30 pointers, but in modern perls you can just use references.
32 There are couple of other symbols that you're likely to encounter that aren't
33 really type specifiers:
35 <> are used for inputting a record from a filehandle.
36 \ takes a reference to something.
38 Note that <FILE> is I<neither> the type specifier for files
39 nor the name of the handle. It is the C<< <> >> operator applied
40 to the handle FILE. It reads one line (well, record--see
41 L<perlvar/$E<sol>>) from the handle FILE in scalar context, or I<all> lines
42 in list context. When performing open, close, or any other operation
43 besides C<< <> >> on files, or even when talking about the handle, do
44 I<not> use the brackets. These are correct: C<eof(FH)>, C<seek(FH, 0,
45 2)> and "copying from STDIN to FILE".
47 =head2 Do I always/never have to quote my strings or use semicolons and commas?
49 Normally, a bareword doesn't need to be quoted, but in most cases
50 probably should be (and must be under C<use strict>). But a hash key
51 consisting of a simple word (that isn't the name of a defined
52 subroutine) and the left-hand operand to the C<< => >> operator both
53 count as though they were quoted:
56 ------------ ---------------
57 $foo{line} $foo{'line'}
58 bar => stuff 'bar' => stuff
60 The final semicolon in a block is optional, as is the final comma in a
61 list. Good style (see L<perlstyle>) says to put them in except for
64 if ($whoops) { exit 1 }
72 "There Beren came from mountains cold",
73 "And lost he wandered under leaves",
76 =head2 How do I skip some return values?
78 One way is to treat the return values as a list and index into it:
80 $dir = (getpwnam($user))[7];
82 Another way is to use undef as an element on the left-hand-side:
84 ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
86 You can also use a list slice to select only the elements that
89 ($dev, $ino, $uid, $gid) = ( stat($file) )[0,1,4,5];
91 =head2 How do I temporarily block warnings?
93 If you are running Perl 5.6.0 or better, the C<use warnings> pragma
94 allows fine control of what warning are produced.
95 See L<perllexwarn> for more details.
98 no warnings; # temporarily turn off warnings
99 $a = $b + $c; # I know these might be undef
102 Additionally, you can enable and disable categories of warnings.
103 You turn off the categories you want to ignore and you can still
104 get other categories of warnings. See L<perllexwarn> for the
105 complete details, including the category names and hierarchy.
108 no warnings 'uninitialized';
112 If you have an older version of Perl, the C<$^W> variable (documented
113 in L<perlvar>) controls runtime warnings for a block:
116 local $^W = 0; # temporarily turn off warnings
117 $a = $b + $c; # I know these might be undef
120 Note that like all the punctuation variables, you cannot currently
121 use my() on C<$^W>, only local().
123 =head2 What's an extension?
125 An extension is a way of calling compiled C code from Perl. Reading
126 L<perlxstut> is a good place to learn more about extensions.
128 =head2 Why do Perl operators have different precedence than C operators?
130 Actually, they don't. All C operators that Perl copies have the same
131 precedence in Perl as they do in C. The problem is with operators that C
132 doesn't have, especially functions that give a list context to everything
133 on their right, eg. print, chmod, exec, and so on. Such functions are
134 called "list operators" and appear as such in the precedence table in
137 A common mistake is to write:
139 unlink $file || die "snafu";
141 This gets interpreted as:
143 unlink ($file || die "snafu");
145 To avoid this problem, either put in extra parentheses or use the
146 super low precedence C<or> operator:
148 (unlink $file) || die "snafu";
149 unlink $file or die "snafu";
151 The "English" operators (C<and>, C<or>, C<xor>, and C<not>)
152 deliberately have precedence lower than that of list operators for
153 just such situations as the one above.
155 Another operator with surprising precedence is exponentiation. It
156 binds more tightly even than unary minus, making C<-2**2> produce a
157 negative not a positive four. It is also right-associating, meaning
158 that C<2**3**2> is two raised to the ninth power, not eight squared.
160 Although it has the same precedence as in C, Perl's C<?:> operator
161 produces an lvalue. This assigns $x to either $a or $b, depending
162 on the trueness of $maybe:
164 ($maybe ? $a : $b) = $x;
166 =head2 How do I declare/create a structure?
168 In general, you don't "declare" a structure. Just use a (probably
169 anonymous) hash reference. See L<perlref> and L<perldsc> for details.
172 $person = {}; # new anonymous hash
173 $person->{AGE} = 24; # set field AGE to 24
174 $person->{NAME} = "Nat"; # set field NAME to "Nat"
176 If you're looking for something a bit more rigorous, try L<perltoot>.
178 =head2 How do I create a module?
180 (contributed by brian d foy)
182 L<perlmod>, L<perlmodlib>, L<perlmodstyle> explain modules
183 in all the gory details. L<perlnewmod> gives a brief
184 overview of the process along with a couple of suggestions
187 If you need to include C code or C library interfaces in
188 your module, you'll need h2xs. h2xs will create the module
189 distribution structure and the initial interface files
190 you'll need. L<perlxs> and L<perlxstut> explain the details.
192 If you don't need to use C code, other tools such as
193 ExtUtils::ModuleMaker and Module::Starter, can help you
194 create a skeleton module distribution.
196 You may also want to see Sam Tregar's "Writing Perl Modules
197 for CPAN" ( http://apress.com/book/bookDisplay.html?bID=14 )
198 which is the best hands-on guide to creating module
201 =head2 How do I adopt or take over a module already on CPAN?
203 (contributed by brian d foy)
205 The full answer to this can be found at
206 http://cpan.org/modules/04pause.html#takeover
208 The easiest way to take over a module is to have the current
209 module maintainer either make you a co-maintainer or transfer
212 If you can't reach the author for some reason (e.g. email bounces),
213 the PAUSE admins at modules@perl.org can help. The PAUSE admins
214 treat each case individually.
220 Get a login for the Perl Authors Upload Server (PAUSE) if you don't
221 already have one: http://pause.perl.org
225 Write to modules@perl.org explaining what you did to contact the
226 current maintainer. The PAUSE admins will also try to reach the
231 Post a public message in a heavily trafficked site announcing your
232 intention to take over the module.
236 Wait a bit. The PAUSE admins don't want to act too quickly in case
237 the current maintainer is on holiday. If there's no response to
238 private communication or the public post, a PAUSE admin can transfer
243 =head2 How do I create a class?
244 X<class, creation> X<package>
246 (contributed by brian d foy)
248 In Perl, a class is just a package, and methods are just subroutines.
249 Perl doesn't get more formal than that and lets you set up the package
250 just the way that you like it (that is, it doesn't set up anything for
253 The Perl documentation has several tutorials that cover class
254 creation, including L<perlboot> (Barnyard Object Oriented Tutorial),
255 L<perltoot> (Tom's Object Oriented Tutorial), L<perlbot> (Bag o'
256 Object Tricks), and L<perlobj>.
258 =head2 How can I tell if a variable is tainted?
260 You can use the tainted() function of the Scalar::Util module, available
261 from CPAN (or included with Perl since release 5.8.0).
262 See also L<perlsec/"Laundering and Detecting Tainted Data">.
264 =head2 What's a closure?
266 Closures are documented in L<perlref>.
268 I<Closure> is a computer science term with a precise but
269 hard-to-explain meaning. Usually, closures are implemented in Perl as
270 anonymous subroutines with lasting references to lexical variables
271 outside their own scopes. These lexicals magically refer to the
272 variables that were around when the subroutine was defined (deep
275 Closures are most often used in programming languages where you can
276 have the return value of a function be itself a function, as you can
277 in Perl. Note that some languages provide anonymous functions but are
278 not capable of providing proper closures: the Python language, for
279 example. For more information on closures, check out any textbook on
280 functional programming. Scheme is a language that not only supports
281 but encourages closures.
283 Here's a classic non-closure function-generating function:
285 sub add_function_generator {
286 return sub { shift() + shift() };
289 $add_sub = add_function_generator();
290 $sum = $add_sub->(4,5); # $sum is 9 now.
292 The anonymous subroutine returned by add_function_generator() isn't
293 technically a closure because it refers to no lexicals outside its own
294 scope. Using a closure gives you a I<function template> with some
295 customization slots left out to be filled later.
297 Contrast this with the following make_adder() function, in which the
298 returned anonymous function contains a reference to a lexical variable
299 outside the scope of that function itself. Such a reference requires
300 that Perl return a proper closure, thus locking in for all time the
301 value that the lexical had when the function was created.
304 my $addpiece = shift;
305 return sub { shift() + $addpiece };
308 $f1 = make_adder(20);
309 $f2 = make_adder(555);
311 Now C<&$f1($n)> is always 20 plus whatever $n you pass in, whereas
312 C<&$f2($n)> is always 555 plus whatever $n you pass in. The $addpiece
313 in the closure sticks around.
315 Closures are often used for less esoteric purposes. For example, when
316 you want to pass in a bit of code into a function:
319 timeout( 30, sub { $line = <STDIN> } );
321 If the code to execute had been passed in as a string,
322 C<< '$line = <STDIN>' >>, there would have been no way for the
323 hypothetical timeout() function to access the lexical variable
324 $line back in its caller's scope.
326 Another use for a closure is to make a variable I<private> to a
327 named subroutine, e.g. a counter that gets initialized at creation
328 time of the sub and can only be modified from within the sub.
329 This is sometimes used with a BEGIN block in package files to make
330 sure a variable doesn't get meddled with during the lifetime of the
335 sub next_id { ++$id }
338 This is discussed in more detail in L<perlsub>, see the entry on
339 I<Persistent Private Variables>.
341 =head2 What is variable suicide and how can I prevent it?
343 This problem was fixed in perl 5.004_05, so preventing it means upgrading
344 your version of perl. ;)
346 Variable suicide is when you (temporarily or permanently) lose the value
347 of a variable. It is caused by scoping through my() and local()
348 interacting with either closures or aliased foreach() iterator variables
349 and subroutine arguments. It used to be easy to inadvertently lose a
350 variable's value this way, but now it's much harder. Take this code:
354 while ($i++ < 3) { my $f = $f; $f .= "bar"; print $f, "\n" }
358 print "Finally $f\n";
360 If you are experiencing variable suicide, that C<my $f> in the subroutine
361 doesn't pick up a fresh copy of the C<$f> whose value is <foo>. The output
362 shows that inside the subroutine the value of C<$f> leaks through when it
363 shouldn't, as in this output:
370 The $f that has "bar" added to it three times should be a new C<$f>
371 C<my $f> should create a new lexical variable each time through the loop.
372 The expected output is:
379 =head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
381 With the exception of regexes, you need to pass references to these
382 objects. See L<perlsub/"Pass by Reference"> for this particular
383 question, and L<perlref> for information on references.
385 See "Passing Regexes", later in L<perlfaq7>, for information on
386 passing regular expressions.
390 =item Passing Variables and Functions
392 Regular variables and functions are quite easy to pass: just pass in a
393 reference to an existing or anonymous variable or function:
395 func( \$some_scalar );
397 func( \@some_array );
401 func( { this => 10, that => 20 } );
404 func( sub { $_[0] ** $_[1] } );
406 =item Passing Filehandles
408 As of Perl 5.6, you can represent filehandles with scalar variables
409 which you treat as any other scalar.
411 open my $fh, $filename or die "Cannot open $filename! $!";
415 my $passed_fh = shift;
417 my $line = <$passed_fh>;
420 Before Perl 5.6, you had to use the C<*FH> or C<\*FH> notations.
421 These are "typeglobs"--see L<perldata/"Typeglobs and Filehandles">
422 and especially L<perlsub/"Pass by Reference"> for more information.
424 =item Passing Regexes
426 To pass regexes around, you'll need to be using a release of Perl
427 sufficiently recent as to support the C<qr//> construct, pass around
428 strings and use an exception-trapping eval, or else be very, very clever.
430 Here's an example of how to pass in a string to be regex compared
434 my ($val1, $regex) = @_;
435 my $retval = $val1 =~ /$regex/;
438 $match = compare("old McDonald", qr/d.*D/i);
440 Notice how C<qr//> allows flags at the end. That pattern was compiled
441 at compile time, although it was executed later. The nifty C<qr//>
442 notation wasn't introduced until the 5.005 release. Before that, you
443 had to approach this problem much less intuitively. For example, here
444 it is again if you don't have C<qr//>:
447 my ($val1, $regex) = @_;
448 my $retval = eval { $val1 =~ /$regex/ };
453 $match = compare("old McDonald", q/($?i)d.*D/);
455 Make sure you never say something like this:
457 return eval "\$val =~ /$regex/"; # WRONG
459 or someone can sneak shell escapes into the regex due to the double
460 interpolation of the eval and the double-quoted string. For example:
462 $pattern_of_evil = 'danger ${ system("rm -rf * &") } danger';
464 eval "\$string =~ /$pattern_of_evil/";
466 Those preferring to be very, very clever might see the O'Reilly book,
467 I<Mastering Regular Expressions>, by Jeffrey Friedl. Page 273's
468 Build_MatchMany_Function() is particularly interesting. A complete
469 citation of this book is given in L<perlfaq2>.
471 =item Passing Methods
473 To pass an object method into a subroutine, you can do this:
475 call_a_lot(10, $some_obj, "methname")
477 my ($count, $widget, $trick) = @_;
478 for (my $i = 0; $i < $count; $i++) {
483 Or, you can use a closure to bundle up the object, its
484 method call, and arguments:
486 my $whatnot = sub { $some_obj->obfuscate(@args) };
493 You could also investigate the can() method in the UNIVERSAL class
494 (part of the standard perl distribution).
498 =head2 How do I create a static variable?
500 (contributed by brian d foy)
502 In Perl 5.10, declare the variable with C<state>. The C<state>
503 declaration creates the lexical variable that persists between calls
506 sub counter { state $count = 1; $counter++ }
508 You can fake a static variable by using a lexical variable which goes
509 out of scope. In this example, you define the subroutine C<counter>, and
510 it uses the lexical variable C<$count>. Since you wrap this in a BEGIN
511 block, C<$count> is defined at compile-time, but also goes out of
512 scope at the end of the BEGIN block. The BEGIN block also ensures that
513 the subroutine and the value it uses is defined at compile-time so the
514 subroutine is ready to use just like any other subroutine, and you can
515 put this code in the same place as other subroutines in the program
516 text (i.e. at the end of the code, typically). The subroutine
517 C<counter> still has a reference to the data, and is the only way you
518 can access the value (and each time you do, you increment the value).
519 The data in chunk of memory defined by C<$count> is private to
524 sub counter { $count++ }
527 my $start = counter();
529 .... # code that calls counter();
533 In the previous example, you created a function-private variable
534 because only one function remembered its reference. You could define
535 multiple functions while the variable is in scope, and each function
536 can share the "private" variable. It's not really "static" because you
537 can access it outside the function while the lexical variable is in
538 scope, and even create references to it. In this example,
539 C<increment_count> and C<return_count> share the variable. One
540 function adds to the value and the other simply returns the value.
541 They can both access C<$count>, and since it has gone out of scope,
542 there is no other way to access it.
546 sub increment_count { $count++ }
547 sub return_count { $count }
550 To declare a file-private variable, you still use a lexical variable.
551 A file is also a scope, so a lexical variable defined in the file
552 cannot be seen from any other file.
554 See L<perlsub/"Persistent Private Variables"> for more information.
555 The discussion of closures in L<perlref> may help you even though we
556 did not use anonymous subroutines in this answer. See
557 L<perlsub/"Persistent Private Variables"> for details.
559 =head2 What's the difference between dynamic and lexical (static) scoping? Between local() and my()?
561 C<local($x)> saves away the old value of the global variable C<$x>
562 and assigns a new value for the duration of the subroutine I<which is
563 visible in other functions called from that subroutine>. This is done
564 at run-time, so is called dynamic scoping. local() always affects global
565 variables, also called package variables or dynamic variables.
567 C<my($x)> creates a new variable that is only visible in the current
568 subroutine. This is done at compile-time, so it is called lexical or
569 static scoping. my() always affects private variables, also called
570 lexical variables or (improperly) static(ly scoped) variables.
575 print "var has value $var\n";
579 local $var = 'local'; # new temporary value for the still-global
580 visible(); # variable called $var
584 my $var = 'private'; # new private variable, $var
585 visible(); # (invisible outside of sub scope)
590 visible(); # prints global
591 dynamic(); # prints local
592 lexical(); # prints global
594 Notice how at no point does the value "private" get printed. That's
595 because $var only has that value within the block of the lexical()
596 function, and it is hidden from called subroutine.
598 In summary, local() doesn't make what you think of as private, local
599 variables. It gives a global variable a temporary value. my() is
600 what you're looking for if you want private variables.
602 See L<perlsub/"Private Variables via my()"> and
603 L<perlsub/"Temporary Values via local()"> for excruciating details.
605 =head2 How can I access a dynamic variable while a similarly named lexical is in scope?
607 If you know your package, you can just mention it explicitly, as in
608 $Some_Pack::var. Note that the notation $::var is B<not> the dynamic $var
609 in the current package, but rather the one in the "main" package, as
610 though you had written $main::var.
613 local $var = "global";
616 print "lexical is $var\n";
617 print "global is $main::var\n";
619 Alternatively you can use the compiler directive our() to bring a
620 dynamic variable into the current lexical scope.
622 require 5.006; # our() did not exist before 5.6
625 local $var = "global";
628 print "lexical is $var\n";
632 print "global is $var\n";
635 =head2 What's the difference between deep and shallow binding?
637 In deep binding, lexical variables mentioned in anonymous subroutines
638 are the same ones that were in scope when the subroutine was created.
639 In shallow binding, they are whichever variables with the same names
640 happen to be in scope when the subroutine is called. Perl always uses
641 deep binding of lexical variables (i.e., those created with my()).
642 However, dynamic variables (aka global, local, or package variables)
643 are effectively shallowly bound. Consider this just one more reason
644 not to use them. See the answer to L<"What's a closure?">.
646 =head2 Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
648 C<my()> and C<local()> give list context to the right hand side
649 of C<=>. The <FH> read operation, like so many of Perl's
650 functions and operators, can tell which context it was called in and
651 behaves appropriately. In general, the scalar() function can help.
652 This function does nothing to the data itself (contrary to popular myth)
653 but rather tells its argument to behave in whatever its scalar fashion is.
654 If that function doesn't have a defined scalar behavior, this of course
655 doesn't help you (such as with sort()).
657 To enforce scalar context in this particular case, however, you need
658 merely omit the parentheses:
660 local($foo) = <FILE>; # WRONG
661 local($foo) = scalar(<FILE>); # ok
662 local $foo = <FILE>; # right
664 You should probably be using lexical variables anyway, although the
665 issue is the same here:
667 my($foo) = <FILE>; # WRONG
668 my $foo = <FILE>; # right
670 =head2 How do I redefine a builtin function, operator, or method?
672 Why do you want to do that? :-)
674 If you want to override a predefined function, such as open(),
675 then you'll have to import the new definition from a different
676 module. See L<perlsub/"Overriding Built-in Functions">. There's
677 also an example in L<perltoot/"Class::Template">.
679 If you want to overload a Perl operator, such as C<+> or C<**>,
680 then you'll want to use the C<use overload> pragma, documented
683 If you're talking about obscuring method calls in parent classes,
684 see L<perltoot/"Overridden Methods">.
686 =head2 What's the difference between calling a function as &foo and foo()?
688 (contributed by brian d foy)
690 Calling a subroutine as C<&foo> with no trailing parentheses ignores
691 the prototype of C<foo> and passes it the current value of the argumet
692 list, C<@_>. Here's an example; the C<bar> subroutine calls C<&foo>,
693 which prints what its arguments list:
697 sub foo { print "Args in foo are: @_\n" }
701 When you call C<bar> with arguments, you see that C<foo> got the same C<@_>:
703 Args in foo are: a b c
705 Calling the subroutine with trailing parentheses, with or without arguments,
706 does not use the current C<@_> and respects the subroutine prototype. Changing
707 the example to put parentheses after the call to C<foo> changes the program:
711 sub foo { print "Args in foo are: @_\n" }
715 Now the output shows that C<foo> doesn't get the C<@_> from its caller.
719 The main use of the C<@_> pass-through feature is to write subroutines
720 whose main job it is to call other subroutines for you. For further
721 details, see L<perlsub>.
723 =head2 How do I create a switch or case statement?
725 In Perl 5.10, use the C<given-when> construct described in L<perlsyn>:
730 when( 'Fred' ) { say "I found Fred!" }
731 when( 'Barney' ) { say "I found Barney!" }
732 when( /Bamm-?Bamm/ ) { say "I found Bamm-Bamm!" }
733 default { say "I don't recognize the name!" }
736 If one wants to use pure Perl and to be compatible with Perl versions
737 prior to 5.10, the general answer is to use C<if-elsif-else>:
739 for ($variable_to_test) {
740 if (/pat1/) { } # do something
741 elsif (/pat2/) { } # do something else
742 elsif (/pat3/) { } # do something else
746 Here's a simple example of a switch based on pattern matching,
747 lined up in a way to make it look more like a switch statement.
748 We'll do a multiway conditional based on the type of reference stored
751 SWITCH: for (ref $whatchamacallit) {
753 /^$/ && die "not a reference";
771 warn "can't print function ref";
777 warn "User defined type skipped";
781 See L<perlsyn> for other examples in this style.
783 Sometimes you should change the positions of the constant and the variable.
784 For example, let's say you wanted to test which of many answers you were
785 given, but in a case-insensitive way that also allows abbreviations.
786 You can use the following technique if the strings all start with
787 different characters or if you want to arrange the matches so that
788 one takes precedence over another, as C<"SEND"> has precedence over
792 if ("SEND" =~ /^\Q$answer/i) { print "Action is send\n" }
793 elsif ("STOP" =~ /^\Q$answer/i) { print "Action is stop\n" }
794 elsif ("ABORT" =~ /^\Q$answer/i) { print "Action is abort\n" }
795 elsif ("LIST" =~ /^\Q$answer/i) { print "Action is list\n" }
796 elsif ("EDIT" =~ /^\Q$answer/i) { print "Action is edit\n" }
798 A totally different approach is to create a hash of function references.
803 "done" => sub { die "See ya!" },
807 print "How are you? ";
808 chomp($string = <STDIN>);
809 if ($commands{$string}) {
810 $commands{$string}->();
812 print "No such command: $string\n";
815 Starting from Perl 5.8, a source filter module, C<Switch>, can also be
816 used to get switch and case. Its use is now discouraged, because it's
817 not fully compatible with the native switch of Perl 5.10, and because,
818 as it's implemented as a source filter, it doesn't always work as intended
819 when complex syntax is involved.
821 =head2 How can I catch accesses to undefined variables, functions, or methods?
823 The AUTOLOAD method, discussed in L<perlsub/"Autoloading"> and
824 L<perltoot/"AUTOLOAD: Proxy Methods">, lets you capture calls to
825 undefined functions and methods.
827 When it comes to undefined variables that would trigger a warning
828 under C<use warnings>, you can promote the warning to an error.
830 use warnings FATAL => qw(uninitialized);
832 =head2 Why can't a method included in this same file be found?
834 Some possible reasons: your inheritance is getting confused, you've
835 misspelled the method name, or the object is of the wrong type. Check
836 out L<perltoot> for details about any of the above cases. You may
837 also use C<print ref($object)> to find out the class C<$object> was
840 Another possible reason for problems is because you've used the
841 indirect object syntax (eg, C<find Guru "Samy">) on a class name
842 before Perl has seen that such a package exists. It's wisest to make
843 sure your packages are all defined before you start using them, which
844 will be taken care of if you use the C<use> statement instead of
845 C<require>. If not, make sure to use arrow notation (eg.,
846 C<< Guru->find("Samy") >>) instead. Object notation is explained in
849 Make sure to read about creating modules in L<perlmod> and
850 the perils of indirect objects in L<perlobj/"Method Invocation">.
852 =head2 How can I find out my current or calling package?
854 (contributed by brian d foy)
856 To find the package you are currently in, use the special literal
857 C<__PACKAGE__>, as documented in L<perldata>. You can only use the
858 special literals as separate tokens, so you can't interpolate them
859 into strings like you can with variables:
861 my $current_package = __PACKAGE__;
862 print "I am in package $current_package\n";
864 This is different from finding out the package an object is blessed
865 into, which might not be the current package. For that, use C<blessed>
866 from C<Scalar::Util>, part of the Standard Library since Perl 5.8:
868 use Scalar::Util qw(blessed);
869 my $object_package = blessed( $object );
871 Most of the time, you shouldn't care what package an object is blessed
872 into, however, as long as it claims to inherit from that class:
874 my $is_right_class = eval { $object->isa( $package ) }; # true or false
876 If you want to find the package calling your code, perhaps to give better
877 diagnostics as C<Carp> does, use the C<caller> built-in:
881 my( $package, $filename, $line ) = caller;
883 print "I was called from package $package\n";
886 By default, your program starts in package C<main>, so you should
887 always be in some package unless someone uses the C<package> built-in
888 with no namespace. See the C<package> entry in L<perlfunc> for the
889 details of empty packges.
891 =head2 How can I comment out a large block of Perl code?
893 (contributed by brian d foy)
895 The quick-and-dirty way to comment out more than one line of Perl is
896 to surround those lines with Pod directives. You have to put these
897 directives at the beginning of the line and somewhere where Perl
898 expects a new statement (so not in the middle of statements like the #
899 comments). You end the comment with C<=cut>, ending the Pod section:
903 my $object = NotGonnaHappen->new();
907 $wont_be_assigned = 37;
911 The quick-and-dirty method only works well when you don't plan to
912 leave the commented code in the source. If a Pod parser comes along,
913 you're multiline comment is going to show up in the Pod translation.
914 A better way hides it from Pod parsers as well.
916 The C<=begin> directive can mark a section for a particular purpose.
917 If the Pod parser doesn't want to handle it, it just ignores it. Label
918 the comments with C<comment>. End the comment using C<=end> with the
919 same label. You still need the C<=cut> to go back to Perl code from
924 my $object = NotGonnaHappen->new();
928 $wont_be_assigned = 37;
934 For more information on Pod, check out L<perlpod> and L<perlpodspec>.
936 =head2 How do I clear a package?
938 Use this code, provided by Mark-Jason Dominus:
943 die "Shouldn't delete main package"
944 if $pack eq "" || $pack eq "main";
945 my $stash = *{$pack . '::'}{HASH};
947 foreach $name (keys %$stash) {
948 my $fullname = $pack . '::' . $name;
949 # Get rid of everything with that name.
958 Or, if you're using a recent release of Perl, you can
959 just use the Symbol::delete_package() function instead.
961 =head2 How can I use a variable as a variable name?
963 Beginners often think they want to have a variable contain the name
968 ++$$varname; # $fred now 24
970 This works I<sometimes>, but it is a very bad idea for two reasons.
972 The first reason is that this technique I<only works on global
973 variables>. That means that if $fred is a lexical variable created
974 with my() in the above example, the code wouldn't work at all: you'd
975 accidentally access the global and skip right over the private lexical
976 altogether. Global variables are bad because they can easily collide
977 accidentally and in general make for non-scalable and confusing code.
979 Symbolic references are forbidden under the C<use strict> pragma.
980 They are not true references and consequently are not reference counted
981 or garbage collected.
983 The other reason why using a variable to hold the name of another
984 variable is a bad idea is that the question often stems from a lack of
985 understanding of Perl data structures, particularly hashes. By using
986 symbolic references, you are just using the package's symbol-table hash
987 (like C<%main::>) instead of a user-defined hash. The solution is to
988 use your own hash or a real reference instead.
990 $USER_VARS{"fred"} = 23;
992 $USER_VARS{$varname}++; # not $$varname++
994 There we're using the %USER_VARS hash instead of symbolic references.
995 Sometimes this comes up in reading strings from the user with variable
996 references and wanting to expand them to the values of your perl
997 program's variables. This is also a bad idea because it conflates the
998 program-addressable namespace and the user-addressable one. Instead of
999 reading a string and expanding it to the actual contents of your program's
1002 $str = 'this has a $fred and $barney in it';
1003 $str =~ s/(\$\w+)/$1/eeg; # need double eval
1005 it would be better to keep a hash around like %USER_VARS and have
1006 variable references actually refer to entries in that hash:
1008 $str =~ s/\$(\w+)/$USER_VARS{$1}/g; # no /e here at all
1010 That's faster, cleaner, and safer than the previous approach. Of course,
1011 you don't need to use a dollar sign. You could use your own scheme to
1012 make it less confusing, like bracketed percent symbols, etc.
1014 $str = 'this has a %fred% and %barney% in it';
1015 $str =~ s/%(\w+)%/$USER_VARS{$1}/g; # no /e here at all
1017 Another reason that folks sometimes think they want a variable to
1018 contain the name of a variable is because they don't know how to build
1019 proper data structures using hashes. For example, let's say they
1020 wanted two hashes in their program: %fred and %barney, and that they
1021 wanted to use another scalar variable to refer to those by name.
1024 $$name{WIFE} = "wilma"; # set %fred
1027 $$name{WIFE} = "betty"; # set %barney
1029 This is still a symbolic reference, and is still saddled with the
1030 problems enumerated above. It would be far better to write:
1032 $folks{"fred"}{WIFE} = "wilma";
1033 $folks{"barney"}{WIFE} = "betty";
1035 And just use a multilevel hash to start with.
1037 The only times that you absolutely I<must> use symbolic references are
1038 when you really must refer to the symbol table. This may be because it's
1039 something that can't take a real reference to, such as a format name.
1040 Doing so may also be important for method calls, since these always go
1041 through the symbol table for resolution.
1043 In those cases, you would turn off C<strict 'refs'> temporarily so you
1044 can play around with the symbol table. For example:
1046 @colors = qw(red blue green yellow orange purple violet);
1047 for my $name (@colors) {
1048 no strict 'refs'; # renege for the block
1049 *$name = sub { "<FONT COLOR='$name'>@_</FONT>" };
1052 All those functions (red(), blue(), green(), etc.) appear to be separate,
1053 but the real code in the closure actually was compiled only once.
1055 So, sometimes you might want to use symbolic references to directly
1056 manipulate the symbol table. This doesn't matter for formats, handles, and
1057 subroutines, because they are always global--you can't use my() on them.
1058 For scalars, arrays, and hashes, though--and usually for subroutines--
1059 you probably only want to use hard references.
1061 =head2 What does "bad interpreter" mean?
1063 (contributed by brian d foy)
1065 The "bad interpreter" message comes from the shell, not perl. The
1066 actual message may vary depending on your platform, shell, and locale
1069 If you see "bad interpreter - no such file or directory", the first
1070 line in your perl script (the "shebang" line) does not contain the
1071 right path to perl (or any other program capable of running scripts).
1072 Sometimes this happens when you move the script from one machine to
1073 another and each machine has a different path to perl--/usr/bin/perl
1074 versus /usr/local/bin/perl for instance. It may also indicate
1075 that the source machine has CRLF line terminators and the
1076 destination machine has LF only: the shell tries to find
1077 /usr/bin/perl<CR>, but can't.
1079 If you see "bad interpreter: Permission denied", you need to make your
1082 In either case, you should still be able to run the scripts with perl
1087 If you get a message like "perl: command not found", perl is not in
1088 your PATH, which might also mean that the location of perl is not
1089 where you expect it so you need to adjust your shebang line.
1093 Revision: $Revision$
1097 See L<perlfaq> for source control details and availability.
1099 =head1 AUTHOR AND COPYRIGHT
1101 Copyright (c) 1997-2009 Tom Christiansen, Nathan Torkington, and
1102 other authors as noted. All rights reserved.
1104 This documentation is free; you can redistribute it and/or modify it
1105 under the same terms as Perl itself.
1107 Irrespective of its distribution, all code examples in this file
1108 are hereby placed into the public domain. You are permitted and
1109 encouraged to use this code in your own programs for fun
1110 or for profit as you see fit. A simple comment in the code giving
1111 credit would be courteous but is not required.