Re: [MacOS X] consider useshrplib='false' by default
[perl.git] / pod / perlfaq7.pod
1 =head1 NAME
2
3 perlfaq7 - General Perl Language Issues ($Revision: 1.14 $, $Date: 2003/01/31 17:38:14 $)
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     @lines = (
71         "There Beren came from mountains cold",
72         "And lost he wandered under leaves",
73     );
74
75 =head2 How do I skip some return values?
76
77 One way is to treat the return values as a list and index into it:
78
79         $dir = (getpwnam($user))[7];
80
81 Another way is to use undef as an element on the left-hand-side:
82
83     ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
84
85 You can also use a list slice to select only the elements that
86 you need:
87
88         ($dev, $ino, $uid, $gid) = ( stat($file) )[0,1,4,5];
89
90 =head2 How do I temporarily block warnings?
91
92 If you are running Perl 5.6.0 or better, the C<use warnings> pragma
93 allows fine control of what warning are produced.
94 See L<perllexwarn> for more details.
95
96     {
97         no warnings;          # temporarily turn off warnings
98         $a = $b + $c;         # I know these might be undef
99     }
100
101 If you have an older version of Perl, the C<$^W> variable (documented
102 in L<perlvar>) controls runtime warnings for a block:
103
104     {
105         local $^W = 0;        # temporarily turn off warnings
106         $a = $b + $c;         # I know these might be undef
107     }
108
109 Note that like all the punctuation variables, you cannot currently
110 use my() on C<$^W>, only local().
111
112 =head2 What's an extension?
113
114 An extension is a way of calling compiled C code from Perl.  Reading
115 L<perlxstut> is a good place to learn more about extensions.
116
117 =head2 Why do Perl operators have different precedence than C operators?
118
119 Actually, they don't.  All C operators that Perl copies have the same
120 precedence in Perl as they do in C.  The problem is with operators that C
121 doesn't have, especially functions that give a list context to everything
122 on their right, eg. print, chmod, exec, and so on.  Such functions are
123 called "list operators" and appear as such in the precedence table in
124 L<perlop>.
125
126 A common mistake is to write:
127
128     unlink $file || die "snafu";
129
130 This gets interpreted as:
131
132     unlink ($file || die "snafu");
133
134 To avoid this problem, either put in extra parentheses or use the
135 super low precedence C<or> operator:
136
137     (unlink $file) || die "snafu";
138     unlink $file or die "snafu";
139
140 The "English" operators (C<and>, C<or>, C<xor>, and C<not>)
141 deliberately have precedence lower than that of list operators for
142 just such situations as the one above.
143
144 Another operator with surprising precedence is exponentiation.  It
145 binds more tightly even than unary minus, making C<-2**2> product a
146 negative not a positive four.  It is also right-associating, meaning
147 that C<2**3**2> is two raised to the ninth power, not eight squared.
148
149 Although it has the same precedence as in C, Perl's C<?:> operator
150 produces an lvalue.  This assigns $x to either $a or $b, depending
151 on the trueness of $maybe:
152
153     ($maybe ? $a : $b) = $x;
154
155 =head2 How do I declare/create a structure?
156
157 In general, you don't "declare" a structure.  Just use a (probably
158 anonymous) hash reference.  See L<perlref> and L<perldsc> for details.
159 Here's an example:
160
161     $person = {};                   # new anonymous hash
162     $person->{AGE}  = 24;           # set field AGE to 24
163     $person->{NAME} = "Nat";        # set field NAME to "Nat"
164
165 If you're looking for something a bit more rigorous, try L<perltoot>.
166
167 =head2 How do I create a module?
168
169 A module is a package that lives in a file of the same name.  For
170 example, the Hello::There module would live in Hello/There.pm.  For
171 details, read L<perlmod>.  You'll also find L<Exporter> helpful.  If
172 you're writing a C or mixed-language module with both C and Perl, then
173 you should study L<perlxstut>.
174
175 The C<h2xs> program will create stubs for all the important stuff for you:
176
177   % h2xs -XA -n My::Module
178
179 The C<-X> switch tells C<h2xs> that you are not using C<XS> extension
180 code.  The C<-A> switch tells C<h2xs> that you are not using the
181 AutoLoader, and the C<-n> switch specifies the name of the module.
182 See L<h2xs> for more details.
183
184 =head2 How do I create a class?
185
186 See L<perltoot> for an introduction to classes and objects, as well as
187 L<perlobj> and L<perlbot>.
188
189 =head2 How can I tell if a variable is tainted?
190
191 You can use the tainted() function of the Scalar::Util module, available
192 from CPAN (or included with Perl since release 5.8.0).
193 See also L<perlsec/"Laundering and Detecting Tainted Data">.
194
195 =head2 What's a closure?
196
197 Closures are documented in L<perlref>.
198
199 I<Closure> is a computer science term with a precise but
200 hard-to-explain meaning. Closures are implemented in Perl as anonymous
201 subroutines with lasting references to lexical variables outside their
202 own scopes.  These lexicals magically refer to the variables that were
203 around when the subroutine was defined (deep binding).
204
205 Closures make sense in any programming language where you can have the
206 return value of a function be itself a function, as you can in Perl.
207 Note that some languages provide anonymous functions but are not
208 capable of providing proper closures: the Python language, for
209 example.  For more information on closures, check out any textbook on
210 functional programming.  Scheme is a language that not only supports
211 but encourages closures.
212
213 Here's a classic function-generating function:
214
215     sub add_function_generator {
216       return sub { shift + shift };
217     }
218
219     $add_sub = add_function_generator();
220     $sum = $add_sub->(4,5);                # $sum is 9 now.
221
222 The closure works as a I<function template> with some customization
223 slots left out to be filled later.  The anonymous subroutine returned
224 by add_function_generator() isn't technically a closure because it
225 refers to no lexicals outside its own scope.
226
227 Contrast this with the following make_adder() function, in which the
228 returned anonymous function contains a reference to a lexical variable
229 outside the scope of that function itself.  Such a reference requires
230 that Perl return a proper closure, thus locking in for all time the
231 value that the lexical had when the function was created.
232
233     sub make_adder {
234         my $addpiece = shift;
235         return sub { shift + $addpiece };
236     }
237
238     $f1 = make_adder(20);
239     $f2 = make_adder(555);
240
241 Now C<&$f1($n)> is always 20 plus whatever $n you pass in, whereas
242 C<&$f2($n)> is always 555 plus whatever $n you pass in.  The $addpiece
243 in the closure sticks around.
244
245 Closures are often used for less esoteric purposes.  For example, when
246 you want to pass in a bit of code into a function:
247
248     my $line;
249     timeout( 30, sub { $line = <STDIN> } );
250
251 If the code to execute had been passed in as a string,
252 C<< '$line = <STDIN>' >>, there would have been no way for the
253 hypothetical timeout() function to access the lexical variable
254 $line back in its caller's scope.
255
256 =head2 What is variable suicide and how can I prevent it?
257
258 Variable suicide is when you (temporarily or permanently) lose the
259 value of a variable.  It is caused by scoping through my() and local()
260 interacting with either closures or aliased foreach() iterator
261 variables and subroutine arguments.  It used to be easy to
262 inadvertently lose a variable's value this way, but now it's much
263 harder.  Take this code:
264
265     my $f = "foo";
266     sub T {
267       while ($i++ < 3) { my $f = $f; $f .= "bar"; print $f, "\n" }
268     }
269     T;
270     print "Finally $f\n";
271
272 The $f that has "bar" added to it three times should be a new C<$f>
273 (C<my $f> should create a new local variable each time through the loop).
274 It isn't, however.  This was a bug, now fixed in the latest releases
275 (tested against 5.004_05, 5.005_03, and 5.005_56).
276
277 =head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
278
279 With the exception of regexes, you need to pass references to these
280 objects.  See L<perlsub/"Pass by Reference"> for this particular
281 question, and L<perlref> for information on references.
282
283 See ``Passing Regexes'', below, for information on passing regular
284 expressions.
285
286 =over 4
287
288 =item Passing Variables and Functions
289
290 Regular variables and functions are quite easy to pass: just pass in a
291 reference to an existing or anonymous variable or function:
292
293     func( \$some_scalar );
294
295     func( \@some_array  );
296     func( [ 1 .. 10 ]   );
297
298     func( \%some_hash   );
299     func( { this => 10, that => 20 }   );
300
301     func( \&some_func   );
302     func( sub { $_[0] ** $_[1] }   );
303
304 =item Passing Filehandles
305
306 As of Perl 5.6, you can represent filehandles with scalar variables
307 which you treat as any other scalar.
308
309         open my $fh, $filename or die "Cannot open $filename! $!";
310         func( $fh );
311
312         sub func {
313                 my $passed_fh = shift;
314
315                 my $line = <$fh>;
316                 }
317
318 Before Perl 5.6, you had to use the C<*FH> or C<\*FH> notations.
319 These are "typeglobs"--see L<perldata/"Typeglobs and Filehandles">
320 and especially L<perlsub/"Pass by Reference"> for more information.
321
322 =item Passing Regexes
323
324 To pass regexes around, you'll need to be using a release of Perl
325 sufficiently recent as to support the C<qr//> construct, pass around
326 strings and use an exception-trapping eval, or else be very, very clever.
327
328 Here's an example of how to pass in a string to be regex compared
329 using C<qr//>:
330
331     sub compare($$) {
332         my ($val1, $regex) = @_;
333         my $retval = $val1 =~ /$regex/;
334         return $retval;
335     }
336     $match = compare("old McDonald", qr/d.*D/i);
337
338 Notice how C<qr//> allows flags at the end.  That pattern was compiled
339 at compile time, although it was executed later.  The nifty C<qr//>
340 notation wasn't introduced until the 5.005 release.  Before that, you
341 had to approach this problem much less intuitively.  For example, here
342 it is again if you don't have C<qr//>:
343
344     sub compare($$) {
345         my ($val1, $regex) = @_;
346         my $retval = eval { $val1 =~ /$regex/ };
347         die if $@;
348         return $retval;
349     }
350
351     $match = compare("old McDonald", q/($?i)d.*D/);
352
353 Make sure you never say something like this:
354
355     return eval "\$val =~ /$regex/";   # WRONG
356
357 or someone can sneak shell escapes into the regex due to the double
358 interpolation of the eval and the double-quoted string.  For example:
359
360     $pattern_of_evil = 'danger ${ system("rm -rf * &") } danger';
361
362     eval "\$string =~ /$pattern_of_evil/";
363
364 Those preferring to be very, very clever might see the O'Reilly book,
365 I<Mastering Regular Expressions>, by Jeffrey Friedl.  Page 273's
366 Build_MatchMany_Function() is particularly interesting.  A complete
367 citation of this book is given in L<perlfaq2>.
368
369 =item Passing Methods
370
371 To pass an object method into a subroutine, you can do this:
372
373     call_a_lot(10, $some_obj, "methname")
374     sub call_a_lot {
375         my ($count, $widget, $trick) = @_;
376         for (my $i = 0; $i < $count; $i++) {
377             $widget->$trick();
378         }
379     }
380
381 Or, you can use a closure to bundle up the object, its
382 method call, and arguments:
383
384     my $whatnot =  sub { $some_obj->obfuscate(@args) };
385     func($whatnot);
386     sub func {
387         my $code = shift;
388         &$code();
389     }
390
391 You could also investigate the can() method in the UNIVERSAL class
392 (part of the standard perl distribution).
393
394 =back
395
396 =head2 How do I create a static variable?
397
398 As with most things in Perl, TMTOWTDI.  What is a "static variable" in
399 other languages could be either a function-private variable (visible
400 only within a single function, retaining its value between calls to
401 that function), or a file-private variable (visible only to functions
402 within the file it was declared in) in Perl.
403
404 Here's code to implement a function-private variable:
405
406     BEGIN {
407         my $counter = 42;
408         sub prev_counter { return --$counter }
409         sub next_counter { return $counter++ }
410     }
411
412 Now prev_counter() and next_counter() share a private variable $counter
413 that was initialized at compile time.
414
415 To declare a file-private variable, you'll still use a my(), putting
416 the declaration at the outer scope level at the top of the file.
417 Assume this is in file Pax.pm:
418
419     package Pax;
420     my $started = scalar(localtime(time()));
421
422     sub begun { return $started }
423
424 When C<use Pax> or C<require Pax> loads this module, the variable will
425 be initialized.  It won't get garbage-collected the way most variables
426 going out of scope do, because the begun() function cares about it,
427 but no one else can get it.  It is not called $Pax::started because
428 its scope is unrelated to the package.  It's scoped to the file.  You
429 could conceivably have several packages in that same file all
430 accessing the same private variable, but another file with the same
431 package couldn't get to it.
432
433 See L<perlsub/"Persistent Private Variables"> for details.
434
435 =head2 What's the difference between dynamic and lexical (static) scoping?  Between local() and my()?
436
437 C<local($x)> saves away the old value of the global variable C<$x>
438 and assigns a new value for the duration of the subroutine I<which is
439 visible in other functions called from that subroutine>.  This is done
440 at run-time, so is called dynamic scoping.  local() always affects global
441 variables, also called package variables or dynamic variables.
442
443 C<my($x)> creates a new variable that is only visible in the current
444 subroutine.  This is done at compile-time, so it is called lexical or
445 static scoping.  my() always affects private variables, also called
446 lexical variables or (improperly) static(ly scoped) variables.
447
448 For instance:
449
450     sub visible {
451         print "var has value $var\n";
452     }
453
454     sub dynamic {
455         local $var = 'local';   # new temporary value for the still-global
456         visible();              #   variable called $var
457     }
458
459     sub lexical {
460         my $var = 'private';    # new private variable, $var
461         visible();              # (invisible outside of sub scope)
462     }
463
464     $var = 'global';
465
466     visible();                  # prints global
467     dynamic();                  # prints local
468     lexical();                  # prints global
469
470 Notice how at no point does the value "private" get printed.  That's
471 because $var only has that value within the block of the lexical()
472 function, and it is hidden from called subroutine.
473
474 In summary, local() doesn't make what you think of as private, local
475 variables.  It gives a global variable a temporary value.  my() is
476 what you're looking for if you want private variables.
477
478 See L<perlsub/"Private Variables via my()"> and
479 L<perlsub/"Temporary Values via local()"> for excruciating details.
480
481 =head2 How can I access a dynamic variable while a similarly named lexical is in scope?
482
483 If you know your package, you can just mention it explicitly, as in
484 $Some_Pack::var. Note that the notation $::var is B<not> the dynamic $var
485 in the current package, but rather the one in the "main" package, as
486 though you had written $main::var.
487
488         use vars '$var';
489         local $var = "global";
490         my    $var = "lexical";
491
492         print "lexical is $var\n";
493         print "global  is $main::var\n";
494
495 Alternatively you can use the compiler directive our() to bring a
496 dynamic variable into the current lexical scope.
497
498         require 5.006; # our() did not exist before 5.6
499         use vars '$var';
500
501         local $var = "global";
502         my $var    = "lexical";
503
504         print "lexical is $var\n";
505
506         {
507           our $var;
508           print "global  is $var\n";
509         }
510
511 =head2 What's the difference between deep and shallow binding?
512
513 In deep binding, lexical variables mentioned in anonymous subroutines
514 are the same ones that were in scope when the subroutine was created.
515 In shallow binding, they are whichever variables with the same names
516 happen to be in scope when the subroutine is called.  Perl always uses
517 deep binding of lexical variables (i.e., those created with my()).
518 However, dynamic variables (aka global, local, or package variables)
519 are effectively shallowly bound.  Consider this just one more reason
520 not to use them.  See the answer to L<"What's a closure?">.
521
522 =head2 Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
523
524 C<my()> and C<local()> give list context to the right hand side
525 of C<=>.  The <FH> read operation, like so many of Perl's
526 functions and operators, can tell which context it was called in and
527 behaves appropriately.  In general, the scalar() function can help.
528 This function does nothing to the data itself (contrary to popular myth)
529 but rather tells its argument to behave in whatever its scalar fashion is.
530 If that function doesn't have a defined scalar behavior, this of course
531 doesn't help you (such as with sort()).
532
533 To enforce scalar context in this particular case, however, you need
534 merely omit the parentheses:
535
536     local($foo) = <FILE>;           # WRONG
537     local($foo) = scalar(<FILE>);   # ok
538     local $foo  = <FILE>;           # right
539
540 You should probably be using lexical variables anyway, although the
541 issue is the same here:
542
543     my($foo) = <FILE>;  # WRONG
544     my $foo  = <FILE>;  # right
545
546 =head2 How do I redefine a builtin function, operator, or method?
547
548 Why do you want to do that? :-)
549
550 If you want to override a predefined function, such as open(),
551 then you'll have to import the new definition from a different
552 module.  See L<perlsub/"Overriding Built-in Functions">.  There's
553 also an example in L<perltoot/"Class::Template">.
554
555 If you want to overload a Perl operator, such as C<+> or C<**>,
556 then you'll want to use the C<use overload> pragma, documented
557 in L<overload>.
558
559 If you're talking about obscuring method calls in parent classes,
560 see L<perltoot/"Overridden Methods">.
561
562 =head2 What's the difference between calling a function as &foo and foo()?
563
564 When you call a function as C<&foo>, you allow that function access to
565 your current @_ values, and you bypass prototypes.
566 The function doesn't get an empty @_--it gets yours!  While not
567 strictly speaking a bug (it's documented that way in L<perlsub>), it
568 would be hard to consider this a feature in most cases.
569
570 When you call your function as C<&foo()>, then you I<do> get a new @_,
571 but prototyping is still circumvented.
572
573 Normally, you want to call a function using C<foo()>.  You may only
574 omit the parentheses if the function is already known to the compiler
575 because it already saw the definition (C<use> but not C<require>),
576 or via a forward reference or C<use subs> declaration.  Even in this
577 case, you get a clean @_ without any of the old values leaking through
578 where they don't belong.
579
580 =head2 How do I create a switch or case statement?
581
582 This is explained in more depth in the L<perlsyn>.  Briefly, there's
583 no official case statement, because of the variety of tests possible
584 in Perl (numeric comparison, string comparison, glob comparison,
585 regex matching, overloaded comparisons, ...).
586 Larry couldn't decide how best to do this, so he left it out, even
587 though it's been on the wish list since perl1.
588
589 Starting from Perl 5.8 to get switch and case one can use the
590 Switch extension and say:
591
592         use Switch;
593
594 after which one has switch and case.  It is not as fast as it could be
595 because it's not really part of the language (it's done using source
596 filters) but it is available, and it's very flexible.
597
598 But if one wants to use pure Perl, the general answer is to write a
599 construct like this:
600
601     for ($variable_to_test) {
602         if    (/pat1/)  { }     # do something
603         elsif (/pat2/)  { }     # do something else
604         elsif (/pat3/)  { }     # do something else
605         else            { }     # default
606     }
607
608 Here's a simple example of a switch based on pattern matching, this
609 time lined up in a way to make it look more like a switch statement.
610 We'll do a multiway conditional based on the type of reference stored
611 in $whatchamacallit:
612
613     SWITCH: for (ref $whatchamacallit) {
614
615         /^$/            && die "not a reference";
616
617         /SCALAR/        && do {
618                                 print_scalar($$ref);
619                                 last SWITCH;
620                         };
621
622         /ARRAY/         && do {
623                                 print_array(@$ref);
624                                 last SWITCH;
625                         };
626
627         /HASH/          && do {
628                                 print_hash(%$ref);
629                                 last SWITCH;
630                         };
631
632         /CODE/          && do {
633                                 warn "can't print function ref";
634                                 last SWITCH;
635                         };
636
637         # DEFAULT
638
639         warn "User defined type skipped";
640
641     }
642
643 See C<perlsyn/"Basic BLOCKs and Switch Statements"> for many other
644 examples in this style.
645
646 Sometimes you should change the positions of the constant and the variable.
647 For example, let's say you wanted to test which of many answers you were
648 given, but in a case-insensitive way that also allows abbreviations.
649 You can use the following technique if the strings all start with
650 different characters or if you want to arrange the matches so that
651 one takes precedence over another, as C<"SEND"> has precedence over
652 C<"STOP"> here:
653
654     chomp($answer = <>);
655     if    ("SEND"  =~ /^\Q$answer/i) { print "Action is send\n"  }
656     elsif ("STOP"  =~ /^\Q$answer/i) { print "Action is stop\n"  }
657     elsif ("ABORT" =~ /^\Q$answer/i) { print "Action is abort\n" }
658     elsif ("LIST"  =~ /^\Q$answer/i) { print "Action is list\n"  }
659     elsif ("EDIT"  =~ /^\Q$answer/i) { print "Action is edit\n"  }
660
661 A totally different approach is to create a hash of function references.
662
663     my %commands = (
664         "happy" => \&joy,
665         "sad",  => \&sullen,
666         "done"  => sub { die "See ya!" },
667         "mad"   => \&angry,
668     );
669
670     print "How are you? ";
671     chomp($string = <STDIN>);
672     if ($commands{$string}) {
673         $commands{$string}->();
674     } else {
675         print "No such command: $string\n";
676     }
677
678 =head2 How can I catch accesses to undefined variables, functions, or methods?
679
680 The AUTOLOAD method, discussed in L<perlsub/"Autoloading"> and
681 L<perltoot/"AUTOLOAD: Proxy Methods">, lets you capture calls to
682 undefined functions and methods.
683
684 When it comes to undefined variables that would trigger a warning
685 under C<use warnings>, you can promote the warning to an error.
686
687         use warnings FATAL => qw(uninitialized);
688
689 =head2 Why can't a method included in this same file be found?
690
691 Some possible reasons: your inheritance is getting confused, you've
692 misspelled the method name, or the object is of the wrong type.  Check
693 out L<perltoot> for details about any of the above cases.  You may
694 also use C<print ref($object)> to find out the class C<$object> was
695 blessed into.
696
697 Another possible reason for problems is because you've used the
698 indirect object syntax (eg, C<find Guru "Samy">) on a class name
699 before Perl has seen that such a package exists.  It's wisest to make
700 sure your packages are all defined before you start using them, which
701 will be taken care of if you use the C<use> statement instead of
702 C<require>.  If not, make sure to use arrow notation (eg.,
703 C<< Guru->find("Samy") >>) instead.  Object notation is explained in
704 L<perlobj>.
705
706 Make sure to read about creating modules in L<perlmod> and
707 the perils of indirect objects in L<perlobj/"Method Invocation">.
708
709 =head2 How can I find out my current package?
710
711 If you're just a random program, you can do this to find
712 out what the currently compiled package is:
713
714     my $packname = __PACKAGE__;
715
716 But, if you're a method and you want to print an error message
717 that includes the kind of object you were called on (which is
718 not necessarily the same as the one in which you were compiled):
719
720     sub amethod {
721         my $self  = shift;
722         my $class = ref($self) || $self;
723         warn "called me from a $class object";
724     }
725
726 =head2 How can I comment out a large block of perl code?
727
728 You can use embedded POD to discard it.  The =for directive
729 lasts until the next paragraph (two consecutive newlines).
730
731     # program is here
732
733     =for nobody
734     This paragraph is commented out
735
736     # program continues
737
738 The =begin and =end directives can contain multiple
739 paragraphs.
740
741     =begin comment text
742
743     all of this stuff
744
745     here will be ignored
746     by everyone
747
748     =end comment text
749
750 The pod directives cannot go just anywhere.  You must put a
751 pod directive where the parser is expecting a new statement,
752 not just in the middle of an expression or some other
753 arbitrary s grammar production.
754
755 See L<perlpod> for more details.
756
757 =head2 How do I clear a package?
758
759 Use this code, provided by Mark-Jason Dominus:
760
761     sub scrub_package {
762         no strict 'refs';
763         my $pack = shift;
764         die "Shouldn't delete main package"
765             if $pack eq "" || $pack eq "main";
766         my $stash = *{$pack . '::'}{HASH};
767         my $name;
768         foreach $name (keys %$stash) {
769             my $fullname = $pack . '::' . $name;
770             # Get rid of everything with that name.
771             undef $$fullname;
772             undef @$fullname;
773             undef %$fullname;
774             undef &$fullname;
775             undef *$fullname;
776         }
777     }
778
779 Or, if you're using a recent release of Perl, you can
780 just use the Symbol::delete_package() function instead.
781
782 =head2 How can I use a variable as a variable name?
783
784 Beginners often think they want to have a variable contain the name
785 of a variable.
786
787     $fred    = 23;
788     $varname = "fred";
789     ++$$varname;         # $fred now 24
790
791 This works I<sometimes>, but it is a very bad idea for two reasons.
792
793 The first reason is that this technique I<only works on global
794 variables>.  That means that if $fred is a lexical variable created
795 with my() in the above example, the code wouldn't work at all: you'd
796 accidentally access the global and skip right over the private lexical
797 altogether.  Global variables are bad because they can easily collide
798 accidentally and in general make for non-scalable and confusing code.
799
800 Symbolic references are forbidden under the C<use strict> pragma.
801 They are not true references and consequently are not reference counted
802 or garbage collected.
803
804 The other reason why using a variable to hold the name of another
805 variable is a bad idea is that the question often stems from a lack of
806 understanding of Perl data structures, particularly hashes.  By using
807 symbolic references, you are just using the package's symbol-table hash
808 (like C<%main::>) instead of a user-defined hash.  The solution is to
809 use your own hash or a real reference instead.
810
811     $fred    = 23;
812     $varname = "fred";
813     $USER_VARS{$varname}++;  # not $$varname++
814
815 There we're using the %USER_VARS hash instead of symbolic references.
816 Sometimes this comes up in reading strings from the user with variable
817 references and wanting to expand them to the values of your perl
818 program's variables.  This is also a bad idea because it conflates the
819 program-addressable namespace and the user-addressable one.  Instead of
820 reading a string and expanding it to the actual contents of your program's
821 own variables:
822
823     $str = 'this has a $fred and $barney in it';
824     $str =~ s/(\$\w+)/$1/eeg;             # need double eval
825
826 it would be better to keep a hash around like %USER_VARS and have
827 variable references actually refer to entries in that hash:
828
829     $str =~ s/\$(\w+)/$USER_VARS{$1}/g;   # no /e here at all
830
831 That's faster, cleaner, and safer than the previous approach.  Of course,
832 you don't need to use a dollar sign.  You could use your own scheme to
833 make it less confusing, like bracketed percent symbols, etc.
834
835     $str = 'this has a %fred% and %barney% in it';
836     $str =~ s/%(\w+)%/$USER_VARS{$1}/g;   # no /e here at all
837
838 Another reason that folks sometimes think they want a variable to
839 contain the name of a variable is because they don't know how to build
840 proper data structures using hashes.  For example, let's say they
841 wanted two hashes in their program: %fred and %barney, and that they
842 wanted to use another scalar variable to refer to those by name.
843
844     $name = "fred";
845     $$name{WIFE} = "wilma";     # set %fred
846
847     $name = "barney";
848     $$name{WIFE} = "betty";     # set %barney
849
850 This is still a symbolic reference, and is still saddled with the
851 problems enumerated above.  It would be far better to write:
852
853     $folks{"fred"}{WIFE}   = "wilma";
854     $folks{"barney"}{WIFE} = "betty";
855
856 And just use a multilevel hash to start with.
857
858 The only times that you absolutely I<must> use symbolic references are
859 when you really must refer to the symbol table.  This may be because it's
860 something that can't take a real reference to, such as a format name.
861 Doing so may also be important for method calls, since these always go
862 through the symbol table for resolution.
863
864 In those cases, you would turn off C<strict 'refs'> temporarily so you
865 can play around with the symbol table.  For example:
866
867     @colors = qw(red blue green yellow orange purple violet);
868     for my $name (@colors) {
869         no strict 'refs';  # renege for the block
870         *$name = sub { "<FONT COLOR='$name'>@_</FONT>" };
871     }
872
873 All those functions (red(), blue(), green(), etc.) appear to be separate,
874 but the real code in the closure actually was compiled only once.
875
876 So, sometimes you might want to use symbolic references to directly
877 manipulate the symbol table.  This doesn't matter for formats, handles, and
878 subroutines, because they are always global--you can't use my() on them.
879 For scalars, arrays, and hashes, though--and usually for subroutines--
880 you probably only want to use hard references.
881
882 =head2 What does "bad interpreter" mean?
883
884 The "bad interpreter" message comes from the shell, not perl.  The
885 actual message may vary depending on your platform, shell, and locale
886 settings.
887
888 If you see "bad interpreter - no such file or directory", the first
889 line in your perl script (the "shebang" line) does not contain the
890 right path to perl (or any other program capable of running scripts). 
891 Sometimes this happens when you move the script from one machine to
892 another and each machine has a different path to perl---/usr/bin/perl
893 versus /usr/local/bin/perl for instance.
894
895 If you see "bad interpreter: Permission denied", you need to make your
896 script executable.
897
898 In either case, you should still be able to run the scripts with perl
899 explicitly:
900
901         % perl script.pl
902
903 If you get a message like "perl: command not found", perl is not in
904 your PATH, which might also mean that the location of perl is not
905 where you expect it so you need to adjust your shebang line.
906
907 =head1 AUTHOR AND COPYRIGHT
908
909 Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington.
910 All rights reserved.
911
912 This documentation is free; you can redistribute it and/or modify it
913 under the same terms as Perl itself.
914
915 Irrespective of its distribution, all code examples in this file
916 are hereby placed into the public domain.  You are permitted and
917 encouraged to use this code in your own programs for fun
918 or for profit as you see fit.  A simple comment in the code giving
919 credit would be courteous but is not required.
920