X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfaq7.pod;h=008f433124daeaee4d2da991a2a07c8cafd7ef05;hb=1a6071381913ad8fca476a56b6dbb62e5c99c1bd;hp=50dc83fb53bb8b4757a36f2d3a9cd6ce6045fc09;hpb=e337fe5d35fe209b9b7282bd06a3e200f19d1403;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod index 50dc83f..008f433 100644 --- a/pod/perlfaq7.pod +++ b/pod/perlfaq7.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq7 - Perl Language Issues ($Revision: 1.1 $, $Date: 2001/09/20 03:03:00 $) +perlfaq7 - General Perl Language Issues ($Revision: 1.8 $, $Date: 2002/03/26 15:48:32 $) =head1 DESCRIPTION @@ -167,81 +167,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.1 $=~/\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 +183,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? @@ -682,7 +608,7 @@ construct like this: 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) { @@ -815,7 +741,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 +751,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 +763,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? @@ -966,7 +897,7 @@ 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. This documentation is free; you can redistribute it and/or modify it