From: Rafael Garcia-Suarez Date: Mon, 12 Feb 2007 09:01:30 +0000 (+0000) Subject: FAQ sync X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ee891a001c5da2b8136d967d7fc118fac92f9465;p=p5sagit%2Fp5-mst-13.2.git FAQ sync p4raw-id: //depot/perl@30218 --- diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod index 5193f05..4a10d6a 100644 --- a/pod/perlfaq1.pod +++ b/pod/perlfaq1.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq1 - General Questions About Perl ($Revision: 7997 $) +perlfaq1 - General Questions About Perl ($Revision: 8539 $) =head1 DESCRIPTION @@ -157,7 +157,7 @@ See L for a history of Perl revisions. Ponie stands for "Perl On the New Internal Engine", started by Arthur Bergman from Fotango in 2003, and subsequently run as a project of The Perl Foundation. It was abandoned in 2006 -L . +(http://www.nntp.perl.org/group/perl.ponie.dev/487). Instead of using the current Perl internals, Ponie aimed to create a new one that would provide a translation path from Perl 5 to Perl 6 @@ -220,7 +220,7 @@ Things that make Perl easier to learn: Unix experience, almost any kind of programming experience, an understanding of regular expressions, and the ability to understand other people's code. If there's something you need to do, then it's probably already been done, and a working example is -usually available for free. Don't forget the new perl modules, either. +usually available for free. Don't forget Perl modules, either. They're discussed in Part 3 of this FAQ, along with CPAN, which is discussed in Part 2. @@ -390,15 +390,15 @@ You might find these links useful: =head1 REVISION -Revision: $Revision: 7997 $ +Revision: $Revision: 8539 $ -Date: $Date: 2006-11-01 09:29:17 +0100 (mer, 01 nov 2006) $ +Date: $Date: 2007-01-11 00:07:14 +0100 (jeu, 11 jan 2007) $ See L for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod index 2123c9e..dd028cd 100644 --- a/pod/perlfaq2.pod +++ b/pod/perlfaq2.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq2 - Obtaining and Learning about Perl ($Revision: 7996 $) +perlfaq2 - Obtaining and Learning about Perl ($Revision: 8539 $) =head1 DESCRIPTION @@ -68,6 +68,16 @@ What you need to do is get a binary version of gcc for your system first. Consult the Usenet FAQs for your operating system for information on where to get such a binary version. +You might look around the net for a pre-built binary of Perl (or a +C compiler!) that meets your needs, though: + +For Windows, Vanilla Perl (http://vanillaperl.com/) comes with a +bundled C compiler. ActivePerl is a pre-compiled version of Perl +ready-to-use. + +For Sun systems, SunFreeware.com provides binaries of most popular +applications, including compilers and Perl. + =head2 I copied the perl binary from one machine to another, but scripts don't work. That's probably because you forgot libraries, or library paths differ. @@ -510,15 +520,15 @@ the I question earlier in this document. =head1 REVISION -Revision: $Revision: 7996 $ +Revision: $Revision: 8539 $ -Date: $Date: 2006-11-01 09:24:38 +0100 (mer, 01 nov 2006) $ +Date: $Date: 2007-01-11 00:07:14 +0100 (jeu, 11 jan 2007) $ See L for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod index 028461c..434bf3a 100644 --- a/pod/perlfaq3.pod +++ b/pod/perlfaq3.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq3 - Programming Tools ($Revision: 7875 $) +perlfaq3 - Programming Tools ($Revision: 8539 $) =head1 DESCRIPTION @@ -982,15 +982,15 @@ to process and install a Perl distribution. =head1 REVISION -Revision: $Revision: 7875 $ +Revision: $Revision: 8539 $ -Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $ +Date: $Date: 2007-01-11 00:07:14 +0100 (jeu, 11 jan 2007) $ See L for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod index b4945d3..6fb4d37 100644 --- a/pod/perlfaq4.pod +++ b/pod/perlfaq4.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq4 - Data Manipulation ($Revision: 7996 $) +perlfaq4 - Data Manipulation ($Revision: 8539 $) =head1 DESCRIPTION @@ -17,7 +17,7 @@ exactly. Some real numbers lose precision in the process. This is a problem with how computers store numbers and affects all computer languages, not just Perl. -L show the gory details of number representations and +L shows the gory details of number representations and conversions. To limit the number of decimal places in your numbers, you can use the @@ -362,17 +362,16 @@ pseudorandom generator than comes with your operating system, look at =head2 How do I get a random number between X and Y? -To get a random number between two values, you can use the -C builtin to get a random number between 0 and +To get a random number between two values, you can use the C +builtin to get a random number between 0 and 1. From there, you shift +that into the range that you want. -C returns a number such that -C<< 0 <= rand($x) < $x >>. Thus what you want to have perl -figure out is a random number in the range from 0 to the -difference between your I and I. +C returns a number such that C<< 0 <= rand($x) < $x >>. Thus +what you want to have perl figure out is a random number in the range +from 0 to the difference between your I and I. -That is, to get a number between 10 and 15, inclusive, you -want a random number between 0 and 5 that you can then add -to 10. +That is, to get a number between 10 and 15, inclusive, you want a +random number between 0 and 5 that you can then add to 10. my $number = 10 + int rand( 15-10+1 ); @@ -491,14 +490,14 @@ give you the same time of day, only the day before. print "Yesterday was $yesterday\n"; -You can also use the C module using its Today_and_Now +You can also use the C module using its C function. use Date::Calc qw( Today_and_Now Add_Delta_DHMS ); my @date_time = Add_Delta_DHMS( Today_and_Now(), -1, 0, 0, 0 ); - print "@date\n"; + print "@date_time\n"; Most people try to use the time rather than the calendar to figure out dates, but that assumes that days are twenty-four hours each. For @@ -1799,15 +1798,57 @@ in the 5.004 release or later of Perl for more detail. =head2 How do I process an entire hash? -Use the each() function (see L) if you don't care -whether it's sorted: +(contributed by brian d foy) + +There are a couple of ways that you can process an entire hash. You +can get a list of keys, then go through each key, or grab a one +key-value pair at a time. - while ( ($key, $value) = each %hash) { - print "$key = $value\n"; +To go through all of the keys, use the C function. This extracts +all of the keys of the hash and gives them back to you as a list. You +can then get the value through the particular key you're processing: + + foreach my $key ( keys %hash ) { + my $value = $hash{$key} + ... } -If you want it sorted, you'll have to use foreach() on the result of -sorting the keys as shown in an earlier question. +Once you have the list of keys, you can process that list before you +process the hashh elements. For instance, you can sort the keys so you +can process them in lexical order: + + foreach my $key ( sort keys %hash ) { + my $value = $hash{$key} + ... + } + +Or, you might want to only process some of the items. If you only want +to deal with the keys that start with C, you can select just +those using C: + + foreach my $key ( grep /^text:/, keys %hash ) { + my $value = $hash{$key} + ... + } + +If the hash is very large, you might not want to create a long list of +keys. To save some memory, you can grab on key-value pair at a time using +C, which returns a pair you haven't seen yet: + + while( my( $key, $value ) = each( %hash ) ) { + ... + } + +The C operator returns the pairs in apparently random order, so if +ordering matters to you, you'll have to stick with the C method. + +The C operator can be a bit tricky though. You can't add or +delete keys of the hash while you're using it without possibly +skipping or re-processing some pairs after Perl internally rehashes +all of the elements. Additionally, a hash has only one iterator, so if +you use C, C, or C on the same hash, you can reset +the iterator and mess up your processing. See the C entry in +L for more details. =head2 What happens if I add or remove keys from a hash while iterating over it? @@ -2219,15 +2260,15 @@ the C module from CPAN instead--it makes number-crunching easy. =head1 REVISION -Revision: $Revision: 7996 $ +Revision: $Revision: 8539 $ -Date: $Date: 2006-11-01 09:24:38 +0100 (mer, 01 nov 2006) $ +Date: $Date: 2007-01-11 00:07:14 +0100 (jeu, 11 jan 2007) $ See L for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod index d9ad4c3..0ed6992 100644 --- a/pod/perlfaq5.pod +++ b/pod/perlfaq5.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq5 - Files and Formats ($Revision: 8075 $) +perlfaq5 - Files and Formats ($Revision: 8579 $) =head1 DESCRIPTION @@ -117,17 +117,25 @@ be sure that you're supposed to do that on every line! close $out; To change only a particular line, the input line number, C<$.>, is -useful. Use C to skip all lines up to line 5, make a change and -print the result, then stop further processing with C. +useful. First read and print the lines up to the one you want to +change. Next, read the single line you want to change, change it, and +print it. After that, read the rest of the lines and print those: - while( <$in> ) + while( <$in> ) # print the lines before the change { - next unless $. == 5; - s/\b(perl)\b/Perl/g; print $out $_; - last; + last if $. == 4; # line number before change } + my $line = <$in>; + $line =~ s/\b(perl)\b/Perl/g; + print $out $line; + + while( <$in> ) # print the rest of the lines + { + print $out $_; + } + To skip lines, use the looping controls. The C in this example skips comment lines, and the C stops all processing once it encounters either C<__END__> or C<__DATA__>. @@ -1160,9 +1168,17 @@ a copied one. Error checking, as always, has been left as an exercise for the reader. =head2 How do I close a file descriptor by number? -X +X X X + +If, for some reason, you have a file descriptor instead of a +filehandle (perhaps you used C), you can use the +C function from the C module: -This should rarely be necessary, as the Perl close() function is to be + use POSIX (); + + POSIX::close( $fd ); + +This should rarely be necessary, as the Perl Cclose()> function is to be used for things that Perl opened itself, even if it was a dup of a numeric descriptor as with MHCONTEXT above. But if you really have to, you may be able to do this: @@ -1171,12 +1187,11 @@ to, you may be able to do this: $rc = syscall(&SYS_close, $fd + 0); # must force numeric die "can't sysclose $fd: $!" unless $rc == -1; -Or, just use the fdopen(3S) feature of open(): +Or, just use the fdopen(3S) feature of C: { - local *F; - open F, "<&=$fd" or die "Cannot reopen fd=$fd: $!"; - close F; + open my( $fh ), "<&=$fd" or die "Cannot reopen fd=$fd: $!"; + close $fh; } =head2 Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work? @@ -1265,15 +1280,15 @@ If your array contains lines, just print them: =head1 REVISION -Revision: $Revision: 8075 $ +Revision: $Revision: 8579 $ -Date: $Date: 2006-11-15 02:26:49 +0100 (mer, 15 nov 2006) $ +Date: $Date: 2007-01-14 19:28:09 +0100 (dim, 14 jan 2007) $ See L for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it diff --git a/pod/perlfaq6.pod b/pod/perlfaq6.pod index ab19de8..c872f9b 100644 --- a/pod/perlfaq6.pod +++ b/pod/perlfaq6.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq6 - Regular Expressions ($Revision: 7910 $) +perlfaq6 - Regular Expressions ($Revision: 8539 $) =head1 DESCRIPTION @@ -338,32 +338,63 @@ The use of C<\Q> causes the <.> in the regex to be treated as a regular character, so that C matches a C

