X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfaq7.pod;h=a144457de98423191582deeadcbe0cf8934aad18;hb=bea985324a3cd895f8e0a0c38e90ab3d09433415;hp=53d4b6baf888e6fdcf7c449cc088724a890ba7c1;hpb=83df6a1d65c0fba9c27c7fb715fa674b03462cf0;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod index 53d4b6b..a144457 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.13 $, $Date: 2003/01/26 17:45:46 $) =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 @@ -167,81 +172,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 +188,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? @@ -372,37 +303,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: +As of Perl 5.6, you can represent filehandles with scalar variables +which you treat as any other scalar. -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: + open my $fh, $filename or die "Cannot open $filename! $!"; + func( $fh ); - splutter(\*STDOUT); - sub splutter { - my $fh = shift; - print $fh "her um well a hmmm\n"; - } - - $rec = get_rec(\*STDIN); - sub get_rec { - my $fh = shift; - return scalar <$fh>; - } + sub func { + my $passed_fh = shift; -If you're planning on generating new filehandles, you could do this: + my $line = <$fh>; + } - sub openit { - my $path = shift; - local *FH; - return open (FH, $path) ? *FH : undef; - } - $fh = openit('< /etc/motd'); - print <$fh>; +Before Perl 5.6, you had to use the C<*FH> or C<\*FH> notations. +These are "typeglobs"--see L +and especially L for more information. =item Passing Regexes @@ -560,28 +475,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 +519,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 +603,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 +640,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 +658,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 +673,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 +under C, you can promote the warning to an error. - /Use of uninitialized value/ && do { - # promote warning to a fatal - die $_; - }; - - # other warning cases to catch could go here; - - warn $_; - } - - }; + use warnings FATAL => qw(uninitialized); =head2 Why can't a method included in this same file be found? @@ -794,7 +704,7 @@ C<< Guru->find("Samy") >>) instead. Object notation is explained in L. Make sure to read about creating modules in L and -the perils of indirect objects in L. +the perils of indirect objects in L. =head2 How can I find out my current package? @@ -815,7 +725,8 @@ 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. The =for directive +lasts until the next paragraph (two consecutive newlines). # program is here @@ -824,6 +735,9 @@ Use embedded POD to discard it: # program continues +The =begin and =end directives can contain multiple +paragraphs. + =begin comment text all of this stuff @@ -833,11 +747,12 @@ Use embedded POD to discard it: =end comment text - =cut +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 s grammar production. -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. +See L for more details. =head2 How do I clear a package? @@ -846,7 +761,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 +776,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? @@ -929,7 +844,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 +868,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. @@ -966,15 +881,11 @@ you probably only want to use hard references. =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