FAQ sync.
Rafael Garcia-Suarez [Wed, 26 Oct 2005 12:52:37 +0000 (12:52 +0000)]
p4raw-id: //depot/perl@25857

pod/perlfaq.pod
pod/perlfaq2.pod
pod/perlfaq3.pod
pod/perlfaq4.pod
pod/perlfaq5.pod
pod/perlfaq6.pod
pod/perlfaq7.pod
pod/perlfaq9.pod

index 1e02381..e657fde 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq - frequently asked questions about Perl ($Date: 2005/08/10 16:01:17 $)
+perlfaq - frequently asked questions about Perl ($Revision: 1.26 $, $Date: 2005/10/13 19:50:54 $)
 
 =head1 DESCRIPTION
 
@@ -45,7 +45,7 @@ Several people have contributed answers, corrections, and comments.
 
 =head1 Author and Copyright Information
 
-Copyright (c) 1997-2003 Tom Christiansen, Nathan Torkington, and 
+Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and 
 other contributors noted in the answers.
 
 All rights reserved.
index 34d4825..0fd1d26 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.34 $, $Date: 2005/08/10 15:56:54 $)
+perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.35 $, $Date: 2005/10/13 19:43:13 $)
 
 =head1 DESCRIPTION
 
@@ -149,9 +149,8 @@ You might also try C<perldoc perl> in case your system doesn't
 have a proper man command, or it's been misinstalled.  If that doesn't
 work, try looking in /usr/local/lib/perl5/pod for documentation.
 
-If all else fails, consult http://perldoc.cpan.org/ or
-http://www.perldoc.com/ both offer the complete documentation
-in html format.
+If all else fails, consult http://perldoc.perl.org/ which has the
+complete documentation in HTML and PDF format.
 
 Many good books have been written about Perl--see the section below
 for more details.
@@ -162,11 +161,9 @@ approach to objects, L<perlopentut> for file opening semantics,
 L<perlreftut> for managing references, L<perlretut> for regular
 expressions, L<perlthrtut> for threads, L<perldebtut> for debugging,
 and L<perlxstut> for linking C and Perl together.  There may be more
-by the time you read this.  The following URLs might also be of
-assistance:
+by the time you read this.  These URLs might also be useful:
 
-    http://perldoc.cpan.org/
-    http://www.perldoc.com/
+    http://perldoc.perl.org/
     http://bookmarks.cpan.org/search.cgi?cat=Training%2FTutorials
 
 =head2 What are the Perl newsgroups on Usenet?  Where do I post questions?
@@ -221,10 +218,11 @@ This is faster and more productive than just posting a request.
 A number of books on Perl and/or CGI programming are available.  A few
 of these are good, some are OK, but many aren't worth your money.
 There is a list of these books, some with extensive reviews, at
-http://books.perl.org/ .
+http://books.perl.org/ . If you don't see your book listed here, you
+can write to perlfaq-workers@perl.org .
 
 The incontestably definitive reference book on Perl, written by
-the creator of Perl, is now (Sept 2004) in its third edition:
+the creator of Perl, is Programming Perl:
 
        Programming Perl (the "Camel Book"):
        by Larry Wall, Tom Christiansen, and Jon Orwant
@@ -242,13 +240,13 @@ of real-world examples, mini-tutorials, and complete programs is:
        http://www.oreilly.com/catalog/perlckbk2/
 
 If you're already a seasoned programmer, then the Camel Book might
-suffice for you to learn Perl from.  If you're not, check out the
+suffice for you to learn Perl.  If you're not, check out the
 Llama book:
 
-       Learning Perl (the "Llama Book")
-       by Randal L. Schwartz and Tom Phoenix
-       ISBN 0-596-00132-0 [3rd edition July 2001]
-       http://www.oreilly.com/catalog/lperl3/
+       Learning Perl
+       by Randal L. Schwartz, Tom Phoenix, and brian d foy
+       ISBN 0-596-10105-8 [4th edition July 2005]
+       http://www.oreilly.com/catalog/learnperl4/
 
 And for more advanced information on writing larger programs,
 presented in the same style as the Llama book, continue your education