followed by a dot. =head2 What is C really for? -X +X X -Using a variable in a regular expression match forces a re-evaluation -(and perhaps recompilation) each time the regular expression is -encountered. The C modifier locks in the regex the first time -it's used. This always happens in a constant regular expression, and -in fact, the pattern was compiled into the internal format at the same -time your entire program was. +(contributed by brian d foy) -Use of C is irrelevant unless variable interpolation is used in -the pattern, and if so, the regex engine will neither know nor care -whether the variables change after the pattern is evaluated the I time. +The C option for regular expressions (documented in L and +L) tells Perl to compile the regular expression only once. +This is only useful when the pattern contains a variable. Perls 5.6 +and later handle this automatically if the pattern does not change. -C is often used to gain an extra measure of efficiency by not -performing subsequent evaluations when you know it won't matter -(because you know the variables won't change), or more rarely, when -you don't want the regex to notice if they do. +Since the match operator C, the substitution operator C, +and the regular expression quoting operator C are double-quotish +constructs, you can interpolate variables into the pattern. See the +answer to "How can I quote a variable to use in a regex?" for more +details. -For example, here's a "paragrep" program: +This example takes a regular expression from the argument list and +prints the lines of input that match it: - $/ = ''; # paragraph mode - $pat = shift; - while (<>) { - print if /$pat/o; - } + my $pattern = shift @ARGV; + + while( <> ) { + print if m/$pattern/; + } + +Versions of Perl prior to 5.6 would recompile the regular expression +for each iteration, even if C<$pattern> had not changed. The C +would prevent this by telling Perl to compile the pattern the first +time, then reuse that for subsequent iterations: + + my $pattern = shift @ARGV; + + while( <> ) { + print if m/$pattern/o; # useful for Perl < 5.6 + } + +In versions 5.6 and later, Perl won't recompile the regular expression +if the variable hasn't changed, so you probably don't need the C +option. It doesn't hurt, but it doesn't help either. If you want any +version of Perl to compile the regular expression only once even if +the variable changes (thus, only using its initial value), you still +need the C. + +You can watch Perl's regular expression engine at work to verify for +yourself if Perl is recompiling a regular expression. The C pragma (comes with Perl 5.005 and later) shows the details. +With Perls before 5.6, you should see C reporting that its +compiling the regular expression on each iteration. With Perl 5.6 or +later, you should only see C report that for the first iteration. + + use re 'debug'; + + $regex = 'Perl'; + foreach ( qw(Perl Java Ruby Python) ) { + print STDERR "-" x 73, "\n"; + print STDERR "Trying $_...\n"; + print STDERR "\t$_ is good!\n" if m/$regex/; + } =head2 How do I use a regular expression to strip C style comments from a file? @@ -684,14 +715,14 @@ string where the last match left off. The regular expression engine cannot skip over any characters to find the next match with this anchor, so C<\G> is similar to the beginning of string anchor, C<^>. The C<\G> anchor is typically -used with the C flag. It uses the value of pos() +used with the C flag. It uses the value of C as the position to start the next match. As the match -operator makes successive matches, it updates pos() with the +operator makes successive matches, it updates C with the position of the next character past the last match (or the first character of the next match, depending on how you like -to look at it). Each string has its own pos() value. +to look at it). Each string has its own C value. -Suppose you want to match all of consective pairs of digits +Suppose you want to match all of consecutive pairs of digits in a string like "1122a44" and stop matching when you encounter non-digits. You want to match C<11> and C<22> but the letter shows up between C<22> and C<44> and you want @@ -701,7 +732,7 @@ the C and still matches C<44>. $_ = "1122a44"; my @pairs = m/(\d\d)/g; # qw( 11 22 44 ) -If you use the \G anchor, you force the match after C<22> to +If you use the C<\G> anchor, you force the match after C<22> to start with the C. The regular expression cannot match there since it does not find a digit, so the next match fails and the match operator returns the pairs it already @@ -719,7 +750,7 @@ still need the C flag. print "Found $1\n"; } -After the match fails at the letter C, perl resets pos() +After the match fails at the letter C, perl resets C and the next match on the same string starts at the beginning. $_ = "1122a44"; @@ -730,13 +761,13 @@ and the next match on the same string starts at the beginning. print "Found $1 after while" if m/(\d\d)/g; # finds "11" -You can disable pos() resets on fail with the C flag. -Subsequent matches start where the last successful match -ended (the value of pos()) even if a match on the same -string as failed in the meantime. In this case, the match -after the while() loop starts at the C (where the last -match stopped), and since it does not use any anchor it can -skip over the C to find "44". +You can disable C resets on fail with the C flag, documented +in L and L. Subsequent matches start where the last +successful match ended (the value of C) even if a match on the +same string has failed in the meantime. In this case, the match after +the C loop starts at the C (where the last match stopped), +and since it does not use any anchor it can skip over the C to find +C<44>. $_ = "1122a44"; while( m/\G(\d\d)/gc ) @@ -761,7 +792,7 @@ which works in 5.004 or later. } } -For each line, the PARSER loop first tries to match a series +For each line, the C loop first tries to match a series of digits followed by a word boundary. This match has to start at the place the last match left off (or the beginning of the string on the first match). Since C for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod index 0d055f5..503f69d 100644 --- a/pod/perlfaq7.pod +++ b/pod/perlfaq7.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq7 - General Perl Language Issues ($Revision: 7998 $) +perlfaq7 - General Perl Language Issues ($Revision: 8539 $) =head1 DESCRIPTION @@ -468,11 +468,11 @@ C. sub counter { $count++ } } - my $start = count(); + my $start = counter(); - .... # code that calls count(); + .... # code that calls counter(); - my $end = count(); + my $end = counter(); In the previous example, you created a function-private variable because only one function remembered its reference. You could define @@ -978,15 +978,15 @@ where you expect it so you need to adjust your shebang line. =head1 REVISION -Revision: $Revision: 7998 $ +Revision: $Revision: 8539 $ -Date: $Date: 2006-11-01 09:56:34 +0100 (mer, 01 nov 2006) $ +Date: $Date: 2007-01-11 00:07:14 +0100 (jeu, 11 jan 2007) $ See L for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it diff --git a/pod/perlfaq8.pod b/pod/perlfaq8.pod index 89f5b51..92e0694 100644 --- a/pod/perlfaq8.pod +++ b/pod/perlfaq8.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq8 - System Interaction ($Revision: 6628 $) +perlfaq8 - System Interaction ($Revision: 8539 $) =head1 DESCRIPTION @@ -804,8 +804,9 @@ this code could and probably should be written as system("cat /etc/termcap") == 0 or die "cat program failed!"; -which will get the output quickly (as it is generated, instead of only -at the end) and also check the return value. +which will echo the cat command's output as it is generated, instead +of waiting until the program has completed to print it out. It also +checks the return value. C also provides direct control over whether shell wildcard processing may take place, whereas backticks do not. @@ -1257,15 +1258,15 @@ but other times it is not. Modern programs C instead. =head1 REVISION -Revision: $Revision: 6628 $ +Revision: $Revision: 8539 $ -Date: $Date: 2006-07-09 14:46:14 +0200 (dim, 09 jui 2006) $ +Date: $Date: 2007-01-11 00:07:14 +0100 (jeu, 11 jan 2007) $ See L for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod index 54d6674..2bed9d9 100644 --- a/pod/perlfaq9.pod +++ b/pod/perlfaq9.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq9 - Networking ($Revision: 8076 $) +perlfaq9 - Networking ($Revision: 8539 $) =head1 DESCRIPTION @@ -665,15 +665,15 @@ http://search.cpan.org/search?query=RPC&mode=all ). =head1 REVISION -Revision: $Revision: 8076 $ +Revision: $Revision: 8539 $ -Date: $Date: 2006-11-15 14:53:23 +0100 (mer, 15 nov 2006) $ +Date: $Date: 2007-01-11 00:07:14 +0100 (jeu, 11 jan 2007) $ See L for source control details and availability. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and +Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it