X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfaq7.pod;h=54e91bda9ba7c37f9ec911c881bf4b60ab5e687a;hb=a537debe17982e491ffa12d12441cf74a452acb2;hp=10b5d255009026317757e0b157bb15110f522449;hpb=ae93639c6e66959ff84ce19b7b13b05a1ca356b7;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod index 10b5d25..54e91bd 100644 --- a/pod/perlfaq7.pod +++ b/pod/perlfaq7.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq7 - Perl Language Issues ($Revision: 1.28 $, $Date: 1999/05/23 20:36:18 $) +perlfaq7 - General Perl Language Issues ($Revision: 1.18 $, $Date: 2004/11/03 22:54:08 $) =head1 DESCRIPTION @@ -38,7 +38,7 @@ really type specifiers: Note that is I the type specifier for files nor the name of the handle. It is the C<< <> >> operator applied to the handle FILE. It reads one line (well, record--see -L) from the handle FILE in scalar context, or I lines +L>) from the handle FILE in scalar context, or I lines in list context. When performing open, close, or any other operation besides C<< <> >> on files, or even when talking about the handle, do I use the brackets. These are correct: C, C pragma @@ -92,6 +97,16 @@ See L for more details. no warnings; # temporarily turn off warnings $a = $b + $c; # I know these might be undef } + +Additionally, you can enable and disable categories of warnings. +You turn off the categories you want to ignore and you can still +get other categories of warnings. See L for the +complete details, including the category names and hierarchy. + + { + no warnings 'uninitialized'; + $a = $b + $c; + } If you have an older version of Perl, the C<$^W> variable (documented in L) controls runtime warnings for a block: @@ -167,81 +182,15 @@ details, read L. You'll also find L helpful. If you're writing a C or mixed-language module with both C and Perl, then you should study L. -Here's a convenient template you might wish you use when starting your -own module. Make sure to change the names appropriately. - - package Some::Module; # assumes Some/Module.pm - - use strict; - use warnings; - - BEGIN { - use Exporter (); - our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS); - - ## set the version for version checking; uncomment to use - ## $VERSION = 1.00; - - # if using RCS/CVS, this next line may be preferred, - # but beware two-digit versions. - $VERSION = do{my@r=q$Revision: 1.28 $=~/\d+/g;sprintf '%d.'.'%02d'x$#r,@r}; - - @ISA = qw(Exporter); - @EXPORT = qw(&func1 &func2 &func3); - %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ], - - # your exported package globals go here, - # as well as any optionally exported functions - @EXPORT_OK = qw($Var1 %Hashit); - } - our @EXPORT_OK; - - # exported package globals go here - our $Var1; - our %Hashit; - - # non-exported package globals go here - our @more; - our $stuff; - - # initialize package globals, first exported ones - $Var1 = ''; - %Hashit = (); - - # then the others (which are still accessible as $Some::Module::stuff) - $stuff = ''; - @more = (); - - # all file-scoped lexicals must be created before - # the functions below that use them. - - # file-private lexicals go here - my $priv_var = ''; - my %secret_hash = (); - - # here's a file-private function as a closure, - # callable as &$priv_func; it cannot be prototyped. - my $priv_func = sub { - # stuff goes here. - }; - - # make all your functions, whether exported or not; - # remember to put something interesting in the {} stubs - sub func1 {} # no prototype - sub func2() {} # proto'd void - sub func3($$) {} # proto'd to 2 scalars - - # this one isn't exported, but could be called! - sub func4(\%) {} # proto'd to 1 hash ref - - END { } # module clean-up code here (global destructor) - - 1; # modules must return true - -The h2xs program will create stubs for all the important stuff for you: +The C program will create stubs for all the important stuff for you: % h2xs -XA -n My::Module +The C<-X> switch tells C that you are not using C extension +code. The C<-A> switch tells C that you are not using the +AutoLoader, and the C<-n> switch specifies the name of the module. +See L for more details. + =head2 How do I create a class? See L for an introduction to classes and objects, as well as @@ -249,17 +198,9 @@ L and L. =head2 How can I tell if a variable is tainted? -See L. Here's an -example (which doesn't use any system calls, because the kill() -is given no processes to signal): - - sub is_tainted { - return ! eval { join('',@_), kill 0; 1; }; - } - -This is not C<-w> clean, however. There is no C<-w> clean way to -detect taintedness--take this as a hint that you should untaint -all possibly-tainted data. +You can use the tainted() function of the Scalar::Util module, available +from CPAN (or included with Perl since release 5.8.0). +See also L. =head2 What's a closure? @@ -282,7 +223,7 @@ but encourages closures. Here's a classic function-generating function: sub add_function_generator { - return sub { shift + shift }; + return sub { shift() + shift() }; } $add_sub = add_function_generator(); @@ -301,7 +242,7 @@ value that the lexical had when the function was created. sub make_adder { my $addpiece = shift; - return sub { shift + $addpiece }; + return sub { shift() + $addpiece }; } $f1 = make_adder(20); @@ -372,37 +313,21 @@ reference to an existing or anonymous variable or function: =item Passing Filehandles -To pass filehandles to subroutines, use the C<*FH> or C<\*FH> notations. -These are "typeglobs"--see L -and especially L for more information. - -Here's an excerpt: - -If you're passing around filehandles, you could usually just use the bare -typeglob, like *STDOUT, but typeglobs references would be better because -they'll still work properly under C. For example: +As of Perl 5.6, you can represent filehandles with scalar variables +which you treat as any other scalar. - splutter(\*STDOUT); - sub splutter { - my $fh = shift; - print $fh "her um well a hmmm\n"; - } + open my $fh, $filename or die "Cannot open $filename! $!"; + func( $fh ); - $rec = get_rec(\*STDIN); - sub get_rec { - my $fh = shift; - return scalar <$fh>; - } + sub func { + my $passed_fh = shift; -If you're planning on generating new filehandles, you could do this: + my $line = <$fh>; + } - sub openit { - my $path = shift; - local *FH; - return open (FH, $path) ? *FH : undef; - } - $fh = openit('< /etc/motd'); - print <$fh>; +Before Perl 5.6, you had to use the C<*FH> or C<\*FH> notations. +These are "typeglobs"--see L +and especially L for more information. =item Passing Regexes @@ -560,28 +485,38 @@ In summary, local() doesn't make what you think of as private, local variables. It gives a global variable a temporary value. my() is what you're looking for if you want private variables. -See L and +See L and L for excruciating details. =head2 How can I access a dynamic variable while a similarly named lexical is in scope? -You can do this via symbolic references, provided you haven't set -C. So instead of $var, use C<${'var'}>. +If you know your package, you can just mention it explicitly, as in +$Some_Pack::var. Note that the notation $::var is B the dynamic $var +in the current package, but rather the one in the "main" package, as +though you had written $main::var. - local $var = "global"; - my $var = "lexical"; + use vars '$var'; + local $var = "global"; + my $var = "lexical"; - print "lexical is $var\n"; + print "lexical is $var\n"; + print "global is $main::var\n"; - no strict 'refs'; - print "global is ${'var'}\n"; +Alternatively you can use the compiler directive our() to bring a +dynamic variable into the current lexical scope. -If you know your package, you can just mention it explicitly, as in -$Some_Pack::var. Note that the notation $::var is I the dynamic -$var in the current package, but rather the one in the C
-package, as though you had written $main::var. Specifying the package -directly makes you hard-code its name, but it executes faster and -avoids running afoul of C. + require 5.006; # our() did not exist before 5.6 + use vars '$var'; + + local $var = "global"; + my $var = "lexical"; + + print "lexical is $var\n"; + + { + our $var; + print "global is $var\n"; + } =head2 What's the difference between deep and shallow binding? @@ -594,7 +529,7 @@ However, dynamic variables (aka global, local, or package variables) are effectively shallowly bound. Consider this just one more reason not to use them. See the answer to L<"What's a closure?">. -=head2 Why doesn't "my($foo) = ;" work right? +=head2 Why doesn't "my($foo) = EFILEE;" work right? C and C give list context to the right hand side of C<=>. The read operation, like so many of Perl's @@ -678,11 +613,11 @@ construct like this: elsif (/pat2/) { } # do something else elsif (/pat3/) { } # do something else else { } # default - } + } Here's a simple example of a switch based on pattern matching, this time lined up in a way to make it look more like a switch statement. -We'll do a multi-way conditional based on the type of reference stored +We'll do a multiway conditional based on the type of reference stored in $whatchamacallit: SWITCH: for (ref $whatchamacallit) { @@ -715,7 +650,7 @@ in $whatchamacallit: } -See C for many other +See C for many other examples in this style. Sometimes you should change the positions of the constant and the variable. @@ -733,7 +668,7 @@ C<"STOP"> here: elsif ("LIST" =~ /^\Q$answer/i) { print "Action is list\n" } elsif ("EDIT" =~ /^\Q$answer/i) { print "Action is edit\n" } -A totally different approach is to create a hash of function references. +A totally different approach is to create a hash of function references. my %commands = ( "happy" => \&joy, @@ -748,33 +683,18 @@ A totally different approach is to create a hash of function references. $commands{$string}->(); } else { print "No such command: $string\n"; - } + } -=head2 How can I catch accesses to undefined variables/functions/methods? +=head2 How can I catch accesses to undefined variables, functions, or methods? The AUTOLOAD method, discussed in L and L, lets you capture calls to undefined functions and methods. When it comes to undefined variables that would trigger a warning -under C<-w>, you can use a handler to trap the pseudo-signal -C<__WARN__> like this: - - $SIG{__WARN__} = sub { - - for ( $_[0] ) { # voici un switch statement - - /Use of uninitialized value/ && do { - # promote warning to a fatal - die $_; - }; - - # other warning cases to catch could go here; - - warn $_; - } +under C, you can promote the warning to an error. - }; + use warnings FATAL => qw(uninitialized); =head2 Why can't a method included in this same file be found? @@ -815,29 +735,29 @@ not necessarily the same as the one in which you were compiled): =head2 How can I comment out a large block of perl code? -Use embedded POD to discard it: +You can use embedded POD to discard it. Enclose the blocks you want +to comment out in POD markers, for example C<=for nobody> and C<=cut> +(which marks ends of POD blocks). # program is here =for nobody - This paragraph is commented out - - # program continues - - =begin comment text all of this stuff here will be ignored by everyone - =end comment text - =cut -This can't go just anywhere. You have to put a pod directive where -the parser is expecting a new statement, not just in the middle -of an expression or some other arbitrary yacc grammar production. + # program continues + +The pod directives cannot go just anywhere. You must put a +pod directive where the parser is expecting a new statement, +not just in the middle of an expression or some other +arbitrary grammar production. + +See L for more details. =head2 How do I clear a package? @@ -846,7 +766,7 @@ Use this code, provided by Mark-Jason Dominus: sub scrub_package { no strict 'refs'; my $pack = shift; - die "Shouldn't delete main package" + die "Shouldn't delete main package" if $pack eq "" || $pack eq "main"; my $stash = *{$pack . '::'}{HASH}; my $name; @@ -861,7 +781,7 @@ Use this code, provided by Mark-Jason Dominus: } } -Or, if you're using a recent release of Perl, you can +Or, if you're using a recent release of Perl, you can just use the Symbol::delete_package() function instead. =head2 How can I use a variable as a variable name? @@ -893,7 +813,7 @@ symbolic references, you are just using the package's symbol-table hash (like C<%main::>) instead of a user-defined hash. The solution is to use your own hash or a real reference instead. - $fred = 23; + $USER_VARS{"fred"} = 23; $varname = "fred"; $USER_VARS{$varname}++; # not $$varname++ @@ -929,7 +849,7 @@ wanted to use another scalar variable to refer to those by name. $name = "fred"; $$name{WIFE} = "wilma"; # set %fred - $name = "barney"; + $name = "barney"; $$name{WIFE} = "betty"; # set %barney This is still a symbolic reference, and is still saddled with the @@ -953,7 +873,7 @@ can play around with the symbol table. For example: for my $name (@colors) { no strict 'refs'; # renege for the block *$name = sub { "@_" }; - } + } All those functions (red(), blue(), green(), etc.) appear to be separate, but the real code in the closure actually was compiled only once. @@ -964,17 +884,38 @@ subroutines, because they are always global--you can't use my() on them. For scalars, arrays, and hashes, though--and usually for subroutines-- you probably only want to use hard references. +=head2 What does "bad interpreter" mean? + +The "bad interpreter" message comes from the shell, not perl. The +actual message may vary depending on your platform, shell, and locale +settings. + +If you see "bad interpreter - no such file or directory", the first +line in your perl script (the "shebang" line) does not contain the +right path to perl (or any other program capable of running scripts). +Sometimes this happens when you move the script from one machine to +another and each machine has a different path to perl---/usr/bin/perl +versus /usr/local/bin/perl for instance. + +If you see "bad interpreter: Permission denied", you need to make your +script executable. + +In either case, you should still be able to run the scripts with perl +explicitly: + + % perl script.pl + +If you get a message like "perl: command not found", perl is not in +your PATH, which might also mean that the location of perl is not +where you expect it so you need to adjust your shebang line. + =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington. All rights reserved. -When included as part of the Standard Version of Perl, or as part of -its complete documentation whether printed or otherwise, this work -may be distributed only under the terms of Perl's Artistic License. -Any distribution of this file or derivatives thereof I -of that package require that special arrangements be made with -copyright holder. +This documentation is free; you can redistribute it and/or modify it +under the same terms as Perl itself. Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and