@@ -306,11 +304,6 @@ Recommended books on (or mostly on) Perl follow.
        ISBN 0-596-00032-4 [3rd edition May 2000]
        http://www.oreilly.com/catalog/perlpr3/
 
-       Perl in a Nutshell
-       by Ellen Siever, Stephan Spainhour, and Nathan Patwardhan
-       ISBN 1-56592-286-7 [1st edition December 1998]
-       http://www.oreilly.com/catalog/perlnut/
-
 =item Tutorials
 
        Beginning Perl
@@ -324,38 +317,15 @@ Recommended books on (or mostly on) Perl follow.
        http://www.manning.com/Johnson/
 
        Learning Perl
-       by Randal L. Schwartz and Tom Phoenix
-       ISBN 0-596-00132-0 [3rd edition July 2001]
-       http://www.oreilly.com/catalog/lperl3/
+       by Randal L. Schwartz, Tom Phoenix, and brian d foy
+       ISBN 0-596-10105-8 [4th edition July 2005]
+       http://www.oreilly.com/catalog/learnperl4/
 
        Learning Perl Objects, References, and Modules
        by Randal L. Schwartz, with Tom Phoenix (foreword by Damian Conway)
        ISBN 0-596-00478-8 [1st edition June 2003]
        http://www.oreilly.com/catalog/lrnperlorm/
 
-       Learning Perl on Win32 Systems
-       by Randal L. Schwartz, Erik Olson, and Tom Christiansen,
-           with foreword by Larry Wall
-       ISBN 1-56592-324-3 [1st edition August 1997]
-       http://www.oreilly.com/catalog/lperlwin/
-
-       Perl: The Programmer's Companion
-       by Nigel Chapman
-       ISBN 0-471-97563-X [1997, 3rd printing Spring 1998]
-       http://www.wiley.com/compbooks/catalog/97563-X.htm
-       http://www.wiley.com/compbooks/chapman/perl/perltpc.html (errata etc)
-
-       Cross-Platform Perl
-       by Eric Foster-Johnson
-       ISBN 1-55851-483-X [2nd edition September 2000]
-       http://www.pconline.com/~erc/perlbook.htm
-
-       MacPerl: Power and Ease
-       by Vicki Brown and Chris Nandor,
-           with foreword by Matthias Neeracher
-       ISBN 1-881957-32-2 [1st edition May 1998]
-       http://www.macperl.com/ptf_book/
-
 =item Task-Oriented
 
        Writing Perl Modules for CPAN
index b5f3562..67a8d43 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq3 - Programming Tools ($Revision: 1.51 $, $Date: 2005/08/10 15:56:39 $)
+perlfaq3 - Programming Tools ($Revision: 1.52 $, $Date: 2005/10/13 19:43:13 $)
 
 =head1 DESCRIPTION
 
@@ -47,7 +47,7 @@ shell that combines the interactive nature of a Unix shell with the
 power of Perl. The goal is a full featured shell that behaves as
 expected for normal shell activity and uses Perl syntax and
 functionality for control-flow statements and other things.
-You can get psh at http://www.focusresearch.com/gregor/psh/ .
+You can get psh at http://sourceforge.net/projects/psh/ .
 
 Zoidberg is a similar project and provides a shell written in perl,
 configured in perl and operated in perl. It is intended as a login shell
@@ -772,30 +772,26 @@ 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 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.
+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.
+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
+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.
-
+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?
 
@@ -923,12 +919,11 @@ guides and references in L<perlfaq9> or in the CGI MetaFAQ:
 
 A good place to start is L<perltoot>, and you can use L<perlobj>,
 L<perlboot>, L<perltoot>, L<perltooc>, and L<perlbot> for reference.
