Put a watchdog on openpid.t: it has been found to hang in some Win32 smokes.
[perl.git] / pod / perlfaq7.pod
1 =head1 NAME
2
3 perlfaq7 - General Perl Language Issues
4
5 =head1 DESCRIPTION
6
7 This section deals with general Perl language issues that don't
8 clearly fit into any of the other sections.
9
10 =head2 Can I get a BNF/yacc/RE for the Perl language?
11
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.
16
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
19 and mirrors."
20
21 =head2 What are all these $@%&* punctuation signs, and how do I know when to use them?
22
23 They are type specifiers, as detailed in L<perldata>:
24
25         $ for scalar values (number, string or reference)
26         @ for arrays
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.
31
32 There are couple of other symbols that you're likely to encounter that aren't
33 really type specifiers:
34
35         <> are used for inputting a record from a filehandle.
36         \  takes a reference to something.
37
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".
46
47 =head2 Do I always/never have to quote my strings or use semicolons and commas?
48
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:
54
55         This                    is like this
56         ------------            ---------------
57         $foo{line}              $foo{'line'}
58         bar => stuff            'bar' => stuff
59
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
62 one-liners:
63
64         if ($whoops) { exit 1 }
65         @nums = (1, 2, 3);
66
67         if ($whoops) {
68                 exit 1;
69         }
70
71         @lines = (
72         "There Beren came from mountains cold",
73         "And lost he wandered under leaves",
74         );
75
76 =head2 How do I skip some return values?
77
78 One way is to treat the return values as a list and index into it:
79
80         $dir = (getpwnam($user))[7];
81
82 Another way is to use undef as an element on the left-hand-side:
83
84         ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
85
86 You can also use a list slice to select only the elements that
87 you need:
88
89         ($dev, $ino, $uid, $gid) = ( stat($file) )[0,1,4,5];
90
91 =head2 How do I temporarily block warnings?
92
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.
96
97         {
98         no warnings;          # temporarily turn off warnings
99         $a = $b + $c;         # I know these might be undef
100         }
101
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.
106
107         {
108         no warnings 'uninitialized';
109         $a = $b + $c;
110         }
111
112 If you have an older version of Perl, the C<$^W> variable (documented
113 in L<perlvar>) controls runtime warnings for a block:
114
115         {
116         local $^W = 0;        # temporarily turn off warnings
117         $a = $b + $c;         # I know these might be undef
118         }
119
120 Note that like all the punctuation variables, you cannot currently
121 use my() on C<$^W>, only local().
122
123 =head2 What's an extension?
124
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.
127
128 =head2 Why do Perl operators have different precedence than C operators?
129
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
135 L<perlop>.
136
137 A common mistake is to write:
138
139         unlink $file || die "snafu";
140
141 This gets interpreted as:
142
143         unlink ($file || die "snafu");
144
145 To avoid this problem, either put in extra parentheses or use the
146 super low precedence C<or> operator:
147
148         (unlink $file) || die "snafu";
149         unlink $file or die "snafu";
150
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.
154
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.
159
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:
163
164         ($maybe ? $a : $b) = $x;
165
166 =head2 How do I declare/create a structure?
167
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.
170 Here's an example:
171
172         $person = {};                   # new anonymous hash
173         $person->{AGE}  = 24;           # set field AGE to 24
174         $person->{NAME} = "Nat";        # set field NAME to "Nat"
175
176 If you're looking for something a bit more rigorous, try L<perltoot>.
177
178 =head2 How do I create a module?
179
180 (contributed by brian d foy)
181
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
185 about style.
186
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.
191
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.
195
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
199 distributions.
200
201 =head2 How do I adopt or take over a module already on CPAN?
202
203 (contributed by brian d foy)
204
205 The full answer to this can be found at
206 http://cpan.org/modules/04pause.html#takeover
207
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
210 the module to you.
211
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.
215
216 =over 4
217
218 =item
219
220 Get a login for the Perl Authors Upload Server (PAUSE) if you don't
221 already have one: http://pause.perl.org
222
223 =item
224
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
227 maintainer.
228
229 =item
230
231 Post a public message in a heavily trafficked site announcing your
232 intention to take over the module.
233
234 =item
235
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
239 it to you.
240
241 =back
242
243 =head2 How do I create a class?
244 X<class, creation> X<package>
245
246 (contributed by brian d foy)
247
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
251 you).
252
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>.
257
258 =head2 How can I tell if a variable is tainted?
259
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">.
263
264 =head2 What's a closure?
265
266 Closures are documented in L<perlref>.
267
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
273 binding).
274
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.
282
283 Here's a classic non-closure function-generating function:
284
285         sub add_function_generator {
286                 return sub { shift() + shift() };
287                 }
288
289         $add_sub = add_function_generator();
290         $sum = $add_sub->(4,5);                # $sum is 9 now.
291
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.
296
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.
302
303         sub make_adder {
304                 my $addpiece = shift;
305                 return sub { shift() + $addpiece };
306         }
307
308         $f1 = make_adder(20);
309         $f2 = make_adder(555);
310
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.
314
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:
317
318         my $line;
319         timeout( 30, sub { $line = <STDIN> } );
320
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.
325
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
331 package:
332
333         BEGIN {
334                 my $id = 0;
335                 sub next_id { ++$id }
336         }
337
338 This is discussed in more detail in L<perlsub>, see the entry on
339 I<Persistent Private Variables>.
340
341 =head2 What is variable suicide and how can I prevent it?
342
343 This problem was fixed in perl 5.004_05, so preventing it means upgrading
344 your version of perl. ;)
345
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:
351
352         my $f = 'foo';
353         sub T {
354                 while ($i++ < 3) { my $f = $f; $f .= "bar"; print $f, "\n" }
355                 }
356
357         T;
358         print "Finally $f\n";
359
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:
364
365         foobar
366         foobarbar
367         foobarbarbar
368         Finally foo
369
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:
373
374         foobar
375         foobar
376         foobar
377         Finally foo
378
379 =head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
380
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.
384
385 See "Passing Regexes", later in L<perlfaq7>, for information on
386 passing regular expressions.
387
388 =over 4
389
390 =item Passing Variables and Functions
391
392 Regular variables and functions are quite easy to pass: just pass in a
393 reference to an existing or anonymous variable or function:
394
395         func( \$some_scalar );
396
397         func( \@some_array  );
398         func( [ 1 .. 10 ]   );
399
400         func( \%some_hash   );
401         func( { this => 10, that => 20 }   );
402
403         func( \&some_func   );
404         func( sub { $_[0] ** $_[1] }   );
405
406 =item Passing Filehandles
407
408 As of Perl 5.6, you can represent filehandles with scalar variables
409 which you treat as any other scalar.
410
411         open my $fh, $filename or die "Cannot open $filename! $!";
412         func( $fh );
413
414         sub func {
415                 my $passed_fh = shift;
416
417                 my $line = <$passed_fh>;
418                 }
419
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.
423
424 =item Passing Regexes
425
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.
429
430 Here's an example of how to pass in a string to be regex compared
431 using C<qr//>:
432
433         sub compare($$) {
434                 my ($val1, $regex) = @_;
435                 my $retval = $val1 =~ /$regex/;
436         return $retval;
437         }
438         $match = compare("old McDonald", qr/d.*D/i);
439
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//>:
445
446         sub compare($$) {
447                 my ($val1, $regex) = @_;
448                 my $retval = eval { $val1 =~ /$regex/ };
449         die if $@;
450         return $retval;
451         }
452
453         $match = compare("old McDonald", q/($?i)d.*D/);
454
455 Make sure you never say something like this:
456
457         return eval "\$val =~ /$regex/";   # WRONG
458
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:
461
462         $pattern_of_evil = 'danger ${ system("rm -rf * &") } danger';
463
464         eval "\$string =~ /$pattern_of_evil/";
465
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>.
470
471 =item Passing Methods
472
473 To pass an object method into a subroutine, you can do this:
474
475         call_a_lot(10, $some_obj, "methname")
476         sub call_a_lot {
477                 my ($count, $widget, $trick) = @_;
478                 for (my $i = 0; $i < $count; $i++) {
479                         $widget->$trick();
480                 }
481         }
482
483 Or, you can use a closure to bundle up the object, its
484 method call, and arguments:
485
486         my $whatnot =  sub { $some_obj->obfuscate(@args) };
487         func($whatnot);
488         sub func {
489                 my $code = shift;
490                 &$code();
491         }
492
493 You could also investigate the can() method in the UNIVERSAL class
494 (part of the standard perl distribution).
495
496 =back
497
498 =head2 How do I create a static variable?
499
500 (contributed by brian d foy)
501
502 In Perl 5.10, declare the variable with C<state>. The C<state>
503 declaration creates the lexical variable that persists between calls
504 to the subroutine:
505
506         sub counter { state $count = 1; $counter++ }
507
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
520 C<counter>.
521
522         BEGIN {
523                 my $count = 1;
524                 sub counter { $count++ }
525         }
526
527         my $start = counter();
528
529         .... # code that calls counter();
530
531         my $end = counter();
532
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.
543
544         BEGIN {
545                 my $count = 1;
546                 sub increment_count { $count++ }
547                 sub return_count    { $count }
548         }
549
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.
553
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.
558
559 =head2 What's the difference between dynamic and lexical (static) scoping?  Between local() and my()?
560
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.
566
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.
571
572 For instance:
573
574         sub visible {
575                 print "var has value $var\n";
576                 }
577
578         sub dynamic {
579                 local $var = 'local';   # new temporary value for the still-global
580                 visible();              #   variable called $var
581                 }
582
583         sub lexical {
584                 my $var = 'private';    # new private variable, $var
585                 visible();              # (invisible outside of sub scope)
586                 }
587
588         $var = 'global';
589
590         visible();                      # prints global
591         dynamic();                      # prints local
592         lexical();                      # prints global
593
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.
597
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.
601
602 See L<perlsub/"Private Variables via my()"> and
603 L<perlsub/"Temporary Values via local()"> for excruciating details.
604
605 =head2 How can I access a dynamic variable while a similarly named lexical is in scope?
606
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.
611
612         use vars '$var';
613         local $var = "global";
614         my    $var = "lexical";
615
616         print "lexical is $var\n";
617         print "global  is $main::var\n";
618
619 Alternatively you can use the compiler directive our() to bring a
620 dynamic variable into the current lexical scope.
621
622         require 5.006; # our() did not exist before 5.6
623         use vars '$var';
624
625         local $var = "global";
626         my $var    = "lexical";
627
628         print "lexical is $var\n";
629
630         {
631                 our $var;
632                 print "global  is $var\n";
633         }
634
635 =head2 What's the difference between deep and shallow binding?
636
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?">.
645
646 =head2 Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
647
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()).
656
657 To enforce scalar context in this particular case, however, you need
658 merely omit the parentheses:
659
660         local($foo) = <FILE>;       # WRONG
661         local($foo) = scalar(<FILE>);   # ok
662         local $foo  = <FILE>;       # right
663
664 You should probably be using lexical variables anyway, although the
665 issue is the same here:
666
667         my($foo) = <FILE>;      # WRONG
668         my $foo  = <FILE>;      # right
669
670 =head2 How do I redefine a builtin function, operator, or method?
671
672 Why do you want to do that? :-)
673
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">.
678
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
681 in L<overload>.
682
683 If you're talking about obscuring method calls in parent classes,
684 see L<perltoot/"Overridden Methods">.
685
686 =head2 What's the difference between calling a function as &foo and foo()?
687
688 (contributed by brian d foy)
689
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:
694
695         sub bar { &foo }
696
697         sub foo { print "Args in foo are: @_\n" }
698
699         bar( qw( a b c ) );
700
701 When you call C<bar> with arguments, you see that C<foo> got the same C<@_>:
702
703         Args in foo are: a b c
704
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:
708
709         sub bar { &foo() }
710
711         sub foo { print "Args in foo are: @_\n" }
712
713         bar( qw( a b c ) );
714
715 Now the output shows that C<foo> doesn't get the C<@_> from its caller.
716
717         Args in foo are:
718
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>.
722
723 =head2 How do I create a switch or case statement?
724
725 In Perl 5.10, use the C<given-when> construct described in L<perlsyn>:
726
727         use 5.010;
728
729         given ( $string ) {
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!" }
734                 };
735
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>:
738
739         for ($variable_to_test) {
740                 if    (/pat1/)  { }     # do something
741                 elsif (/pat2/)  { }     # do something else
742                 elsif (/pat3/)  { }     # do something else
743                 else            { }     # default
744                 }
745
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
749 in $whatchamacallit:
750
751     SWITCH: for (ref $whatchamacallit) {
752
753         /^$/            && die "not a reference";
754
755         /SCALAR/        && do {
756                                 print_scalar($$ref);
757                                 last SWITCH;
758                         };
759
760         /ARRAY/         && do {
761                                 print_array(@$ref);
762                                 last SWITCH;
763                         };
764
765         /HASH/          && do {
766                                 print_hash(%$ref);
767                                 last SWITCH;
768                         };
769
770         /CODE/          && do {
771                                 warn "can't print function ref";
772                                 last SWITCH;
773                         };
774
775         # DEFAULT
776
777         warn "User defined type skipped";
778
779     }
780
781 See L<perlsyn> for other examples in this style.
782
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
789 C<"STOP"> here:
790
791         chomp($answer = <>);
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"  }
797
798 A totally different approach is to create a hash of function references.
799
800         my %commands = (
801                 "happy" => \&joy,
802                 "sad",  => \&sullen,
803                 "done"  => sub { die "See ya!" },
804                 "mad"   => \&angry,
805         );
806
807         print "How are you? ";
808         chomp($string = <STDIN>);
809         if ($commands{$string}) {
810                 $commands{$string}->();
811         } else {
812                 print "No such command: $string\n";
813         }
814
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.
820
821 =head2 How can I catch accesses to undefined variables, functions, or methods?
822
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.
826
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.
829
830         use warnings FATAL => qw(uninitialized);
831
832 =head2 Why can't a method included in this same file be found?
833
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
838 blessed into.
839
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
847 L<perlobj>.
848
849 Make sure to read about creating modules in L<perlmod> and
850 the perils of indirect objects in L<perlobj/"Method Invocation">.
851
852 =head2 How can I find out my current or calling package?
853
854 (contributed by brian d foy)
855
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:
860
861         my $current_package = __PACKAGE__;
862         print "I am in package $current_package\n";
863
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:
867
868         use Scalar::Util qw(blessed);
869         my $object_package = blessed( $object );
870
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:
873
874         my $is_right_class = eval { $object->isa( $package ) }; # true or false
875
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:
878
879         sub foo {
880                 my @args = ...;
881                 my( $package, $filename, $line ) = caller;
882
883                 print "I was called from package $package\n";
884                 );
885
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.
890
891 =head2 How can I comment out a large block of Perl code?
892
893 (contributed by brian d foy)
894
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:
900
901         =pod
902
903         my $object = NotGonnaHappen->new();
904
905         ignored_sub();
906
907         $wont_be_assigned = 37;
908
909         =cut
910
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. 
915
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
920 the Pod comment:
921
922         =begin comment
923
924         my $object = NotGonnaHappen->new();
925
926         ignored_sub();
927
928         $wont_be_assigned = 37;
929
930         =end comment
931
932         =cut
933
934 For more information on Pod, check out L<perlpod> and L<perlpodspec>.
935
936 =head2 How do I clear a package?
937
938 Use this code, provided by Mark-Jason Dominus:
939
940         sub scrub_package {
941                 no strict 'refs';
942                 my $pack = shift;
943                 die "Shouldn't delete main package"
944                         if $pack eq "" || $pack eq "main";
945                 my $stash = *{$pack . '::'}{HASH};
946                 my $name;
947                 foreach $name (keys %$stash) {
948                         my $fullname = $pack . '::' . $name;
949                         # Get rid of everything with that name.
950                         undef $$fullname;
951                         undef @$fullname;
952                         undef %$fullname;
953                         undef &$fullname;
954                         undef *$fullname;
955         }
956         }
957
958 Or, if you're using a recent release of Perl, you can
959 just use the Symbol::delete_package() function instead.
960
961 =head2 How can I use a variable as a variable name?
962
963 Beginners often think they want to have a variable contain the name
964 of a variable.
965
966         $fred    = 23;
967         $varname = "fred";
968         ++$$varname;         # $fred now 24
969
970 This works I<sometimes>, but it is a very bad idea for two reasons.
971
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.
978
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.
982
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.
989
990         $USER_VARS{"fred"} = 23;
991         $varname = "fred";
992         $USER_VARS{$varname}++;  # not $$varname++
993
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
1000 own variables:
1001
1002         $str = 'this has a $fred and $barney in it';
1003         $str =~ s/(\$\w+)/$1/eeg;                 # need double eval
1004
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:
1007
1008         $str =~ s/\$(\w+)/$USER_VARS{$1}/g;   # no /e here at all
1009
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.
1013
1014         $str = 'this has a %fred% and %barney% in it';
1015         $str =~ s/%(\w+)%/$USER_VARS{$1}/g;   # no /e here at all
1016
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.
1022
1023         $name = "fred";
1024         $$name{WIFE} = "wilma";     # set %fred
1025
1026         $name = "barney";
1027         $$name{WIFE} = "betty"; # set %barney
1028
1029 This is still a symbolic reference, and is still saddled with the
1030 problems enumerated above.  It would be far better to write:
1031
1032         $folks{"fred"}{WIFE}   = "wilma";
1033         $folks{"barney"}{WIFE} = "betty";
1034
1035 And just use a multilevel hash to start with.
1036
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.
1042
1043 In those cases, you would turn off C<strict 'refs'> temporarily so you
1044 can play around with the symbol table.  For example:
1045
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>" };
1050         }
1051
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.
1054
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.
1060
1061 =head2 What does "bad interpreter" mean?
1062
1063 (contributed by brian d foy)
1064
1065 The "bad interpreter" message comes from the shell, not perl.  The
1066 actual message may vary depending on your platform, shell, and locale
1067 settings.
1068
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.
1078
1079 If you see "bad interpreter: Permission denied", you need to make your
1080 script executable.
1081
1082 In either case, you should still be able to run the scripts with perl
1083 explicitly:
1084
1085         % perl script.pl
1086
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.
1090
1091 =head1 REVISION
1092
1093 Revision: $Revision$
1094
1095 Date: $Date$
1096
1097 See L<perlfaq> for source control details and availability.
1098
1099 =head1 AUTHOR AND COPYRIGHT
1100
1101 Copyright (c) 1997-2009 Tom Christiansen, Nathan Torkington, and
1102 other authors as noted. All rights reserved.
1103
1104 This documentation is free; you can redistribute it and/or modify it
1105 under the same terms as Perl itself.
1106
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.
1112