diff options
Diffstat (limited to 'pod')
| -rw-r--r-- | pod/perlfaq.pod | 10 | ||||
| -rw-r--r-- | pod/perlfaq1.pod | 133 | ||||
| -rw-r--r-- | pod/perlfaq2.pod | 34 | ||||
| -rw-r--r-- | pod/perlfaq3.pod | 116 | ||||
| -rw-r--r-- | pod/perlfaq4.pod | 89 | ||||
| -rw-r--r-- | pod/perlfaq5.pod | 32 | ||||
| -rw-r--r-- | pod/perlfaq6.pod | 148 | ||||
| -rw-r--r-- | pod/perlfaq7.pod | 44 | ||||
| -rw-r--r-- | pod/perlfaq8.pod | 6 | ||||
| -rw-r--r-- | pod/perlfaq9.pod | 75 |
10 files changed, 432 insertions, 255 deletions
diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod index e97a59a6db..a77d8e403f 100644 --- a/pod/perlfaq.pod +++ b/pod/perlfaq.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq - frequently asked questions about Perl ($Date: 2004/10/05 22:15:44 $) +perlfaq - frequently asked questions about Perl ($Date: 2005/01/31 15:52:15 $) =head1 DESCRIPTION @@ -119,7 +119,7 @@ Which version of Perl should I use? =item * -What are perl4 and perl5? +What are perl4, perl5, or perl6? =item * @@ -377,7 +377,7 @@ Where can I learn about linking C with Perl? [h2xs, xsubpp] =item * -I've read perlembed, perlguts, etc., but I can't embed perl in +I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong? =item * @@ -727,6 +727,10 @@ How can I use Perl's C<-i> option from within a program? =item * +How can I copy a file? + +=item * + How do I make a temporary file name? =item * diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod index 293aa7f826..abde261934 100644 --- a/pod/perlfaq1.pod +++ b/pod/perlfaq1.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq1 - General Questions About Perl ($Revision: 1.15 $, $Date: 2004/10/11 05:06:29 $) +perlfaq1 - General Questions About Perl ($Revision: 1.17 $, $Date: 2005/01/31 15:52:15 $) =head1 DESCRIPTION @@ -56,39 +56,100 @@ users the informal support will more than suffice. See the answer to =head2 Which version of Perl should I use? -You should definitely use version 5. Version 4 is old, limited, and -no longer maintained; its last patch (4.036) was in 1992, long ago and -far away. Sure, it's stable, but so is anything that's dead; in fact, -perl4 had been called a dead, flea-bitten camel carcass. The most -recent production release is 5.8.2 (although 5.005_03 and 5.6.2 are -still supported). The most cutting-edge development release is 5.9. -Further references to the Perl language in this document refer to the -production release unless otherwise specified. There may be one or -more official bug fixes by the time you read this, and also perhaps -some experimental versions on the way to the next release. -All releases prior to 5.004 were subject to buffer overruns, a grave -security issue. - -=head2 What are perl4 and perl5? - -Perl4 and perl5 are informal names for different versions of the Perl -programming language. It's easier to say "perl5" than it is to say -"the 5(.004) release of Perl", but some people have interpreted this -to mean there's a language called "perl5", which isn't the case. -Perl5 is merely the popular name for the fifth major release (October 1994), -while perl4 was the fourth major release (March 1991). There was also a -perl1 (in January 1988), a perl2 (June 1988), and a perl3 (October 1989). - -The 5.0 release is, essentially, a ground-up rewrite of the original -perl source code from releases 1 through 4. It has been modularized, -object-oriented, tweaked, trimmed, and optimized until it almost doesn't -look like the old code. However, the interface is mostly the same, and -compatibility with previous releases is very high. -See L<perltrap/"Perl4 to Perl5 Traps">. - -To avoid the "what language is perl5?" confusion, some people prefer to -simply use "perl" to refer to the latest version of perl and avoid using -"perl5" altogether. It's not really that big a deal, though. +(contributed by brian d foy) + +There is often a matter of opinion and taste, and there isn't any +one answer that fits anyone. In general, you want to use either +the current stable release, or the stable release immediately prior +to that one. Currently, those are perl5.8.x and perl5.6.x, respectively. + +Beyond that, you have to consider several things and decide which +is best for you. + +=over 4 + +=item + +If things aren't broken, upgrading perl may break +them (or at least issue new warnings). + +=item + +The latest versions of perl have more bug fixes. + +=item + +The Perl community is geared toward supporting the most +recent releases, so you'll have an easier time finding help for +those. + +=item + +Versions prior to perl5.004 had serious security problems with +buffer overflows, and in some cases have CERT advisories (for +instance, http://www.cert.org/advisories/CA-1997-17.html ). + +=item + +The latest versions are probably the least deployed and +widely tested, so you may want to wait a few months after their +release and see what problems others have if you are risk averse. + +=item + +The immediate, previous releases (i.e. perl5.6.x ) are usually +maintained for a while, although not at the same level as the +current releases. + +=item + +No one is actively supporting perl4.x. Five years ago it was +a dead camel carcass (according to this document). Now it's barely +a skeleton as its whitewashed bones have fractured or eroded. + +=item + +There is no perl6.x for the next couple of years. Stay tuned, +but don't worry that you'll have to change major versions of Perl +soon (i.e. before 2006). + +=item + +There are really two tracks of perl development: a +maintenance version and an experimental version. The +maintenance versions are stable, and have an even number +as the minor release (i.e. perl5.8.x, where 8 is the minor +release). The experimental versions may include features that +don't make it into the stable versions, and have an odd number +as the minor release (i.e. perl5.9.x, where 9 is the minor release). + +=back + + +=head2 What are perl4, perl5, or perl6? + +(contributed by brian d foy) + +In short, perl4 is the past, perl5 is the present, and perl6 is the +future. + +The number after perl (i.e. the 5 after perl5) is the major release +of the perl interpreter as well as the version of the language. Each +major version has significant differences that earlier versions cannot +support. + +The current major release of Perl is perl5, and was released in 1994. +It can run scripts from the previous major release, perl4 (March 1991), +but has significant differences. It introduced the concept of references, +complex data structures, and modules. The perl5 interpreter was a +complete re-write of the previous perl sources. + +Perl6 is the next major version of Perl, but it's still in development +in both its syntax and design. The work started in 2002 and is still +ongoing. Many of the most interesting features have shown up in the +latest versions of perl5, and some perl5 modules allow you to use some +perl6 syntax in your programs. You can learn more about perl6 at +http://dev.perl.org/perl6/ . See L<perlhist> for a history of Perl revisions. @@ -334,8 +395,8 @@ but the most recommendable way is to upgrade to at least Perl 5.6.1. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998, 1999, 2000, 2001 Tom Christiansen and Nathan -Torkington. All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod index 4d419549b0..a0fdf300ce 100644 --- a/pod/perlfaq2.pod +++ b/pod/perlfaq2.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.29 $, $Date: 2004/10/25 18:37:23 $) +perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.31 $, $Date: 2005/01/31 15:54:44 $) =head1 DESCRIPTION @@ -313,6 +313,11 @@ Recommended books on (or mostly on) Perl follow. =item Tutorials + Beginning Perl + by James Lee + ISBN 1-59059-391-X [2nd edition August 2004] + http://apress.com/book/bookDisplay.html?bID=344 + Elements of Programming with Perl by Andrew L. Johnson ISBN 1-884777-80-5 [1st edition October 1999] @@ -353,6 +358,11 @@ Recommended books on (or mostly on) Perl follow. =item Task-Oriented + Writing Perl Modules for CPAN + by Sam Tregar + ISBN 1-59059-018-X [1st edition Aug 2002] + http://apress.com/book/bookDisplay.html?bID=14 + The Perl Cookbook by Tom Christiansen and Nathan Torkington with foreword by Larry Wall @@ -364,30 +374,40 @@ Recommended books on (or mostly on) Perl follow. ISBN 0-201-41975-0 [1st edition 1998] http://www.awl.com/ + Real World SQL Server Administration with Perl + by Linchi Shea + ISBN 1-59059-097-X [1st edition July 2003] + http://apress.com/book/bookDisplay.html?bID=171 + =item Special Topics + Perl 6 Now: The Core Ideas Illustrated with Perl 5 + by Scott Walters + ISBN 1-59059-395-2 [1st edition December 2004 + http://apress.com/book/bookDisplay.html?bID=355 + Mastering Regular Expressions by Jeffrey E. F. Friedl ISBN 0-596-00289-0 [2nd edition July 2002] http://www.oreilly.com/catalog/regex2/ - Network Programming with Perl + Network Programming with Perl by Lincoln Stein ISBN 0-201-61571-1 [1st edition 2001] http://www.awlonline.com/ - Object Oriented Perl + Object Oriented Perl Damian Conway with foreword by Randal L. Schwartz ISBN 1-884777-79-1 [1st edition August 1999] http://www.manning.com/Conway/ - Data Munging with Perl + Data Munging with Perl Dave Cross ISBN 1-930110-00-6 [1st edition 2001] http://www.manning.com/cross - Mastering Perl/Tk + Mastering Perl/Tk by Steve Lidie and Nancy Walsh ISBN 1-56592-716-8 [1st edition January 2002] http://www.oreilly.com/catalog/mastperltk/ @@ -523,8 +543,8 @@ the I<What is CPAN?> question earlier in this document. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2001 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod index 33675bfff3..7dede4c75d 100644 --- a/pod/perlfaq3.pod +++ b/pod/perlfaq3.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq3 - Programming Tools ($Revision: 1.41 $, $Date: 2004/11/03 22:45:32 $) +perlfaq3 - Programming Tools ($Revision: 1.46 $, $Date: 2005/02/13 02:36:09 $) =head1 DESCRIPTION @@ -407,8 +407,8 @@ no 32k limit). =item Affrus -is a full Perl development enivornment with full debugger support ( -http://www.latenightsw.com ). +is a full Perl development enivornment with full debugger support +( http://www.latenightsw.com ). =item Alpha @@ -649,23 +649,25 @@ everything works out right. =head2 How can I free an array or hash so my program shrinks? -You usually can't. On most operating systems, memory -allocated to a program can never be returned to the system. -That's why long-running programs sometimes re-exec -themselves. Some operating systems (notably, systems that -use mmap(2) for allocating large chunks of memory) can -reclaim memory that is no longer used, but on such systems, -perl must be configured and compiled to use the OS's malloc, -not perl's. - -However, judicious use of my() on your variables will help make sure -that they go out of scope so that Perl can free up that space for -use in other parts of your program. A global variable, of course, never -goes out of scope, so you can't get its space automatically reclaimed, -although undef()ing and/or delete()ing it will achieve the same effect. +(contributed by Michael Carman) + +You usually can't. Memory allocated to lexicals (i.e. my() variables) +cannot be reclaimed or reused even if they go out of scope. It is +reserved in case the variables come back into scope. Memory allocated +to global variables can be reused (within your program) by using +undef()ing and/or delete(). + +On most operating systems, memory allocated to a program can never be +returned to the system. That's why long-running programs sometimes re- +exec themselves. Some operating systems (notably, systems that use +mmap(2) for allocating large chunks of memory) can reclaim memory that +is no longer used, but on such systems, perl must be configured and +compiled to use the OS's malloc, not perl's. + In general, memory allocation and de-allocation isn't something you can -or should be worrying about much in Perl, but even this capability -(preallocation of data types) is in the works. +or should be worrying about much in Perl. + +See also "How can I make my Perl program take less memory?" =head2 How can I make my CGI script more efficient? @@ -753,41 +755,40 @@ you want to be sure your license's wording will stand up in court. =head2 How can I compile my Perl program into byte code or C? -Malcolm Beattie has written a multifunction backend compiler, -available from CPAN, that can do both these things. It is included -in the perl5.005 release, but is still considered experimental. -This means it's fun to play with if you're a programmer but not -really for people looking for turn-key solutions. - -Merely compiling into C does not in and of itself guarantee that your -code will run very much faster. That's because except for lucky cases -where a lot of native type inferencing is possible, the normal Perl -run-time system is still present and so your program will take just as -long to run and be just as big. Most programs save little more than -compilation time, leaving execution no more than 10-30% faster. A few -rare programs actually benefit significantly (even running several times -faster), but this takes some tweaking of your code. - -You'll probably be astonished to learn that the current version of the -compiler generates a compiled form of your script whose executable is -just as big as the original perl executable, and then some. That's -because as currently written, all programs are prepared for a full -eval() statement. You can tremendously reduce this cost by building a -shared I<libperl.so> library and linking against that. See the -F<INSTALL> podfile in the Perl source distribution for details. If -you link your main perl binary with this, it will make it minuscule. -For example, on one author's system, F</usr/bin/perl> is only 11k in -size! - -In general, the compiler will do nothing to make a Perl program smaller, -faster, more portable, or more secure. In fact, it can make your -situation worse. The executable will be bigger, your VM system may take -longer to load the whole thing, the binary is fragile and hard to fix, -and compilation never stopped software piracy in the form of crackers, -viruses, or bootleggers. The real advantage of the compiler is merely -packaging, and once you see the size of what it makes (well, unless -you use a shared I<libperl.so>), you'll probably want a complete -Perl install anyway. +(contributed by brian d foy) + +In general, you can't do this. There are some things that may work +for your situation though. People usually ask this question +because they want to distribute their works without giving away +the source code, and most solutions trade disk space for convenience. +You probably won't see much of a speed increase either, since most +solutions simply bundle a Perl interpreter in the final product +(but see L<How can I make my Perl program run faster?>). + +The Perl Archive Toolkit (http://par.perl.org/index.cgi) is +Perl's analog to Java's JAR. It's freely available and on +CPAN (http://search.cpan.org/dist/PAR/). + +The B::* namespace, often called "the Perl compiler", but is really a +way for Perl programs to peek at its innards rather than create +pre-compiled versions of your program. However. the B::Bytecode +module can turn your script into a bytecode format that could be +loaded later by the ByteLoader module and executed as a regular Perl +script. + +There are also some commercial products that may work for +you, although you have to buy a license for them. + +The Perl Dev Kit +(http://www.activestate.com/Products/Perl_Dev_Kit/) from +ActiveState can "Turn your Perl programs into ready-to-run +executables for HP-UX, Linux, Solaris and Windows." + +Perl2Exe (http://www.indigostar.com/perl2exe.htm) is a +command line program for converting perl scripts to +executable files. It targets both Windows and unix +platforms. + =head2 How can I compile Perl into Java? @@ -931,8 +932,7 @@ L<perlguts>. Don't forget that you can learn a lot from looking at how the authors of existing extension modules wrote their code and solved their problems. -=head2 I've read perlembed, perlguts, etc., but I can't embed perl in -my C program; what am I doing wrong? +=head2 I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong? Download the ExtUtils::Embed kit from CPAN and run `make test'. If the tests pass, read the pods again and again and again. If they @@ -964,8 +964,8 @@ information, see L<ExtUtils::MakeMaker>. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod index 815a9ea428..05005cb4ac 100644 --- a/pod/perlfaq4.pod +++ b/pod/perlfaq4.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq4 - Data Manipulation ($Revision: 1.56 $, $Date: 2004/11/03 22:47:56 $) +perlfaq4 - Data Manipulation ($Revision: 1.60 $, $Date: 2005/02/14 18:24:01 $) =head1 DESCRIPTION @@ -454,26 +454,29 @@ and Date::Manip modules from CPAN. =head2 How can I find the Julian Day? -Use the Time::JulianDay module (part of the Time-modules bundle -available from CPAN.) - -Before you immerse yourself too deeply in this, be sure to verify that -it is the I<Julian> Day you really want. Are you interested in a way -of getting serial days so that you just can tell how many days they -are apart or so that you can do also other date arithmetic? If you -are interested in performing date arithmetic, this can be done using -modules Date::Manip or Date::Calc. - -There is too many details and much confusion on this issue to cover in -this FAQ, but the term is applied (correctly) to a calendar now -supplanted by the Gregorian Calendar, with the Julian Calendar failing -to adjust properly for leap years on centennial years (among other -annoyances). The term is also used (incorrectly) to mean: [1] days in -the Gregorian Calendar; and [2] days since a particular starting time -or `epoch', usually 1970 in the Unix world and 1980 in the -MS-DOS/Windows world. If you find that it is not the first meaning -that you really want, then check out the Date::Manip and Date::Calc -modules. (Thanks to David Cassell for most of this text.) +(contributed by brian d foy and Dave Cross) + +You can use the Time::JulianDay module available on CPAN. Ensure that +you really want to find a Julian day, though, as many people have +different ideas about Julian days. See +http://www.hermetic.ch/cal_stud/jdn.htm for instance. + +You can also try the DateTime module, which can convert a date/time +to a Julian Day. + + $ perl -MDateTime -le'print DateTime->today->jd' + 2453401.5 + +Or the modified Julian Day + + $ perl -MDateTime -le'print DateTime->today->mjd' + 53401 + +Or even the day of the year (which is what some people think of as a +Julian day) + + $ perl -MDateTime -le'print DateTime->today->doy' + 31 =head2 How do I find yesterday's date? @@ -598,9 +601,6 @@ a subroutine call (in list context) into a string: print "My sub returned @{[mysub(1,2,3)]} that time.\n"; -See also ``How can I expand variables in text strings?'' in this -section of the FAQ. - =head2 How do I find matching/nesting anything? This isn't something that can be done in one regular expression, no @@ -804,7 +804,7 @@ case transformations: =head2 How can I split a [character] delimited string except when inside [character]? Several modules can handle this sort of pasing---Text::Balanced, -Text::CVS, Text::CVS_XS, and Text::ParseWords, among others. +Text::CSV, Text::CSV_XS, and Text::ParseWords, among others. Take the example case of trying to split a string that is comma-separated into its different fields. You can't use C<split(/,/)> @@ -938,31 +938,27 @@ you can use this kind of thing: =head2 How do I find the soundex value of a string? -Use the standard Text::Soundex module distributed with Perl. -Before you do so, you may want to determine whether `soundex' is in -fact what you think it is. Knuth's soundex algorithm compresses words -into a small space, and so it does not necessarily distinguish between -two words which you might want to appear separately. For example, the -last names `Knuth' and `Kant' are both mapped to the soundex code K530. -If Text::Soundex does not do what you are looking for, you might want -to consider the String::Approx module available at CPAN. +(contributed by brian d foy) + +You can use the Text::Soundex module. If you want to do fuzzy or close +matching, you might also try the String::Approx, and Text::Metaphone, +and Text::DoubleMetaphone modules. =head2 How can I expand variables in text strings? -Let's assume that you have a string like: +Let's assume that you have a string that contains placeholder +variables. $text = 'this has a $foo in it and a $bar'; -If those were both global variables, then this would -suffice: +You can use a substitution with a double evaluation. The +first /e turns C<$1> into C<$foo>, and the second /e turns +C<$foo> into its value. You may want to wrap this in an +C<eval>: if you try to get the value of an undeclared variable +while running under C<use strict>, you get a fatal error. - $text =~ s/\$(\w+)/${$1}/g; # no /e needed - -But since they are probably lexicals, or at least, they could -be, you'd have to do this: - - $text =~ s/(\$\w+)/$1/eeg; - die if $@; # needed /ee, not /e + eval { $text =~ s/(\$\w+)/$1/eeg }; + die if $@; It's probably better in the general case to treat those variables as entries in some special hash. For example: @@ -973,9 +969,6 @@ variables as entries in some special hash. For example: ); $text =~ s/\$(\w+)/$user_defs{$1}/g; -See also ``How do I expand function calls in a string?'' in this section -of the FAQ. - =head2 What's wrong with always quoting "$vars"? The problem is that those double-quotes force stringification-- @@ -2088,8 +2081,8 @@ the PDL module from CPAN instead--it makes number-crunching easy. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod index ae71cd9540..ab0ba26be4 100644 --- a/pod/perlfaq5.pod +++ b/pod/perlfaq5.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq5 - Files and Formats ($Revision: 1.31 $, $Date: 2004/02/07 04:29:50 $) +perlfaq5 - Files and Formats ($Revision: 1.35 $, $Date: 2005/01/21 12:26:11 $) =head1 DESCRIPTION @@ -106,9 +106,31 @@ This block modifies all the C<.c> files in the current directory, leaving a backup of the original data from each file in a new C<.c.orig> file. +=head2 How can I copy a file? + +(contributed by brian d foy) + +Use the File::Copy module. It comes with Perl and can do a +true copy across file systems, and it does its magic in +a portable fashion. + + use File::Copy; + + copy( $original, $new_copy ) or die "Copy failed: $!"; + +If you can't use File::Copy, you'll have to do the work yourself: +open the original file, open the destination file, then print +to the destination file as you read the original. + =head2 How do I make a temporary file name? -Use the File::Temp module, see L<File::Temp> for more information. +If you don't need to know the name of the file, you can use C<open()> +with C<undef> in place of the file name. The C<open()> function +creates an anonymous temporary file. + + open my $tmp, '+>', undef or die $!; + +Otherwise, you can use the File::Temp module. use File::Temp qw/ tempfile tempdir /; @@ -333,7 +355,7 @@ It is easier to see with comments: s/( ^[-+]? # beginning of number. - \d{1,3}? # first digits before first comma + \d+? # first digits before first comma (?= # followed by, (but not included in the match) : (?>(?:\d{3})+) # some positive multiple of three digits. (?!\d) # an *exact* multiple, not x * 3 + 1 or whatever. @@ -1047,8 +1069,8 @@ If your array contains lines, just print them: =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/perlfaq6.pod b/pod/perlfaq6.pod index 6b0f3bb9a4..29e6903929 100644 --- a/pod/perlfaq6.pod +++ b/pod/perlfaq6.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq6 - Regular Expressions ($Revision: 1.27 $, $Date: 2004/11/03 22:52:16 $) +perlfaq6 - Regular Expressions ($Revision: 1.30 $, $Date: 2005/02/14 18:25:48 $) =head1 DESCRIPTION @@ -518,59 +518,115 @@ See the module String::Approx available from CPAN. =head2 How do I efficiently match many regular expressions at once? -The following is extremely inefficient: +( contributed by brian d foy ) + +Avoid asking Perl to compile a regular expression every time +you want to match it. In this example, perl must recompile +the regular expression for every iteration of the foreach() +loop since it has no way to know what $pattern will be. + + @patterns = qw( foo bar baz ); + + LINE: while( <> ) + { + foreach $pattern ( @patterns ) + { + print if /\b$pattern\b/i; + next LINE; + } + } - # slow but obvious way - @popstates = qw(CO ON MI WI MN); - while (defined($line = <>)) { - for $state (@popstates) { - if ($line =~ /\b$state\b/i) { - print $line; - last; - } - } - } +The qr// operator showed up in perl 5.005. It compiles a +regular expression, but doesn't apply it. When you use the +pre-compiled version of the regex, perl does less work. In +this example, I inserted a map() to turn each pattern into +its pre-compiled form. The rest of the script is the same, +but faster. + + @patterns = map { qr/\b$_\b/i } qw( foo bar baz ); + + LINE: while( <> ) + { + foreach $pattern ( @patterns ) + { + print if /\b$pattern\b/i; + next LINE; + } + } + +In some cases, you may be able to make several patterns into +a single regular expression. Beware of situations that require +backtracking though. -That's because Perl has to recompile all those patterns for each of -the lines of the file. As of the 5.005 release, there's a much better -approach, one which makes use of the new C<qr//> operator: - - # use spiffy new qr// operator, with /i flag even - use 5.005; - @popstates = qw(CO ON MI WI MN); - @poppats = map { qr/\b$_\b/i } @popstates; - while (defined($line = <>)) { - for $patobj (@poppats) { - print $line if $line =~ /$patobj/; - } - } + $regex = join '|', qw( foo bar baz ); + + LINE: while( <> ) + { + print if /\b(?:$regex)\b/i; + } + +For more details on regular expression efficiency, see Mastering +Regular Expressions by Jeffrey Freidl. He explains how regular +expressions engine work and why some patterns are surprisingly +inefficient. Once you understand how perl applies regular +expressions, you can tune them for individual situations. =head2 Why don't word-boundary searches with C<\b> work for me? -Two common misconceptions are that C<\b> is a synonym for C<\s+> and -that it's the edge between whitespace characters and non-whitespace -characters. Neither is correct. C<\b> is the place between a C<\w> -character and a C<\W> character (that is, C<\b> is the edge of a -"word"). It's a zero-width assertion, just like C<^>, C<$>, and all -the other anchors, so it doesn't consume any characters. L<perlre> -describes the behavior of all the regex metacharacters. +(contributed by brian d foy) + +Ensure that you know what \b really does: it's the boundary between a +word character, \w, and something that isn't a word character. That +thing that isn't a word character might be \W, but it can also be the +start or end of the string. + +It's not (not!) the boundary between whitespace and non-whitespace, +and it's not the stuff between words we use to create sentences. + +In regex speak, a word boundary (\b) is a "zero width assertion", +meaning that it doesn't represent a character in the string, but a +condition at a certain position. + +For the regular expression, /\bPerl\b/, there has to be a word +boundary before the "P" and after the "l". As long as something other +than a word character precedes the "P" and succeeds the "l", the +pattern will match. These strings match /\bPerl\b/. + + "Perl" # no word char before P or after l + "Perl " # same as previous (space is not a word char) + "'Perl'" # the ' char is not a word char + "Perl's" # no word char before P, non-word char after "l" + +These strings do not match /\bPerl\b/. + + "Perl_" # _ is a word char! + "Perler" # no word char before P, but one after l + +You don't have to use \b to match words though. You can look for +non-word characters surrrounded by word characters. These strings +match the pattern /\b'\b/. + + "don't" # the ' char is surrounded by "n" and "t" + "qep'a'" # the ' char is surrounded by "p" and "a" + +These strings do not match /\b'\b/. -Here are examples of the incorrect application of C<\b>, with fixes: + "foo'" # there is no word char after non-word ' + +You can also use the complement of \b, \B, to specify that there +should not be a word boundary. - "two words" =~ /(\w+)\b(\w+)/; # WRONG - "two words" =~ /(\w+)\s+(\w+)/; # right +In the pattern /\Bam\B/, there must be a word character before the "a" +and after the "m". These patterns match /\Bam\B/: - " =matchless= text" =~ /\b=(\w+)=\b/; # WRONG - " =matchless= text" =~ /=(\w+)=/; # right + "llama" # "am" surrounded by word chars + "Samuel" # same + +These strings do not match /\Bam\B/ -Although they may not do what you thought they did, C<\b> and C<\B> -can still be quite useful. For an example of the correct use of -C<\b>, see the example of matching duplicate words over multiple -lines. + "Sam" # no word boundary before "a", but one after "m" + "I am Sam" # "am" surrounded by non-word chars -An example of using C<\B> is the pattern C<\Bis\B>. This will find -occurrences of "is" on the insides of words only, as in "thistle", but -not "this" or "island". =head2 Why does using $&, $`, or $' slow my program down? @@ -800,8 +856,8 @@ in L<perlre>. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod index 54e91bda9b..19fa7807b6 100644 --- a/pod/perlfaq7.pod +++ b/pod/perlfaq7.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq7 - General Perl Language Issues ($Revision: 1.18 $, $Date: 2004/11/03 22:54:08 $) +perlfaq7 - General Perl Language Issues ($Revision: 1.21 $, $Date: 2005/01/21 12:10:22 $) =head1 DESCRIPTION @@ -176,20 +176,26 @@ If you're looking for something a bit more rigorous, try L<perltoot>. =head2 How do I create a module? -A module is a package that lives in a file of the same name. For -example, the Hello::There module would live in Hello/There.pm. For -details, read L<perlmod>. You'll also find L<Exporter> helpful. If -you're writing a C or mixed-language module with both C and Perl, then -you should study L<perlxstut>. +(contributed by brian d foy) -The C<h2xs> program will create stubs for all the important stuff for you: +L<perlmod>, L<perlmodlib>, L<perlmodstyle> explain modules +in all the gory details. L<perlnewmod> gives a a brief +overview of the process along with a couple of suggestions +about style. - % h2xs -XA -n My::Module +If you need to include C code or C library interfaces in +your module, you'll need h2xs. h2xs will create the module +distribution structure and the initial interface files +you'll need. L<perlxs> and L<perlxstut> explain the details. -The C<-X> switch tells C<h2xs> that you are not using C<XS> extension -code. The C<-A> switch tells C<h2xs> that you are not using the -AutoLoader, and the C<-n> switch specifies the name of the module. -See L<h2xs> for more details. +If you don't need to use C code, other tools such as +ExtUtils::ModuleMaker and Module::Starter, can help you +create a skeleton module distribution. + +You may also want to see Sam Tregar's "Writing Perl Modules +for CPAN" ( http://apress.com/book/bookDisplay.html?bID=14 ) +which is the best hands-on guide to creating module +distributions. =head2 How do I create a class? @@ -736,18 +742,22 @@ not necessarily the same as the one in which you were compiled): =head2 How can I comment out a large block of perl code? 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). +to comment out in POD markers. The <=begin> directive marks a section +for a specific formatter. Use the C<comment> format, which no formatter +should claim to understand (by policy). Mark the end of the block +with <=end>. # program is here - =for nobody + =begin comment all of this stuff here will be ignored by everyone + =end comment + =cut # program continues @@ -911,8 +921,8 @@ where you expect it so you need to adjust your shebang line. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/perlfaq8.pod b/pod/perlfaq8.pod index ad07fa3656..8152d49c7e 100644 --- a/pod/perlfaq8.pod +++ b/pod/perlfaq8.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq8 - System Interaction ($Revision: 1.22 $, $Date: 2004/10/05 22:13:49 $) +perlfaq8 - System Interaction ($Revision: 1.23 $, $Date: 2005/01/03 18:43:37 $) =head1 DESCRIPTION @@ -1252,8 +1252,8 @@ but other times it is not. Modern programs C<use Socket;> instead. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2003 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod index fa59003d10..0dd6f1ea3b 100644 --- a/pod/perlfaq9.pod +++ b/pod/perlfaq9.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq9 - Networking ($Revision: 1.16 $, $Date: 2004/10/30 12:20:59 $) +perlfaq9 - Networking ($Revision: 1.19 $, $Date: 2005/01/21 12:14:12 $) =head1 DESCRIPTION @@ -227,6 +227,10 @@ through proxies: =head2 How do I automate an HTML form submission? +If you are doing something complex, such as moving through many pages +and forms or a web site, you can use C<WWW::Mechanize>. See its +documentation for all the details. + If you're submitting values using the GET method, create a URL and encode the form using the C<query_form> method: @@ -348,35 +352,42 @@ the Mail::Header module from CPAN (part of the MailTools package). =head2 How do I decode a CGI form? -You use a standard module, probably CGI.pm. Under no circumstances -should you attempt to do so by hand! - -You'll see a lot of CGI programs that blindly read from STDIN the number -of bytes equal to CONTENT_LENGTH for POSTs, or grab QUERY_STRING for -decoding GETs. These programs are very poorly written. They only work -sometimes. They typically forget to check the return value of the read() -system call, which is a cardinal sin. They don't handle HEAD requests. -They don't handle multipart forms used for file uploads. They don't deal -with GET/POST combinations where query fields are in more than one place. -They don't deal with keywords in the query string. - -In short, they're bad hacks. Resist them at all costs. Please do not be -tempted to reinvent the wheel. Instead, use the CGI.pm or CGI_Lite.pm -(available from CPAN), or if you're trapped in the module-free land -of perl1 .. perl4, you might look into cgi-lib.pl (available from -http://cgi-lib.stanford.edu/cgi-lib/ ). - -Make sure you know whether to use a GET or a POST in your form. -GETs should only be used for something that doesn't update the server. -Otherwise you can get mangled databases and repeated feedback mail -messages. The fancy word for this is ``idempotency''. This simply -means that there should be no difference between making a GET request -for a particular URL once or multiple times. This is because the -HTTP protocol definition says that a GET request may be cached by the -browser, or server, or an intervening proxy. POST requests cannot be -cached, because each request is independent and matters. Typically, -POST requests change or depend on state on the server (query or update -a database, send mail, or purchase a computer). +(contributed by brian d foy) + +Use the CGI.pm module that comes with Perl. It's quick, +it's easy, and it actually does quite a bit of work to +ensure things happen correctly. It handles GET, POST, and +HEAD requests, multipart forms, multivalued fields, query +string and message body combinations, and many other things +you probably don't want to think about. + +It doesn't get much easier: the CGI module automatically +parses the input and makes each value available through the +C<param()> function. + + use CGI qw(:standard); + + my $total = param( "price" ) + param( "shipping" ); + + my @items = param( "item ); # multiple values, same field name + +If you want an object-oriented approach, CGI.pm can do that too. + + use CGI; + + my $cgi = CGI->new(); + + my $total = $cgi->param( "price" ) + $cgi->param( "shipping" ); + + my @items = $cgi->param( "item" ); + +You might also try CGI::Minimal which is a lightweight version +of the same thing. Other CGI::* modules on CPAN might work better +for you, too. + +Many people try to write their own decoder (or copy one from +another program) and then run into one of the many "gotchas" +of the task. It's much easier and less hassle to use CGI.pm. =head2 How do I check a valid mail address? @@ -632,8 +643,8 @@ an RPC stub generator and includes an RPC::ONC module. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself. |