cvs commit: perlfaq perlfaq5.pod perlfaq6.pod
[email protected] (brian d foy) 13 Oct 2005 19:49:13 -0000
| Newsgroups | perl.cvs.perlfaq |
|---|---|
| Message-ID | <[email protected]> |
cvsuser 05/10/13 12:49:13
Modified: . perlfaq5.pod perlfaq6.pod
Log:
* sync-ed perlfaq for change 25748 which added X<> entries to several
pod files.
Revision Changes Path
1.38 +36 -1 perlfaq/perlfaq5.pod
Index: perlfaq5.pod
===================================================================
RCS file: /cvs/public/perlfaq/perlfaq5.pod,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -r1.37 -r1.38
--- perlfaq5.pod 10 Aug 2005 15:55:23 -0000 1.37
+++ perlfaq5.pod 13 Oct 2005 19:49:13 -0000 1.38
@@ -8,6 +8,7 @@
formats, and footers.
=head2 How do I flush/unbuffer an output filehandle? Why must I do this?
+X<flush> X<buffer> X<unbuffer> X<autoflush>
Perl does not support truly unbuffered output (except
insofar as you can C<syswrite(OUT, $char, 1)>), although it
@@ -61,11 +62,13 @@
$sock->autoflush();
=head2 How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?
+X<file, editing>
Use the Tie::File module, which is included in the standard
distribution since Perl 5.8.0.
=head2 How do I count the number of lines in a file?
+X<file, counting lines> X<lines> X<line>
One fairly efficient way is to count newlines in the file. The
following program uses a feature of tr///, as documented in L<perlop>.
@@ -82,6 +85,7 @@
This assumes no funny games with newline translations.
=head2 How can I use Perl's C<-i> option from within a program?
+X<-i> X<in-place>
C<-i> sets the value of Perl's C<$^I> variable, which in turn affects
the behavior of C<< <> >>; see L<perlrun> for more details. By
@@ -107,6 +111,7 @@
C<.c.orig> file.
=head2 How can I copy a file?
+X<copy> X<file, copy>
(contributed by brian d foy)
@@ -123,6 +128,7 @@
to the destination file as you read the original.
=head2 How do I make a temporary file name?
+X<file, temporary>
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
@@ -175,6 +181,7 @@
}
=head2 How can I manipulate fixed-record-length files?
+X<fixed-length> X<file, fixed-length records>
The most efficient way is using L<pack()|perlfunc/"pack"> and
L<unpack()|perlfunc/"unpack">. This is faster than using
@@ -206,6 +213,7 @@
with global variables and using symbolic references.
=head2 How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?
+X<filehandle, local> X<filehandle, passing> X<filehandle, reference>
As of perl5.6, open() autovivifies file and directory handles
as references if you pass it an uninitialized scalar variable.
@@ -234,6 +242,7 @@
check out the Symbol or IO::Handle modules.
=head2 How can I use a filehandle indirectly?
+X<filehandle, indirect>
An indirect filehandle is using something other than a symbol
in a place that a filehandle is expected. Here are ways
@@ -329,15 +338,18 @@
game doesn't help you at all here.
=head2 How can I set up a footer format to be used with write()?
+X<footer>
There's no builtin way to do this, but L<perlform> has a couple of
techniques to make it possible for the intrepid hacker.
=head2 How can I write() into a string?
+X<write, into a string>
See L<perlform/"Accessing Formatting Internals"> for an swrite() function.
=head2 How can I output my numbers with commas added?
+X<number, commify>
(contributed by brian d foy and Benjamin Goldberg)
@@ -373,6 +385,7 @@
)/$1,/xg;
=head2 How can I translate tildes (~) in a filename?
+X<tilde> X<tilde expansion>
Use the <> (glob()) operator, documented in L<perlfunc>. Older
versions of Perl require that you have a shell installed that groks
@@ -395,6 +408,7 @@
}ex;
=head2 How come when I open a file read-write it wipes it out?
+X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating>
Because you're using something like this, which truncates the file and
I<then> gives you read-write access:
@@ -468,6 +482,7 @@
See also the new L<perlopentut> if you have it (new for 5.6).
=head2 Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>?
+X<argument list too long>
The C<< <> >> operator performs a globbing operation (see above).
In Perl versions earlier than v5.6.0, the internal glob() operator forks
@@ -481,6 +496,7 @@
one that doesn't use the shell to do globbing.
=head2 Is there a leak/bug in glob()?
+X<glob>
Due to the current implementation on some operating systems, when you
use the glob() function or its angle-bracket alias in a scalar
@@ -488,6 +504,7 @@
best therefore to use glob() only in list context.
=head2 How can I open a file with a leading ">" or trailing blanks?
+X<filename, special characters>
(contributed by Brian McCauley)
@@ -504,6 +521,7 @@
open FILE, ">", ">file"; # filename is ">file"
=head2 How can I reliably rename a file?
+X<rename> X<mv> X<move> X<file, rename> X<ren>
If your operating system supports a proper mv(1) utility or its
functional equivalent, this works:
@@ -519,6 +537,7 @@
Newer versions of File::Copy export a move() function.
=head2 How can I lock a file?
+X<lock> X<file, lock> X<flock>
Perl's builtin flock() function (see L<perlfunc> for details) will call
flock(2) if that exists, fcntl(2) if it doesn't (on perl version 5.004 and
@@ -566,6 +585,7 @@
=back
=head2 Why can't I just open(FH, "E<gt>file.lock")?
+X<lock, lockfile race condition>
A common bit of code B<NOT TO USE> is this:
@@ -585,6 +605,7 @@
these tend to involve busy-wait, which is also subdesirable.
=head2 I still don't get locking. I just want to increment the number in the file. How can I do this?
+X<counter> X<file, counter>
Didn't anyone ever tell you web-page hit counters were useless?
They don't count number of hits, they're a waste of time, and they serve
@@ -609,6 +630,7 @@
If the count doesn't impress your friends, then the code might. :-)
=head2 All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?
+X<append> X<file, append>
If you are on a system that correctly implements flock() and you use the
example appending code from "perldoc -f flock" everything will be OK
@@ -637,6 +659,7 @@
systems where this probability is reduced to zero.
=head2 How do I randomly update a binary file?
+X<file, binary patch>
If you're just trying to patch a binary, in many cases something as
simple as this works:
@@ -660,6 +683,7 @@
Don't forget them or you'll be quite sorry.
=head2 How do I get a file's timestamp in perl?
+X<timestamp> X<file, timestamp>
If you want to retrieve the time at which the file was last
read, written, or had its meta-data (owner, etc) changed,
@@ -693,6 +717,7 @@
for details.
=head2 How do I set a file's timestamp in perl?
+X<timestamp> X<file, timestamp>
You use the utime() function documented in L<perlfunc/utime>.
By way of example, here's a little program that copies the
@@ -718,6 +743,7 @@
the filesystems, not of utime().
=head2 How do I print to more than one file at once?
+X<print, to multiple files>
To connect one filehandle to several output filehandles,
you can use the IO::Tee or Tie::FileHandle::Multiplex modules.
@@ -728,6 +754,7 @@
for $fh (FH1, FH2, FH3) { print $fh "whatever\n" }
=head2 How can I read in an entire file all at once?
+X<slurp> X<file, slurping>
You can use the File::Slurp module to do it in one step.
@@ -781,6 +808,7 @@
and reads that many bytes into the buffer $var.
=head2 How can I read in a file by paragraphs?
+X<file, reading by paragraphs>
Use the C<$/> variable (see L<perlvar> for details). You can either
set it to C<""> to eliminate empty paragraphs (C<"abc\n\n\n\ndef">,
@@ -791,6 +819,7 @@
S<C<"fred\n \nstuff\n\n">> is one paragraph, but C<"fred\n\nstuff\n\n"> is two.
=head2 How can I read a single character from a file? From the keyboard?
+X<getc> X<file, reading one character at a time>
You can use the builtin C<getc()> function for most filehandles, but
it won't (easily) work on a terminal device. For STDIN, either use
@@ -922,6 +951,7 @@
pipes, and tty devices work, but I<not> files.
=head2 How do I do a C<tail -f> in perl?
+X<tail>
First try
@@ -950,6 +980,7 @@
There's also a File::Tail module from CPAN.
=head2 How do I dup() a filehandle in Perl?
+X<dup>
If you check L<perlfunc/open>, you'll see that several of the ways
to call open() should do the trick. For example:
@@ -970,6 +1001,7 @@
Error checking, as always, has been left as an exercise for the reader.
=head2 How do I close a file descriptor by number?
+X<file, closing file descriptors>
This should rarely be necessary, as the Perl close() function is to be
used for things that Perl opened itself, even if it was a dup of a
@@ -989,6 +1021,7 @@
}
=head2 Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?
+X<filename, DOS issues>
Whoops! You just put a tab and a formfeed into that filename!
Remember that within double quoted strings ("like\this"), the
@@ -1005,6 +1038,7 @@
are more portable, too.
=head2 Why doesn't glob("*.*") get all the files?
+X<glob>
Because even on non-Unix ports, Perl's glob function follows standard
Unix globbing semantics. You'll need C<glob("*")> to get all (non-hidden)
@@ -1027,6 +1061,7 @@
the permissions of the file govern whether you're allowed to.
=head2 How do I select a random line from a file?
+X<file, selecting a random line>
Here's an algorithm from the Camel Book:
1.36 +27 -1 perlfaq/perlfaq6.pod
Index: perlfaq6.pod
===================================================================
RCS file: /cvs/public/perlfaq/perlfaq6.pod,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -r1.35 -r1.36
--- perlfaq6.pod 10 Aug 2005 15:55:08 -0000 1.35
+++ perlfaq6.pod 13 Oct 2005 19:49:13 -0000 1.36
@@ -13,6 +13,8 @@
a number/whole/integer/float", to be precise).
=head2 How can I hope to use regular expressions without creating illegible and unmaintainable code?
+X<regex, legibility> X<regexp, legibility>
+X<regular expression, legibility> X</x>
Three techniques can make regular expressions maintainable and
understandable.
@@ -69,6 +71,7 @@
=back
=head2 I'm having trouble matching over more than one line. What's wrong?
+X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
Either you don't have more than one line in the string you're looking
at (probably), or else you aren't using the correct modifier(s) on
@@ -121,6 +124,7 @@
}
=head2 How can I pull out lines between two patterns that are themselves on different lines?
+X<..>
You can use Perl's somewhat exotic C<..> operator (documented in
L<perlop>):
@@ -146,6 +150,8 @@
}
=head2 I put a regular expression into $/ but it didn't work. What's wrong?
+X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in>
+X<$RS, regexes in>
Up to Perl 5.8.0, $/ has to be a string. This may change in 5.10,
but don't get your hopes up. Until then, you can use these examples
@@ -189,6 +195,8 @@
=head2 How do I substitute case insensitively on the LHS while preserving case on the RHS?
+X<replace, case preserving> X<substitute, case preserving>
+X<substitution, case preserving> X<s, case preserving>
Here's a lovely Perlish solution by Larry Rosler. It exploits
properties of bitwise xor on ASCII strings.
@@ -278,6 +286,7 @@
}
=head2 How can I make C<\w> match national character sets?
+X<\w>
Put C<use locale;> in your script. The \w character class is taken
from the current locale.
@@ -285,6 +294,7 @@
See L<perllocale> for details.
=head2 How can I match a locale-smart version of C</[a-zA-Z]/>?
+X<alpha>
You can use the POSIX character class syntax C</[[:alpha:]]/>
documented in L<perlre>.
@@ -296,6 +306,7 @@
the digits and the underscore, or C</[\W\d_]/>.
=head2 How can I quote a variable to use in a regex?
+X<regex, escaping> X<regexp, escaping> X<regular expression, escaping>
The Perl parser will expand $variable and @variable references in
regular expressions unless the delimiter is a single quote. Remember,
@@ -326,6 +337,7 @@
regular character, so that C<P.> matches a C<P> followed by a dot.
=head2 What is C</o> really for?
+X</o>
Using a variable in a regular expression match forces a re-evaluation
(and perhaps recompilation) each time the regular expression is
@@ -414,6 +426,8 @@
s#/\*[^*]*\*+([^/*][^*]*\*+)*/|//[^\n]*|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse;
=head2 Can I use Perl regular expressions to match balanced text?
+X<regex, matching balanced test> X<regexp, matching balanced test>
+X<regular expression, matching balanced test>
Historically, Perl regular expressions were not capable of matching
balanced text. As of more recent versions of perl including 5.6.1
@@ -442,6 +456,7 @@
but they are undocumented.
=head2 What does it mean that regexes are greedy? How can I get around it?
+X<greedy> X<greediness>
Most people mean that greedy regexes match as much as they can.
Technically speaking, it's actually the quantifiers (C<?>, C<*>, C<+>,
@@ -462,6 +477,7 @@
playing hot potato.
=head2 How do I process each word on each line?
+X<word>
Use the split function:
@@ -513,10 +529,13 @@
sort a hash (optionally by value instead of key)?".
=head2 How can I do approximate matching?
+X<match, approximate> X<matching, approximate>
See the module String::Approx available from CPAN.
=head2 How do I efficiently match many regular expressions at once?
+X<regex, efficiency> X<regexp, efficiency>
+X<regular expression, efficiency>
( contributed by brian d foy )
@@ -572,6 +591,7 @@
expressions, you can tune them for individual situations.
=head2 Why don't word-boundary searches with C<\b> work for me?
+X<\b>
(contributed by brian d foy)
@@ -629,6 +649,7 @@
=head2 Why does using $&, $`, or $' slow my program down?
+X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`>
(contributed by Anno Siegel)
@@ -649,6 +670,7 @@
string copying.
=head2 What good is C<\G> in a regular expression?
+X<\G>
You use the C<\G> anchor to start the next match on the same
string where the last match left off. The regular
@@ -742,6 +764,7 @@
pattern.
=head2 Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
+X<DFA> X<NFA> X<POSIX>
While it's true that Perl's regular expressions resemble the DFAs
(deterministic finite automata) of the egrep(1) program, they are in
@@ -755,6 +778,7 @@
L<perlfaq2>).
=head2 What's wrong with using grep in a void context?
+X<grep>
The problem is that grep builds a return list, regardless of the context.
This means you're making Perl go to the trouble of building a list that
@@ -767,6 +791,8 @@
context, no lists are constructed.
=head2 How can I match strings with multibyte characters?
+X<regex, and multibyte characters> X<regexp, and multibyte characters>
+X<regular expression, and multibyte characters>
Starting from Perl 5.6 Perl has had some level of multibyte character
support. Perl 5.8 or later is recommended. Supported multibyte