-(If you are using really old Perl, you may not have all of these,
-try http://www.perldoc.com/ , but consider upgrading your perl.)
 
 A good book on OO on Perl is the "Object-Oriented Perl"
-by Damian Conway from Manning Publications,
-http://www.manning.com/Conway/index.html
+by Damian Conway from Manning Publications, or "Learning Perl
+References, Objects, & Modules" by Randal Schwartz and Tom
+Phoenix from O'Reilly Media.
 
 =head2 Where can I learn about linking C with Perl?
 
index 876ef78..179681b 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq4 - Data Manipulation ($Revision: 1.67 $, $Date: 2005/08/10 15:55:49 $)
+perlfaq4 - Data Manipulation ($Revision: 1.69 $, $Date: 2005/10/14 15:34:06 $)
 
 =head1 DESCRIPTION
 
@@ -1212,6 +1212,8 @@ same thing.
 
 =head2 How can I tell whether a certain element is contained in a list or array?
 
+(portions of this answer contributed by Anno Siegel)
+
 Hearing the word "in" is an I<in>dication that you probably should have
 used a hash, not a list or array, to store your data.  Hashes are
 designed to answer this question quickly and efficiently.  Arrays aren't.
@@ -1247,28 +1249,35 @@ quite a lot of space by using bit strings instead:
 
 Now check whether C<vec($read,$n,1)> is true for some C<$n>.
 
-Please do not use
+These methods guarantee fast individual tests but require a re-organization
+of the original list or array.  They only pay off if you have to test
+multiple values against the same array.
 
-    ($is_there) = grep $_ eq $whatever, @array;
+If you are testing only once, the standard module List::Util exports
+the function C<first> for this purpose.  It works by stopping once it
+finds the element. It's written in C for speed, and its Perl equivalant
+looks like this subroutine:
 
-or worse yet
+       sub first (&@) {
+               my $code = shift;
+               foreach (@_) {
+                       return $_ if &{$code}();
+               }
+               undef;
+       }
 
-    ($is_there) = grep /$whatever/, @array;
+If speed is of little concern, the common idiom uses grep in scalar context
+(which returns the number of items that passed its condition) to traverse the
+entire list. This does have the benefit of telling you how many matches it
+found, though.
 
-These are slow (checks every element even if the first matches),
-inefficient (same reason), and potentially buggy (what if there are
-regex characters in $whatever?).  If you're only testing once, then
-use:
+       my $is_there = grep $_ eq $whatever, @array;
 
-    $is_there = 0;
-    foreach $elt (@array) {
-       if ($elt eq $elt_to_find) {
-           $is_there = 1;
-           last;
-       }
-    }
-    if ($is_there) { ... }
+If you want to actually extract the matching elements, simply use grep in
+list context.
 
+       my @matches = grep $_ eq $whatever, @array;
+       
 =head2 How do I compute the difference of two arrays?  How do I compute the intersection of two arrays?
 
 Use a hash.  Here's code to do both and more.  It assumes that
@@ -1982,8 +1991,18 @@ in L<perltoot>.
 
 =head2 How can I use a reference as a hash key?
 
-You can't do this directly, but you could use the standard Tie::RefHash
-module distributed with Perl.
+(contributed by brian d foy)
+
+Hash keys are strings, so you can't really use a reference as the key.
+When you try to do that, perl turns the reference into its stringified
+form (for instance, C<HASH(0xDEADBEEF)>). From there you can't get back
+the reference from the stringified form, at least without doing some
+extra work on your own. Also remember that hash keys must be unique, but
+two different variables can store the same reference (and those variables
+can change later).
+
+The Tie::RefHash module, which is distributed with perl, might be what
+you want. It handles that extra work.
 
 =head1 Data: Misc
 
index bab49a2..31db204 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq5 - Files and Formats ($Revision: 1.37 $, $Date: 2005/08/10 15:55:23 $)
+perlfaq5 - Files and Formats ($Revision: 1.38 $, $Date: 2005/10/13 19:49:13 $)
 
 =head1 DESCRIPTION
 
index b778a58..3cfeadf 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq6 - Regular Expressions ($Revision: 1.35 $, $Date: 2005/08/10 15:55:08 $)
+perlfaq6 - Regular Expressions ($Revision: 1.36 $, $Date: 2005/10/13 19:49:13 $)
 
 =head1 DESCRIPTION
 
index 2dd24a4..cca3b17 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq7 - General Perl Language Issues ($Revision: 1.25 $, $Date: 2005/08/08 02:38:25 $)
+perlfaq7 - General Perl Language Issues ($Revision: 1.26 $, $Date: 2005/10/13 19:43:13 $)
 
 =head1 DESCRIPTION
 
@@ -271,24 +271,40 @@ $line back in its caller's scope.
 
 =head2 What is variable suicide and how can I prevent it?
 
-Variable suicide is when you (temporarily or permanently) lose the
-value of a variable.  It is caused by scoping through my() and local()
-interacting with either closures or aliased foreach() iterator
-variables and subroutine arguments.  It used to be easy to
-inadvertently lose a variable's value this way, but now it's much
-harder.  Take this code:
+This problem was fixed in perl 5.004_05, so preventing it means upgrading
+your version of perl. ;)
 
