Change 24024: FAQ sync
[email protected] (Rafael Garcia-Suarez) Fri, 11 Mar 2005 03:41:48 -0800
| Newsgroups | perl.perlfaq.workers,perl.perl5.changes |
|---|---|
| Message-ID | <[email protected]> |
Change 24024 by rgs@bloom on 2005/03/11 11:12:31
FAQ sync
Affected files ...
... //depot/perl/pod/perlfaq.pod#34 edit
... //depot/perl/pod/perlfaq1.pod#50 edit
... //depot/perl/pod/perlfaq2.pod#71 edit
... //depot/perl/pod/perlfaq3.pod#82 edit
... //depot/perl/pod/perlfaq4.pod#94 edit
... //depot/perl/pod/perlfaq5.pod#59 edit
... //depot/perl/pod/perlfaq6.pod#46 edit
... //depot/perl/pod/perlfaq7.pod#42 edit
... //depot/perl/pod/perlfaq8.pod#43 edit
... //depot/perl/pod/perlfaq9.pod#44 edit
Differences ...
==== //depot/perl/pod/perlfaq.pod#34 (text) ====
Index: perl/pod/perlfaq.pod
--- perl/pod/perlfaq.pod#33~23466~ Tue Nov 2 04:33:57 2004
+++ perl/pod/perlfaq.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=item *
-What are perl4 and perl5?
+What are perl4, perl5, or perl6?
=item *
@@ -377,7 +377,7 @@
=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 *
@@ -724,6 +724,10 @@
=item *
How can I use Perl's C<-i> option from within a program?
+
+=item *
+
+How can I copy a file?
=item *
==== //depot/perl/pod/perlfaq1.pod#50 (text) ====
Index: perl/pod/perlfaq1.pod
--- perl/pod/perlfaq1.pod#49~23466~ Tue Nov 2 04:33:57 2004
+++ perl/pod/perlfaq1.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=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 @@
=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.
==== //depot/perl/pod/perlfaq2.pod#71 (text) ====
Index: perl/pod/perlfaq2.pod
--- perl/pod/perlfaq2.pod#70~23466~ Tue Nov 2 04:33:57 2004
+++ perl/pod/perlfaq2.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=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 @@
=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 @@
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 @@
=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.
==== //depot/perl/pod/perlfaq3.pod#82 (text) ====
Index: perl/pod/perlfaq3.pod
--- perl/pod/perlfaq3.pod#81~23963~ Sat Feb 12 08:26:47 2005
+++ perl/pod/perlfaq3.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=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 @@
=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 @@
=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 @@
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 @@
=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.
==== //depot/perl/pod/perlfaq4.pod#94 (text) ====
Index: perl/pod/perlfaq4.pod
--- perl/pod/perlfaq4.pod#93~23509~ Wed Nov 17 02:22:52 2004
+++ perl/pod/perlfaq4.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=head2 How can I find the Julian Day?
-Use the Time::JulianDay module (part of the Time-modules bundle
-available from CPAN.)
+(contributed by brian d foy and Dave Cross)
-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.)
+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 @@
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 @@
=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 @@
=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 @@
);
$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 @@
=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.
==== //depot/perl/pod/perlfaq5.pod#59 (text) ====
Index: perl/pod/perlfaq5.pod
--- perl/pod/perlfaq5.pod#58~23647~ Mon Dec 13 23:51:43 2004
+++ perl/pod/perlfaq5.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
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 @@
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 @@
=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.
==== //depot/perl/pod/perlfaq6.pod#46 (text) ====
Index: perl/pod/perlfaq6.pod
--- perl/pod/perlfaq6.pod#45~23509~ Wed Nov 17 02:22:52 2004
+++ perl/pod/perlfaq6.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=head2 How do I efficiently match many regular expressions at once?
-The following is extremely inefficient:
+( contributed by brian d foy )
- # 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;
- }
- }
- }
+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;
+ }
+ }
-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/;
- }
- }
+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.
+
+ $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.
-
-Here are examples of the incorrect application of C<\b>, with fixes:
-
- "two words" =~ /(\w+)\b(\w+)/; # WRONG
- "two words" =~ /(\w+)\s+(\w+)/; # right
-
- " =matchless= text" =~ /\b=(\w+)=\b/; # WRONG
- " =matchless= text" =~ /=(\w+)=/; # right
-
-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.
-
-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".
+(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/.
+
+ "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.
+
+In the pattern /\Bam\B/, there must be a word character before the "a"
+and after the "m". These patterns match /\Bam\B/:
+
+ "llama" # "am" surrounded by word chars
+ "Samuel" # same
+
+These strings do not match /\Bam\B/
+
+ "Sam" # no word boundary before "a", but one after "m"
+ "I am Sam" # "am" surrounded by non-word chars
+
=head2 Why does using $&, $`, or $' slow my program down?
@@ -800,8 +856,8 @@
=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.
==== //depot/perl/pod/perlfaq7.pod#42 (text) ====
Index: perl/pod/perlfaq7.pod
--- perl/pod/perlfaq7.pod#41~23509~ Wed Nov 17 02:22:52 2004
+++ perl/pod/perlfaq7.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=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>.
-
-The C<h2xs> program will create stubs for all the important stuff for you:
-
- % h2xs -XA -n My::Module
-
-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.
+(contributed by brian d foy)
+
+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.
+
+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.
+
+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 @@
=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 @@
=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.
==== //depot/perl/pod/perlfaq8.pod#43 (text) ====
Index: perl/pod/perlfaq8.pod
--- perl/pod/perlfaq8.pod#42~23466~ Tue Nov 2 04:33:57 2004
+++ perl/pod/perlfaq8.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=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.
==== //depot/perl/pod/perlfaq9.pod#44 (text) ====
Index: perl/pod/perlfaq9.pod
--- perl/pod/perlfaq9.pod#43~23466~ Tue Nov 2 04:33:57 2004
+++ perl/pod/perlfaq9.pod Fri Mar 11 03:12:31 2005
@@ -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 @@
=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 @@
=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!
+(contributed by brian d foy)
-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).
+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 @@
=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.
End of Patch.