-    my $f = "foo";
+Variable suicide is when you (temporarily or permanently) lose the value
+of a variable.  It is caused by scoping through my() and local()
+interacting with either closures or aliased foreach() iterator variables
+and subroutine arguments.  It used to be easy to inadvertently lose a
+variable's value this way, but now it's much harder.  Take this code:
+
+    my $f = 'foo';
     sub T {
-      while ($i++ < 3) { my $f = $f; $f .= "bar"; print $f, "\n" }
+      while ($i++ < 3) { my $f = $f; $f .= $i; print $f, "\n" }
     }
     T;
     print "Finally $f\n";
 
+If you are experiencing variable suicide, that C<my $f> in the subroutine
+doesn't pick up a fresh copy of the C<$f> whose value is <foo>. The output
+shows that inside the subroutine the value of C<$f> leaks through when it
+shouldn't, as in this output:
+
+       foobar
+       foobarbar
+       foobarbarbar
+       Finally foo
+
 The $f that has "bar" added to it three times should be a new C<$f>
-(C<my $f> should create a new local variable each time through the loop).
-It isn't, however.  This was a bug, now fixed in the latest releases
-(tested against 5.004_05, 5.005_03, and 5.005_56).
+C<my $f> should create a new lexical variable each time through the loop.
+The expected output is:
+
+       foobar
+       foobar
+       foobar
+       Finally foo
 
 =head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
 
index 336d22d..577d151 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq9 - Networking ($Revision: 1.23 $, $Date: 2005/08/10 15:54:54 $)
+perlfaq9 - Networking ($Revision: 1.24 $, $Date: 2005/10/13 19:43:13 $)
 
 =head1 DESCRIPTION
 
@@ -366,9 +366,9 @@ C<param()> function.
 
        use CGI qw(:standard);
 
-       my $total = param( "price" ) + param( "shipping" );
+       my $total = param( 'price' ) + param( 'shipping' );
 
-       my @items = param( "item ); # multiple values, same field name
+       my @items = param( 'item' ); # multiple values, same field name
 
 If you want an object-oriented approach, CGI.pm can do that too.
 
@@ -376,9 +376,9 @@ If you want an object-oriented approach, CGI.pm can do that too.
 
        my $cgi = CGI->new();
 
-       my $total = $cgi->param( "price" ) + $cgi->param( "shipping" );
+       my $total = $cgi->param( 'price' ) + $cgi->param( 'shipping' );
 
-       my @items = $cgi->param( "item" );
+       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