diff options
Diffstat (limited to 'pod')
36 files changed, 6740 insertions, 140 deletions
diff --git a/pod/Makefile b/pod/Makefile index cf1e7a49d5..0ec08f992a 100644 --- a/pod/Makefile +++ b/pod/Makefile @@ -38,6 +38,16 @@ POD = \ perlxstut.pod \ perlguts.pod \ perlcall.pod \ + perlfaq.pod \ + perlfaq1.pod \ + perlfaq2.pod \ + perlfaq3.pod \ + perlfaq4.pod \ + perlfaq5.pod \ + perlfaq6.pod \ + perlfaq7.pod \ + perlfaq8.pod \ + perlfaq9.pod \ perltoc.pod MAN = \ @@ -75,6 +85,16 @@ MAN = \ perlxstut.man \ perlguts.man \ perlcall.man \ + perlfaq.man \ + perlfaq1.man \ + perlfaq2.man \ + perlfaq3.man \ + perlfaq4.man \ + perlfaq5.man \ + perlfaq6.man \ + perlfaq7.man \ + perlfaq8.man \ + perlfaq9.man \ perltoc.man HTML = \ @@ -112,6 +132,16 @@ HTML = \ perlxstut.html \ perlguts.html \ perlcall.html \ + perlfaq.html \ + perlfaq1.html \ + perlfaq2.html \ + perlfaq3.html \ + perlfaq4.html \ + perlfaq5.html \ + perlfaq6.html \ + perlfaq7.html \ + perlfaq8.html \ + perlfaq9.html \ perltoc.html TEX = \ @@ -149,6 +179,16 @@ TEX = \ perlxstut.tex \ perlguts.tex \ perlcall.tex \ + perlfaq.tex \ + perlfaq1.tex \ + perlfaq2.tex \ + perlfaq3.tex \ + perlfaq4.tex \ + perlfaq5.tex \ + perlfaq6.tex \ + perlfaq7.tex \ + perlfaq8.tex \ + perlfaq9.tex \ perltoc.tex man: pod2man $(MAN) diff --git a/pod/buildtoc b/pod/buildtoc index e8557c764f..31712e290c 100644 --- a/pod/buildtoc +++ b/pod/buildtoc @@ -5,11 +5,13 @@ use Text::Wrap; sub output ($); @pods = qw( - perl perldelta perldata perlsyn perlop perlre perlrun perlfunc - perlvar perlsub perlmod perlform perllocale perlref perldsc - perllol perltoot perlobj perltie perlbot perlipc perldebug - perldiag perlsec perltrap perlstyle perlpod perlbook perlembed - perlapio perlxs perlxstut perlguts perlcall + perl perlfaq perlfaq1 perlfaq2 perlfaq3 perlfaq4 perlfaq5 + perlfaq6 perlfaq7 perlfaq8 perlfaq9 perldelta perldata + perlsyn perlop perlre perlrun perlfunc perlvar perlsub + perlmod perlform perllocale perlref perldsc perllol perltoot + perlobj perltie perlbot perlipc perldebug perldiag perlsec + perltrap perlstyle perlpod perlbook perlembed perlapio perlxs + perlxstut perlguts perlcall ); for (@pods) { s/$/.pod/ } diff --git a/pod/perl.pod b/pod/perl.pod index f3ddc3c2c7..2c1dde2039 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -20,6 +20,7 @@ of sections: perl Perl overview (this section) perldelta Perl changes since previous version + perlfaq Perl frequently asked questions perldata Perl data structures perlsyn Perl syntax @@ -219,7 +220,7 @@ optimized C code. =back -Ok, that's I<definitely> enough hype. +Okay, that's I<definitely> enough hype. =head1 ENVIRONMENT diff --git a/pod/perlcall.pod b/pod/perlcall.pod index 9a4a886a59..1ff71fc581 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -565,7 +565,7 @@ Next, we come to XPUSHs. This is where the parameters actually get pushed onto the stack. In this case we are pushing a string and an integer. -See the L<perlguts/"XSUB's and the Argument Stack"> for details +See the L<perlguts/"XSUBs and the Argument Stack"> for details on how the XPUSH macros work. =item 6. @@ -668,7 +668,7 @@ an alternative to using these macros. The purpose of the macro C<SPAGAIN> is to refresh the local copy of the stack pointer. This is necessary because it is possible that the memory -allocated to the Perl stack has been re-allocated whilst in the +allocated to the Perl stack has been reallocated whilst in the I<perl_call_pv> call. If you are making use of the Perl stack pointer in your code you must diff --git a/pod/perldata.pod b/pod/perldata.pod index 1878f4a5fa..f0837b3854 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -247,6 +247,11 @@ The usual Unix backslash rules apply for making characters such as newline, tab, etc., as well as some more exotic forms. See L<perlop/Quote and Quotelike Operators> for a list. +Octal or hex representations in string literals (e.g. '0xffff') are not +automatically converted to their integer representation. The hex() and +oct() functions make these conversions for you. See L<perlfunc/hex> and +L<perlfunc/oct> for more details. + You can also embed newlines directly in your strings, i.e., they can end on a different line than they begin. This is nice, but if you forget your trailing quote, the error will not be reported until Perl finds @@ -279,16 +284,19 @@ single-quoted string must be separated from a preceding word by a space, because single quote is a valid (though deprecated) character in a variable name (see L<perlmod/Packages>). -Two special literals are __LINE__ and __FILE__, which represent the -current line number and filename at that point in your program. They -may be used only as separate tokens; they will not be interpolated into -strings. In addition, the token __END__ may be used to indicate the -logical end of the script before the actual end of file. Any following -text is ignored, but may be read via the DATA filehandle. (The DATA -filehandle may read data from only the main script, but not from any -required file or evaluated string.) The two control characters ^D and -^Z are synonyms for __END__ (or __DATA__ in a module; see L<SelfLoader> for -details on __DATA__). +Three special literals are __FILE__, __LINE__, and __PACKAGE__, which +represent the current filename, line number, and package name at that +point in your program. They may be used only as separate tokens; they +will not be interpolated into strings. If there is no current package +(due to a C<package;> directive), __PACKAGE__ is the undefined value. + +The tokens __END__ and __DATA__ may be used to indicate the logical end +of the script before the actual end of file. Any following text is +ignored, but may be read via a DATA filehandle: main::DATA for __END__, +or PACKNAME::DATA (where PACKNAME is the current package) for __DATA__. +The two control characters ^D and ^Z are synonyms for __END__ (or +__DATA__ in a module). See L<SelfLoader> for more description of +__DATA__, and an example of its use. A word that has no other interpretation in the grammar will be treated as if it were a quoted string. These are known as @@ -440,6 +448,11 @@ put the list in parentheses to avoid ambiguity. Examples: # A "reverse comma operator". return (pop(@foo),pop(@foo))[0]; +You may assign to C<undef> in a list. This is useful for throwing +away some of the return values of a function: + + ($dev, $ino, undef, undef, $uid, $gid) = stat($file); + Lists may be assigned to if and only if each element of the list is legal to assign to: diff --git a/pod/perldebug.pod b/pod/perldebug.pod index a682de1ade..61263b6664 100644 --- a/pod/perldebug.pod +++ b/pod/perldebug.pod @@ -11,7 +11,7 @@ First of all, have you tried using the B<-w> switch? If you invoke Perl with the B<-d> switch, your script runs under the Perl source debugger. This works like an interactive Perl environment, prompting for debugger commands that let you examine -source code, set breakpoints, get stack back-traces, change the values of +source code, set breakpoints, get stack backtraces, change the values of variables, etc. This is so convenient that you often fire up the debugger all by itself just to test out Perl constructs interactively to see what they do. For example: @@ -102,7 +102,7 @@ Same as C<V currentpackage [vars]>. =item T -Produce a stack back-trace. See below for details on its output. +Produce a stack backtrace. See below for details on its output. =item s [expr] @@ -620,7 +620,7 @@ commands typed into the debugger. =item Stack backtrace -Here's an example of what a stack back-trace via C<T> command might +Here's an example of what a stack backtrace via C<T> command might look like: $ = main::infested called from file `Ambulation.pm' line 10 @@ -1056,4 +1056,4 @@ You cannot get the stack frame information or otherwise debug functions that were not compiled by Perl, such as C or C++ extensions. If you alter your @_ arguments in a subroutine (such as with B<shift> -or B<pop>, the stack back-trace will not show the original values. +or B<pop>, the stack backtrace will not show the original values. diff --git a/pod/perldelta.pod b/pod/perldelta.pod index cf6036ff02..958bee38ed 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -27,7 +27,7 @@ might have symbol conflicts if you embed Perl in another application, just as in the 5.003 release. By default, binary compatibility is preserved at the expense of symbol table pollution. -=head2 Subroutine Parameters Are Not Autovivified +=head2 No Autovivification of Subroutine Parameters In Perl versions 5.002 and 5.003, array and hash elements used as subroutine parameters were "autovivified"; that is, they were brought @@ -47,6 +47,13 @@ fixed. As a result, the string "$$0" is no longer equivalent to C<$$."0">, but rather to C<${$0}>. To get the old behavior, change "$$" followed by a digit to "${$}". +=head2 No Resetting of $. on Implicit Close + +The documentation for Perl 5.0 has always stated that C<$.> is I<not> +reset when an already-open file handle is re-opened with no intervening +call to C<close>. Due to a bug, perl versions 5.000 through 5.0003 +I<did> reset C<$.> under that circumstance; Perl 5.004 does not. + =head2 Changes to Tainting Checks A bug in previous versions may have failed to detect some insecure @@ -64,6 +71,15 @@ application of opcode masks. The revised Safe module has a new API and is implemented using the new Opcode module. Please read the new Opcode and Safe documentation. +=head2 Embedding Improvements + +In older versions of Perl it was not possible to create more than one +Perl interpreter instance inside a single process without leaking like a +sieve and/or crashing. The bugs that caused this behavior have all been +fixed. However, you still must take care when embedding Perl in a C +program. See the updated perlembed manpage for tips on how to manage +your interpreters. + =head2 Internal Change: FileHandle Class Based on IO::* Classes File handles are now stored internally as type IO::Handle. The @@ -124,8 +140,8 @@ This now works. (e.g. C<delete @ENV{'PATH', 'MANPATH'}>) =item flock -is now supported on more platforms, and prefers fcntl -to lockf when emulating. +is now supported on more platforms, prefers fcntl to lockf when +emulating, and always flushes before (un)locking. =item printf and sprintf @@ -283,7 +299,7 @@ are inherited by all other classes: =item isa(CLASS) -C<isa> returns I<true> if its object is blessed into a sub-class of C<CLASS> +C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS> C<isa> is also exportable and can be called as a sub with two arguments. This allows the ability to check what a reference points to. Example: @@ -459,7 +475,7 @@ a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>). Each unique hash key is only allocated once, no matter how many hashes have an entry with that key. So even if you have 100 copies of the -same hash, the hash keys never have to be re-allocated. +same hash, the hash keys never have to be reallocated. =head1 Pragmata diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 24b16128dd..e0a23b0162 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -16,8 +16,8 @@ desperation): (A) An alien error message (not generated by Perl). Optional warnings are enabled by using the B<-w> switch. Warnings may -be captured by setting C<$SIG{__WARN__}> to a reference to a routine that will be -called on each warning instead of printing it. See L<perlvar>. +be captured by setting C<$SIG{__WARN__}> to a reference to a routine that +will be called on each warning instead of printing it. See L<perlvar>. Trappable errors may be trapped using the eval operator. See L<perlfunc/eval>. @@ -339,6 +339,14 @@ Perl yourself. (F) An untrapped exception was raised while executing a BEGIN subroutine. Compilation stops immediately and the interpreter is exited. +=item BEGIN not safe after errors--compilation aborted + +(F) Perl found a C<BEGIN {}> subroutine (or a C<use> directive, which +implies a C<BEGIN {}>) after one or more compilation errors had +already occurred. Since the intended environment for the C<BEGIN {}> +could not be guaranteed (due to the errors), and since subsequent code +likely depends on its correct operation, Perl just gave up. + =item bind() on closed fd (W) You tried to do a bind on a closed socket. Did you forget to check @@ -646,7 +654,7 @@ buffer. =item Can't open %s: %s -(S) An inplace edit couldn't open the original file for the indicated reason. +(S) An in-place edit couldn't open the original file for the indicated reason. Usually this is because you don't have read permission for the file. =item Can't open bidirectional pipe @@ -1066,8 +1074,8 @@ the line, and you really meant a "less than". =item Global symbol "%s" requires explicit package name -(F) You've said "use strict vars", which indicates that all variables must -either be lexically scoped (using "my"), or explicitly qualified to +(F) You've said "use strict vars", which indicates that all variables +must either be lexically scoped (using "my"), or explicitly qualified to say which package the global variable is in (using "::"). =item goto must have label @@ -1099,8 +1107,20 @@ or it may indicate that a logical name table has been corrupted. (F) A carriage return character was found in the input. This is an error, and not a warning, because carriage return characters can break -here documents (e.g. C<print E<lt>E<lt>EOF;>). Note that Perl always -opens scripts in text mode, so this error should only occur in C<eval>. +here documents (e.g., C<print E<lt>E<lt>EOF;>). + +Under UNIX, this error is usually caused by executing Perl code -- +either the main program, a module, or an eval'd string -- that was +transferred over a network connection from a non-UNIX system without +properly converting the text file format. + +Under systems that use something other than '\n' to delimit lines of +text, this error can also be caused by reading Perl code from a file +handle that is in binary mode (as set by the C<binmode> operator). + +In either case, the Perl code in question will probably need to be +converted with something like C<s/\x0D\x0A?/\n/g> before it can be +executed. =item Illegal division by zero @@ -1301,10 +1321,10 @@ like C<$foo[1][2][3]>, as in C. =item Name "%s::%s" used only once: possible typo -(W) Typographical errors often show up as unique variable names. If you -had a good reason for having a unique name, then just mention it -again somehow to suppress the message (the C<use vars> pragma is -provided for just this purpose). +(W) Typographical errors often show up as unique variable names. +If you had a good reason for having a unique name, then just mention +it again somehow to suppress the message. The C<use vars> pragma is +provided for just this purpose. =item Negative length @@ -1796,7 +1816,7 @@ old-fashioned way, with quotes and commas: =item Possible attempt to separate words with commas (W) qw() lists contain items separated by whitespace; therefore commas -aren't needed to separate the items. (You may have used different +aren't needed to separate the items. (You may have used different delimiters than the parentheses shown here; braces are also frequently used.) @@ -1826,9 +1846,10 @@ is now misinterpreted as open(FOO || die); -because of the strict regularization of Perl 5's grammar into unary and -list operators. (The old open was a little of both.) You must put -parentheses around the filehandle, or use the new "or" operator instead of "||". +because of the strict regularization of Perl 5's grammar into unary +and list operators. (The old open was a little of both.) You must +put parentheses around the filehandle, or use the new "or" operator +instead of "||". =item print on closed filehandle %s @@ -2104,7 +2125,7 @@ may break this. (P) The substitution was looping infinitely. (Obviously, a substitution shouldn't iterate more times than there are characters of -input, which is what happened.) See the discussion of substitution in +input, which is what happened.) See the discussion of substitution in L<perlop/"Quote and Quote-like Operators">. =item Substitution pattern not terminated @@ -2490,13 +2511,13 @@ L<perlref> for more on this. (W) A copy of the object returned from C<tie> (or C<tied>) was still valid when C<untie> was called. -=item Value of %s construct can be "0"; test with defined() +=item Value of %s can be "0"; test with defined() -(W) In a conditional expression, you used <HANDLE>, <*> (glob), or -C<readdir> as a boolean value. Each of these constructs can return a -value of "0"; that would make the conditional expression false, which -is probably not what you intended. When using these constructs in -conditional expressions, test their values with the C<defined> operator. +(W) In a conditional expression, you used <HANDLE>, <*> (glob), C<each()>, +or C<readdir()> as a boolean value. Each of these constructs can return a +value of "0"; that would make the conditional expression false, which is +probably not what you intended. When using these constructs in conditional +expressions, test their values with the C<defined> operator. =item Variable "%s" is not imported%s diff --git a/pod/perldsc.pod b/pod/perldsc.pod index fad539c0ec..61c45b970c 100644 --- a/pod/perldsc.pod +++ b/pod/perldsc.pod @@ -324,7 +324,7 @@ example, given the assignment to $LoL above, here's the debugger output: 2 'elroy' 3 'judy' -There's also a lower-case B<x> command which is nearly the same. +There's also a lowercase B<x> command which is nearly the same. =head1 CODE EXAMPLES diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod new file mode 100644 index 0000000000..8db316c24b --- /dev/null +++ b/pod/perlfaq.pod @@ -0,0 +1,138 @@ +=head1 NAME + +perlfaq - frequently asked questions about Perl ($Date: 1997/03/17 22:17:56 $) + +=head1 DESCRIPTION + +This document is structured into the following sections: + +=over + +=item perlfaq: Structural overview of the FAQ. + +This document. + +=item L<perlfaq1>: General Questions About Perl + +Very general, high-level information about Perl. + +=item L<perlfaq2>: Obtaining and Learning about Perl + +Where to find source and documentation to Perl, support and training, +and related matters. + +=item L<perlfaq3>: Programming Tools + +Programmer tools and programming support. + +=item L<perlfaq4>: Data Manipulation + +Manipulating numbers, dates, strings, arrays, hashes, and +miscellaneous data issues. + +=item L<perlfaq5>: Files and Formats + +I/O and the "f" issues: filehandles, flushing, formats and footers. + +=item L<perlfaq6>: Regexps + +Pattern matching and regular expressions. + +=item L<perlfaq7>: General Perl Language Issues + +General Perl language issues that don't clearly fit into any of the +other sections. + +=item L<perlfaq8>: System Interaction + +Interprocess communication (IPC), control over the user-interface +(keyboard, screen and pointing devices). + +=item L<perlfaq9>: Networking + +Networking, the Internet, and a few on the web. + +=back + +=head2 Where to get this document + +This document is posted regularly to comp.lang.perl.announce and +several other related newsgroups. It is available in a variety of +formats from CPAN in the /CPAN/doc/FAQs/FAQ/ directory, or on the web +at http://www.perl.com/perl/faq/ . + +=head2 How to contribute to this document + +You may mail corrections, additions, and suggestions to +perlfaq-suggestions@perl.com. Mail sent to the old perlfaq alias will +merely cause the FAQ to be sent to you. + +=head2 What will happen if you mail your Perl programming problems to the authors + +Your questions will probably go unread, unless they're suggestions of +new questions to add to the FAQ, in which case they should have gone +to the perlfaq-suggestions@perl.com instead. + +You should have read section 2 of this faq. There you would have +learned that comp.lang.perl.misc is the appropriate place to go for +free advice. If your question is really important and you require a +prompt and correct answer, you should hire a consultant. + +=head1 Credits + +When I first began the Perl FAQ in the late 80s, I never realized it +would have grown to over a hundred pages, nor that Perl would ever become +so popular and widespread. This document could not have been written +without the tremendous help provided by Larry Wall and the rest of the +Perl Porters. + +=head1 Author and Copyright Information + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. + +=head2 Non-commercial Reproduction + +Permission is granted to distribute this document, in part or in full, +via electronic means or printed copy providing that (1) that all credits +and copyright notices be retained, (2) that no charges beyond reproduction +be involved, and (3) that a reasonable attempt be made to use the most +current version available. + +Furthermore, you may include this document in any distribution of the +full Perl source or binaries, in its verbatim documentation, or on a +complete dump of the CPAN archive, providing that the three stipulations +given above continue to be met. + +=head2 Commercial Reproduction + +Requests for all other distribution rights, including the incorporation +in part or in full of this text or its code into commercial products +such as but not limited to books, magazine articles, or CD-ROMs, must +be made to perlfaq-legal@perl.com. Any commercial use of any portion +of this document without prior written authorization by its authors +will be subject to appropriate action. + +=head2 Disclaimer + +This information is offered in good faith and in the hope that it may +be of use, but is not guaranteed to be correct, up to date, or suitable +for any particular purpose whatsoever. The authors accept no liability +in respect of this information or its use. + +=head1 Changes + +=over 4 + +=item 17/March/97 Version + +Various typos fixed throughout. + +Added new question on Perl BNF on L<perlfaq7>. + +=item Initial Release: 11/March/97 + +This is the initial release of version 3 of the FAQ; consequently there +have been no changes since its initial release. + +=back diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod new file mode 100644 index 0000000000..2510a4b1f1 --- /dev/null +++ b/pod/perlfaq1.pod @@ -0,0 +1,248 @@ +=head1 NAME + +perlfaq1 - General Questions About Perl ($Revision: 1.10 $) + +=head1 DESCRIPTION + +This section of the FAQ answers very general, high-level questions +about Perl. + +=head2 What is Perl? + +Perl is a high-level programming language with an eclectic heritage +written by Larry Wall and a cast of thousands. It derives from the +ubiquitous C programming language and to a lesser extent from sed, +awk, the Unix shell, and at least a dozen other tools and languages. +Perl's process, file, and text manipulation facilities make it +particularly well-suited for tasks involving quick prototyping, system +utilities, software tools, system management tasks, database access, +graphical programming, networking, and world wide web programming. +These strengths make it especially popular with system administrators +and CGI script authors, but mathematicians, geneticists, journalists, +and even managers also use Perl. Maybe you should, too. + +=head2 Who supports Perl? Who develops it? Why is it free? + +The original culture of the pre-populist Internet and the deeply-held +beliefs of Perl's author, Larry Wall, gave rise to the free and open +distribution policy of perl. Perl is supported by its users. The +core, the standard Perl library, the optional modules, and the +documentation you're reading now were all written by volunteers. See +the personal note at the end of the README file in the perl source +distribution for more details. + +In particular, the core development team (known as the Perl +Porters) are a rag-tag band of highly altruistic individuals +committed to producing better software for free than you +could hope to purchase for money. You may snoop on pending +developments via news://genetics.upenn.edu/perl.porters-gw/ and +http://www.frii.com/~gnat/perl/porters/summary.html. + +While the GNU project includes Perl in its distributions, there's no +such thing as "GNU Perl". Perl is not produced nor maintained by the +Free Software Foundation. Perl's licensing terms are also more open +than GNU software's tend to be. + +You can get commercial support of Perl if you wish, although for most +users the informal support will more than suffice. See the answer to +"Where can I buy a commercial version of perl?" for more information. + +=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. The last +production release was 5.003, and the current experimental release for +those at the bleeding edge (as of 27/03/97) is 5.003_92, considered a beta +for production release 5.004, which will probably be out by the time +you read this. Further references to the Perl language in this document +refer to the current production release unless otherwise specified. + +=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 complete rewrite of the perl source +code from the ground up. 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. + +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. + +=head2 How stable is Perl? + +Production releases, which incorporate bug fixes and new functionality, +are widely tested before release. Since the 5.000 release, we have +averaged only about one production release per year. + +Larry and the Perl development team occasionally make changes to the +internal core of the language, but all possible efforts are made toward +backward compatibility. While not quite all perl4 scripts run flawlessly +under perl5, an update to perl should nearly never invalidate a program +written for an earlier version of perl (barring accidental bug fixes +and the rare new keyword). + +=head2 Is Perl difficult to learn? + +Perl is easy to start learning -- and easy to keep learning. It looks +like most programming languages you're likely to have had experience +with, so if you've ever written an C program, an awk script, a shell +script, or even an Excel macro, you're already part way there. + +Most tasks only require a small subset of the Perl language. One of +the guiding mottos for Perl development is "there's more than one way +to do it" (TMTOWTDI, sometimes pronounced "tim toady"). Perl's +learning curve is therefore shallow (easy to learn) and long (there's +a whole lot you can do if you really want). + +Finally, Perl is (frequently) an interpreted language. This means +that you can write your programs and test them without an intermediate +compilation step, allowing you to experiment and test/debug quickly +and easily. This ease of experimentation flattens the learning curve +even more. + +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. +They're discussed in Part 3 of this FAQ, along with the CPAN, which is +discussed in Part 2. + +=head2 How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl? + +Favorably in some areas, unfavorably in others. Precisely which areas +are good and bad is often a personal choice, so asking this question +on Usenet runs a strong risk of starting an unproductive Holy War. + +Probably the best thing to do is try to write equivalent code to do a +set of tasks. These languages have their own newsgroups in which you +can learn about (but hopefully not argue about) them. + +=head2 Can I do [task] in Perl? + +Perl is flexible and extensible enough for you to use on almost any +task, from one-line file-processing tasks to complex systems. For +many people, Perl serves as a great replacement for shell scripting. +For others, it serves as a convenient, high-level replacement for most +of what they'd program in low-level languages like C or C++. It's +ultimately up to you (and possibly your management ...) which tasks +you'll use Perl for and which you won't. + +If you have a library that provides an API, you can make any component +of it available as just another Perl function or variable using a Perl +extension written in C or C++ and dynamically linked into your main +perl interpreter. You can also go the other direction, and write your +main program in C or C++, and then link in some Perl code on the fly, +to create a powerful application. + +That said, there will always be small, focused, special-purpose +languages dedicated to a specific problem domain that are simply more +convenient for certain kinds of problems. Perl tries to be all things +to all people, but nothing special to anyone. Examples of specialized +languages that come to mind include prolog and matlab. + +=head2 When shouldn't I program in Perl? + +When your manager forbids it -- but do consider replacing them :-). + +Actually, one good reason is when you already have an existing +application written in another language that's all done (and done +well), or you have an application language specifically designed for a +certain task (e.g. prolog, make). + +For various reasons, Perl is probably not well-suited for real-time +embedded systems, low-level operating systems development work like +device drivers or context-switching code, complex multithreaded +shared-memory applications, or extremely large applications. You'll +notice that perl is not itself written in Perl. + +The new native-code compiler for Perl may reduce the limitations given +in the previous statement to some degree, but understand that Perl +remains fundamentally a dynamically typed language, and not a +statically typed one. You certainly won't be chastized if you don't +trust nuclear-plant or brain-surgery monitoring code to it. And +Larry will sleep easier, too -- Wall Street programs not +withstanding. :-) + +=head2 What's the difference between "perl" and "Perl"? + +One bit. Oh, you weren't talking ASCII? :-) Larry now uses "Perl" to +signify the language proper and "perl" the implementation of it, +i.e. the current interpreter. Hence Tom's quip that "Nothing but perl +can parse Perl." You may or may not choose to follow this usage. For +example, parallelism means "awk and perl" and "Python and Perl" look +ok, while "awk and Perl" and "Python and perl" do not. + +=head2 Is it a Perl program or a Perl script? + +It doesn't matter. + +In "standard terminology" a I<program> has been compiled to physical +machine code once, and can then be be run multiple times, whereas a +I<script> must be translated by a program each time it's used. Perl +programs, however, are usually neither strictly compiled nor strictly +interpreted. They can be compiled to a bytecode form (something of a Perl +virtual machine) or to completely different languages, like C or assembly +language. You can't tell just by looking whether the source is destined +for a pure interpreter, a parse-tree interpreter, a byte-code interpreter, +or a native-code compiler, so it's hard to give a definitive answer here. + +=head2 What is a JAPH? + +These are the "just another perl hacker" signatures that some people +sign their postings with. About 100 of the of the earlier ones are +available from http://www.perl.com/CPAN/misc/japh . + +=head2 Where can I get a list of Larry Wall witticisms? + +Over a hundred quips by Larry, from postings of his or source code, +can be found at http://www.perl.com/CPAN/misc/lwall-quotes . + +=head2 How can I convince my sysadmin/supervisor/employees to use version (5/5.004/Perl instead of some other language)? + +If your manager or employees are wary of unsupported software, or +software which doesn't officially ship with your Operating System, you +might try to appeal to their self-interest. If programmers can be +more productive using and utilizing Perl constructs, functionality, +simplicity, and power, then the typical manager/supervisor/employee +may be persuaded. Regarding using Perl in general, it's also +sometimes helpful to point out that delivery times may be reduced +using Perl, as compared to other languages. + +If you have a project which has a bottleneck, especially in terms of +translation, or testing, Perl almost certainly will provide a viable, +and quick solution. In conjunction with any persuasion effort, you +should not fail to point out that Perl is used, quite extensively, and +with extremely reliable and valuable results, at many large computer +software and/or hardware companies throughout the world. In fact, +many Unix vendors now ship Perl by default, and support is usually +just a news-posting away, if you can't find the answer in the +I<comprehensive> documentation, including this FAQ. + +If you face reluctance to upgrading from an older version of perl, +then point out that version 4 is utterly unmaintained and unsupported +by the Perl Development Team. Another big sell for Perl5 is the large +number of modules and extensions which greatly reduce development time +for any given task. Also mention that the difference between version +4 and version 5 of Perl is like the difference between awk and C++. +(Well, ok, maybe not quite that distinct, but you get the idea.) If +you want support and a reasonable guarantee that what you're +developing will continue to work in the future, then you have to run +the supported version. That probably means running the 5.004 release, +although 5.003 isn't that bad (it's just one year and one release +behind). Several important bugs were fixed from the 5.000 through +5.002 versions, though, so try upgrading past them if possible. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod new file mode 100644 index 0000000000..b4c3e9f1dc --- /dev/null +++ b/pod/perlfaq2.pod @@ -0,0 +1,419 @@ +=head1 NAME + +perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.13 $) + +=head1 DESCRIPTION + +This section of the FAQ answers questions about where to find +source and documentation for Perl, support and training, and +related matters. + +=head2 What machines support Perl? Where do I get it? + +The standard release of Perl (the one maintained by the perl +development team) is distributed only in source code form. You can +find this at http://www.perl.com/CPAN/src/latest.tar.gz, which is a +gzipped archive in POSIX tar format. This source builds with no +porting whatsoever on most Unix systems (Perl's native environment), +as well as Plan 9, VMS, QNX, OS/2, and the Amiga. + +Although it's rumored that the (imminent) 5.004 release may build +on Windows NT, this is yet to be proven. Binary distributions +for 32-bit Microsoft systems and for Apple systems can be found +http://www.perl.com/CPAN/ports/ directory. Because these are not part of +the standard distribution, they may and in fact do differ from the base +Perl port in a variety of ways. You'll have to check their respective +release notes to see just what the differences are. These differences +can be either positive (e.g. extensions for the features of the particular +platform that are not supported in the source release of perl) or negative +(e.g. might be based upon a less current source release of perl). + +A useful FAQ for Win32 Perl users is +http://www.endcontsw.com/people/evangelo/Perl_for_Win32_FAQ.html + +=head2 How can I get a binary version of Perl? + +If you don't have a C compiler because for whatever reasons your +vendor did not include one with your system, the best thing to do is +grab a binary version of gcc from the net and use that to compile perl +with. CPAN only has binaries for systems that are terribly hard to +get free compilers for, not for Unix systems. + +=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. +You really should build the whole distribution on the machine it will +eventually live on, and then type C<make install>. Most other +approaches are doomed to failure. + +One simple way to check that things are in the right place is to print out +the hard-coded @INC which perl is looking for. + + perl -e 'print join("\n",@INC)' + +If this command lists any paths which don't exist on your system, then you +may need to move the appropriate libraries to these locations, or create +symlinks, aliases, or shortcuts appropriately. + +=head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? + +Read the F<INSTALL> file, which is part of the source distribution. +It describes in detail how to cope with most idiosyncracies that the +Configure script can't work around for any given system or +architecture. + +=head2 What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? + +CPAN stands for Comprehensive Perl Archive Network, a huge archive +replicated on dozens of machines all over the world. CPAN contains +source code, non-native ports, documentation, scripts, and many +third-party modules and extensions, designed for everything from +commercial database interfaces to keyboard/screen control to web +walking and CGI scripts. The master machine for CPAN is +ftp://ftp.funet.fi/pub/languages/perl/CPAN/, but you can use the +address http://www.perl.com/CPAN/CPAN.html to fetch a copy from a +"site near you". See http://www.perl.com/CPAN (without a slash at the +end) for how this process works. + +CPAN/path/... is a naming convention for files available on CPAN +sites. CPAN indicates the base directory of a CPAN mirror, and the +rest of the path is the path from that directory to the file. For +instance, if you're using ftp://ftp.funet.fi/pub/languages/perl/CPAN +as your CPAN site, the file CPAN/misc/japh file is downloadable as +ftp://ftp.funet.fi/pub/languages/perl/CPAN/misc/japh . + +Considering that there are hundreds of existing modules in the +archive, one probably exists to do nearly anything you can think of. +Current categories under CPAN/modules/by-category/ include perl core +modules; development support; operating system interfaces; networking, +devices, and interprocess communication; data type utilities; database +interfaces; user interfaces; interfaces to other languages; filenames, +file systems, and file locking; internationalization and locale; world +wide web support; server and daemon utilities; archiving and +compression; image manipulation; mail and news; control flow +utilities; filehandle and I/O; Microsoft Windows modules; and +miscellaneous modules. + +=head2 Is there an ISO or ANSI certified version of Perl? + +Certainly not. Larry expects that he'll be certified before Perl is. + +=head2 Where can I get information on Perl? + +The complete Perl documentation is available with the perl +distribution. If you have perl installed locally, you probably have +the documentation installed as well: type C<man perl> if you're on a +system resembling Unix. This will lead you to other important man +pages. If you're not on a Unix system, access to the documentation +will be different; for example, it might be only in HTML format. But +all proper perl installations have fully-accessible documentation. + +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 the CPAN/doc directory, which contains the +complete documentation in various formats, including native pod, +troff, html, and plain text. There's also a web page at +http://www.perl.com/perl/info/documentation.html that might help. + +It's also worth noting that there's a PDF version of the complete +documentation for perl available in the CPAN/authors/id/BMIDD +directory. + +Many good books have been written about Perl -- see the section below +for more details. + +=head2 What are the Perl newsgroups on USENET? Where do I post questions? + +The now defunct comp.lang.perl newsgroup has been superseded by the +following groups: + + comp.lang.perl.announce Moderated announcement group + comp.lang.perl.misc Very busy group about Perl in general + comp.lang.perl.modules Use and development of Perl modules + comp.lang.perl.tk Using Tk (and X) from Perl + + comp.infosystems.www.authoring.cgi Writing CGI scripts for the Web. + +There is also USENET gateway to the mailing list used by the crack +Perl development team (perl5-porters) at +news://genetics.upenn.edu/perl.porters-gw/ . + +=head2 Where should I post source code? + +You should post source code to whichever group is most appropriate, +but feel free to cross-post to comp.lang.perl.misc. If you want to +cross-post to alt.sources, please make sure it follows their posting +standards, including setting the Followup-To header line to NOT +include alt.sources; see their FAQ for details. + +=head2 Perl Books + +A number 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. Tom +Christiansen maintains a list of these books, some with extensive +reviews, at http://www.perl.com/perl/critiques/index.html. + +The incontestably definitive reference book on Perl, written by the +creator of Perl and his apostles, is now in its second edition and +fourth printing. + + Programming Perl (the "Camel Book"): + Authors: Larry Wall, Tom Christiansen, and Randal Schwartz + ISBN 1-56592-149-6 (English) + ISBN 4-89052-384-7 (Japanese) + (French and German translations in progress) + +Note that O'Reilly books are color-coded: turquoise (some would call +it teal) covers indicate perl5 coverage, while magenta (some would +call it pink) covers indicate perl4 only. Check the cover color +before you buy! + +What follows is a list of the books that the FAQ authors found personally +useful. Your mileage may (but, we hope, probably won't) vary. + +If you're already a hard-core systems programmer, then the Camel Book +just might suffice for you to learn Perl from. But if you're not, +check out the "Llama Book". It currently doesn't cover perl5, but the +2nd edition is nearly done and should be out by summer 97: + + Learning Perl (the Llama Book): + Author: Randal Schwartz, with intro by Larry Wall + ISBN 1-56592-042-2 (English) + ISBN 4-89502-678-1 (Japanese) + ISBN 2-84177-005-2 (French) + ISBN 3-930673-08-8 (German) + +Another stand-out book in the turquoise O'Reilly Perl line is the "Hip +Owls" book. It covers regular expressions inside and out, with quite a +bit devoted exclusively to Perl: + + Mastering Regular Expressions (the Cute Owls Book): + Author: Jeffrey Friedl + ISBN 1-56592-257-3 + +You can order any of these books from O'Reilly & Associates, +1-800-998-9938. Local/overseas is 1-707-829-0515. If you can locate +an O'Reilly order form, you can also fax to 1-707-829-0104. See +http://www.ora.com/ on the Web. + +Recommended Perl books that are not from O'Reilly are the following: + + Cross-Platform Perl, (for Unix and Windows NT) + Author: Eric F. Johnson + ISBN: 1-55851-483-X + + How to Set up and Maintain a World Wide Web Site, (2nd edition) + Author: Lincoln Stein, M.D., Ph.D. + ISBN: 0-201-63462-7 + + CGI Programming in C & Perl, + Author: Thomas Boutell + ISBN: 0-201-42219-0 + +Note that some of these address specific application areas (e.g. the +Web) and are not general-purpose programming books. + +=head2 Perl in Magazines + +The Perl Journal is the first and only magazine dedicated to Perl. +It is published (on paper, not online) quarterly by Jon Orwant +(orwant@tpj.com), editor. Subscription information is at http://tpj.com +or via email to subscriptions@tpj.com. + +Beyond this, two other magazines that frequently carry high-quality articles +on Perl are Web Techniques (see http://www.webtechniques.com/) and +Unix Review (http://www.unixreview.com/). + +=head2 Perl on the Net: FTP and WWW Access + +To get the best (and possibly cheapest) performance, pick a site from +the list below and use it to grab the complete list of mirror sites. +>From there you can find the quickest site for you. Remember, the +following list is I<not> the complete list of CPAN mirrors. + + http://www.perl.com/CPAN (redirects to another mirror) + http://www.perl.org/CPAN + ftp://ftp.funet.fi/pub/languages/perl/CPAN/ + http://www.cs.ruu.nl/pub/PERL/CPAN/ + ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ + +=head2 What mailing lists are there for perl? + +Most of the major modules (tk, CGI, libwww-perl) have their own +mailing lists. Consult the documentation that came with the module for +subscription information. The following are a list of mailing lists +related to perl itself. + +If you subscribe to a mailing list, it behooves you to know how to +unsubscribe from it. Strident pleas to the list itself to get you off +will not be favorably received. + +=over 4 + +=item MacPerl + +There is a mailing list for discussing Macintosh Perl. Contact +"mac-perl-request@iis.ee.ethz.ch". + +Also see Matthias Neeracher's (the creator and maintainer of MacPerl) +webpage at http://www.iis.ee.ethz.ch/~neeri/macintosh/perl.html for +many links to interesting MacPerl sites, and the applications/MPW +tools, precompiled. + +=item Perl5-Porters + +The core development team have a mailing list for discussing fixes and +changes to the language. Send mail to +"perl5-porters-request@perl.org" with help in the body of the message +for information on subscribing. + +=item NTPerl + +This list is used to discuss issues involving Win32 Perl 5 (Windows NT +and Win95). Subscribe by emailing ListManager@ActiveWare.com with the +message body: + + subscribe Perl-Win32-Users + +The list software, also written in perl, will automatically determine +your address, and subscribe you automatically. To unsubscribe, email +the following in the message body to the same address like so: + + unsubscribe Perl-Win32-Users + +You can also check http://www.activeware.com/ and select "Mailing Lists" +to join or leave this list. + +=item Perl-Packrats + +Discussion related to archiving of perl materials, particularly the +Comprehensive PerlArchive Network (CPAN). Subscribe by emailing +majordomo@cis.ufl.edu: + + subscribe perl-packrats + +The list software, also written in perl, will automatically determine +your address, and subscribe you automatically. To unsubscribe, simple +prepend the same command with an "un", and mail to the same address +like so: + + unsubscribe perl-packrats + +=back + +=head2 Archives of comp.lang.perl.misc + +Have you tried Deja News or Alta Vista? + +ftp.cis.ufl.edu:/pub/perl/comp.lang.perl.*/monthly has an almost +complete collection dating back to 12/89 (missing 08/91 through +12/93). They are kept as one large file for each month. + +You'll probably want more a sophisticated query and retrieval mechanism +than a file listing, preferably one that allows you to retrieve +articles using a fast-access indices, keyed on at least author, date, +subject, thread (as in "trn") and probably keywords. The best +solution the FAQ authors know of is the MH pick command, but it is +very slow to select on 18000 articles. + +If you have, or know where can be found, the missing sections, please +let perlfaq-suggestions@perl.com know. + +=head2 Perl Training + +While some large training companies offer their own courses on Perl, +you may prefer to contact individuals near and dear to the heart of +Perl development. Two well-known members of the Perl development team +who offer such things are Tom Christiansen <perl-classes@perl.com> +and Randal Schwartz <perl-training-info@stonehenge.com>, plus their +respective minions, who offer a variety of professional tutorials +and seminars on Perl. These courses include large public seminars, +private corporate training, and fly-ins to Colorado and Oregon. +See http://www.perl.com/perl/info/training.html for more details. + +=head2 Where can I buy a commercial version of Perl? + +In a sense, Perl already I<is> commercial software: It has a licence +that you can grab and carefully read to your manager. It is +distributed in releases and comes in well-defined packages. There is a +very large user community and an extensive literature. The +comp.lang.perl.* newsgroups and several of the mailing lists provide +free answers to your questions in near real-time. Perl has +traditionally been supported by Larry, dozens of software designers +and developers, and thousands of programmers, all working for free +to create a useful thing to make life better for everyone. + +However, these answers may not suffice for managers who require a +purchase order from a company whom they can sue should anything go +wrong. Or maybe they need very serious hand-holding and contractual +obligations. Shrink-wrapped CDs with perl on them are available from +several sources if that will help. + +Or you can purchase a real support contract. Although Cygnus historically +provided this service, they no longer sell support contracts for Perl. +Instead, the Paul Ingram Group will be taking up the slack through The +Perl Clinic. The following is a commercial from them: + +"Do you need professional support for Perl and/or Oraperl? Do you need +a support contract with defined levels of service? Do you want to pay +only for what you need? + +"The Paul Ingram Group has provided quality software development and +support services to some of the world's largest corporations for ten +years. We are now offering the same quality support services for Perl +at The Perl Clinic. This service is led by Tim Bunce, an active perl +porter since 1994 and well known as the author and maintainer of the +DBI, DBD::Oracle, and Oraperl modules and author/co-maintainer of The +Perl 5 Module List. We also offer Oracle users support for Perl5 +Oraperl and related modules (which Oracle is planning to ship as part +of Oracle Web Server 3). 20% of the profit from our Perl support work +will be donated to The Perl Institute." + +For more information, contact the The Perl Clinic: + + Tel: +44 1483 424424 + Fax: +44 1483 419419 + Web: http://www.perl.co.uk/ + Email: perl-support-info@perl.co.uk or Tim.Bunce@ig.co.uk + +=head2 Where do I send bug reports? + +If you are reporting a bug in the perl interpreter or the modules +shipped with perl, use the perlbug program in the perl distribution or +email your report to perlbug@perl.com. + +If you are posting a bug with a non-standard port (see the answer to +"What platforms is Perl available for?"), a binary distribution, or a +non-standard module (such as Tk, CGI, etc), then please see the +documentation that came with it to determine the correct place to post +bugs. + +Read the perlbug man page (perl5.004 or later) for more information. + +=head2 What is perl.com? perl.org? The Perl Institute? + +perl.org is the official vehicle for The Perl Institute. The motto of +TPI is "helping people help Perl help people" (or something like +that). It's a non-profit organization supporting development, +documentation, and dissemination of perl. Current directors of TPI +include Larry Wall, Tom Christiansen, and Randal Schwartz, whom you +may have heard of somewhere else around here. + +The perl.com domain is Tom Christiansen's domain. He created it as a +public service long before perl.org came about. It's the original PBS +of the Perl world, a clearinghouse for information about all things +Perlian, accepting no paid advertisements, glossy gifs, or (gasp!) +java applets on its pages. + +=head2 How do I learn about object-oriented Perl programming? + +L<perltoot> (distributed with 5.004 or later) is a good place to start. +Also, L<perlobj>, L<perlref>, and L<perlmod> are useful references, +while L<perlbot> has some excellent tips and tricks. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod new file mode 100644 index 0000000000..121743ddbf --- /dev/null +++ b/pod/perlfaq3.pod @@ -0,0 +1,503 @@ +=head1 NAME + +perlfaq3 - Programming Tools ($Revision: 1.19 $) + +=head1 DESCRIPTION + +This section of the FAQ answers questions related to programmer tools +and programming support. + +=head2 How do I do (anything)? + +Have you looked at CPAN (see L<perlfaq2>)? The chances are that +someone has already written a module that can solve your problem. +Have you read the appropriate man pages? Here's a brief index: + + Objects perlref, perlmod, perlobj, perltie + Data Structures perlref, perllol, perldsc + Modules perlmod, perlsub + Regexps perlre, perlfunc, perlop + Moving to perl5 perltrap, perl + Linking w/C perlxstut, perlxs, perlcall, perlguts, perlembed + Various http://www.perl.com/CPAN/doc/FMTEYEWTK/index.html + (not a man-page but still useful) + +L<perltoc> provides a crude table of contents for the perl man page set. + +=head2 How can I use Perl interactively? + +The typical approach uses the Perl debugger, described in the +perldebug(1) man page, on an "empty" program, like this: + + perl -de 42 + +Now just type in any legal Perl code, and it will be immediately +evaluated. You can also examine the symbol table, get stack +backtraces, check variable values, set breakpoints, and other +operations typically found in symbolic debuggers + +=head2 Is there a Perl shell? + +In general, no. The Shell.pm module (distributed with perl) makes +perl try commands which aren't part of the Perl language as shell +commands. perlsh from the source distribution is simplistic and +uninteresting, but may still be what you want. + +=head2 How do I debug my Perl programs? + +Have you used C<-w>? + +Have you tried C<use strict>? + +Did you check the returns of each and every system call? + +Did you read L<perltrap>? + +Have you tried the Perl debugger, described in L<perldebug>? + +=head2 How do I profile my Perl programs? + +You should get the Devel::DProf module from CPAN, and also use +Benchmark.pm from the standard distribution. Benchmark lets you time +specific portions of your code, while Devel::DProf gives detailed +breakdowns of where your code spends its time. + +=head2 How do I cross-reference my Perl programs? + +The B::Xref module, shipped with the new, alpha-release Perl compiler +(not the general distribution), can be used to generate +cross-reference reports for Perl programs. + + perl -MO=Xref[,OPTIONS] foo.pl + +=head2 Is there a pretty-printer (formatter) for Perl? + +There is no program that will reformat Perl as much as indent(1) will +do for C. The complex feedback between the scanner and the parser +(this feedback is what confuses the vgrind and emacs programs) makes it +challenging at best to write a stand-alone Perl parser. + +Of course, if you simply follow the guidelines in L<perlstyle>, you +shouldn't need to reformat. + +Your editor can and should help you with source formatting. The +perl-mode for emacs can provide a remarkable amount of help with most +(but not all) code, and even less programmable editors can provide +significant assistance. + +If you are using to using vgrind program for printing out nice code to +a laser printer, you can take a stab at this using +http://www.perl.com/CPAN/doc/misc/tips/working.vgrind.entry, but the +results are not particularly satisfying for sophisticated code. + +=head2 Is there a ctags for Perl? + +There's a simple one at +http://www.perl.com/CPAN/authors/id/TOMC/scripts/ptags.gz which may do +the trick. + +=head2 Where can I get Perl macros for vi? + +For a complete version of Tom Christiansen's vi configuration file, +see ftp://ftp.perl.com/pub/vi/toms.exrc, the standard benchmark file +for vi emulators. This runs best with nvi, the current version of vi +out of Berkeley, which incidentally can be built with an embedded Perl +interpreter -- see http://www.perl.com/CPAN/src/misc . + +=head2 Where can I get perl-mode for emacs? + +Since Emacs version 19 patchlevel 22 or so, there have been both a +perl-mode.el and support for the perl debugger built in. These should +come with the standard Emacs 19 distribution. + +In the perl source directory, you'll find a directory called "emacs", +which contains a cperl-mode that color-codes keywords, provides +context-sensitive help, and other nifty things. + +Note that the perl-mode of emacs will have fits with "main'foo" +(single quote), and mess up the indentation and hilighting. You +should be using "main::foo", anyway. + +=head2 How can I use curses with Perl? + +The Curses module from CPAN provides a dynamically loadable object +module interface to a curses library. + +=head2 How can I use X or Tk with Perl? + +Tk is a completely Perl-based, object-oriented interface to the Tk +toolkit that doesn't force you to use Tcl just to get at Tk. Sx is an +interface to the Athena Widget set. Both are available from CPAN. + +=head2 How can I generate simple menus without using CGI or Tk? + +The http://www.perl.com/CPAN/authors/id/SKUNZ/perlmenu.v4.0.tar.gz +module, which is curses-based, can help with this. + +=head2 Can I dynamically load C routines into Perl? + +If your system architecture supports it, then the standard perl +on your system should also provide you with this via the +DynaLoader module. Read L<perlxstut> for details. + +=head2 What is undump? + +See the next questions. + +=head2 How can I make my Perl program run faster? + +The best way to do this is to come up with a better algorithm. +This can often make a dramatic difference. Chapter 8 in the Camel +has some efficiency tips in it you might want to look at. + +Other approaches include autoloading seldom-used Perl code. See the +AutoSplit and AutoLoader modules in the standard distribution for +that. Or you could locate the bottleneck and think about writing just +that part in C, the way we used to take bottlenecks in C code and +write them in assembler. Similar to rewriting in C is the use of +modules that have critical sections written in C (for instance, the +PDL module from CPAN). + +In some cases, it may be worth it to use the backend compiler to +produce byte code (saving compilation time) or compile into C, which +will certainly save compilation time and sometimes a small amount (but +not much) execution time. See the question about compiling your Perl +programs. + +If you're currently linking your perl executable to a shared libc.so, +you can often gain a 10-25% performance benefit by rebuilding it to +link with a static libc.a instead. This will make a bigger perl +executable, but your Perl programs (and programmers) may thank you for +it. See the F<INSTALL> file in the source distribution for more +information. + +Unsubstantiated reports allege that Perl interpreters that use sfio +outperform those that don't (for IO intensive applications). To try +this, see the F<INSTALL> file in the source distribution, especially +the "Selecting File IO mechanisms" section. + +The undump program was an old attempt to speed up your Perl program +by storing the already-compiled form to disk. This is no longer +a viable option, as it only worked on a few architectures, and +wasn't a good solution anyway. + +=head2 How can I make my Perl program take less memory? + +When it comes to time-space tradeoffs, Perl nearly always prefers to +throw memory at a problem. Scalars in Perl use more memory than +strings in C, arrays take more that, and hashes use even more. While +there's still a lot to be done, recent releases have been addressing +these issues. For example, as of 5.004, duplicate hash keys are +shared amongst all hashes using them, so require no reallocation. + +In some cases, using substr() or vec() to simulate arrays can be +highly beneficial. For example, an array of a thousand booleans will +take at least 20,000 bytes of space, but it can be turned into one +125-byte bit vector for a considerable memory savings. The standard +Tie::SubstrHash module can also help for certain types of data +structure. If you're working with specialist data structures +(matrices, for instance) modules that implement these in C may use +less memory than equivalent Perl modules. + +Another thing to try is learning whether your Perl was compiled with +the system malloc or with Perl's built-in malloc. Whichever one it +is, try using the other one and see whether this makes a difference. +Information about malloc is in the F<INSTALL> file in the source +distribution. You can find out whether you are using perl's malloc by +typing C<perl -V:usemymalloc>. + +=head2 Is it unsafe to return a pointer to local data? + +No, Perl's garbage collection system takes care of this. + + sub makeone { + my @a = ( 1 .. 10 ); + return \@a; + } + + for $i ( 1 .. 10 ) { + push @many, makeone(); + } + + print $many[4][5], "\n"; + + print "@many\n"; + +=head2 How can I free an array or hash so my program shrinks? + +You can't. Memory the system allocates to a program will never be +returned to the system. That's why long-running programs sometimes +re-exec themselves. + +However, judicious use of my() on your variables will help make sure +that they go out of scope so that Perl can free up their storage for +use in other parts of your program. (NB: my() variables also execute +about 10% faster than globals.) 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. +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. + +=head2 How can I make my CGI script more efficient? + +Beyond the normal measures described to make general Perl programs +faster or smaller, a CGI program has additional issues. It may be run +several times per second. Given that each time it runs it will need +to be re-compiled and will often allocate a megabyte or more of system +memory, this can be a killer. Compiling into C B<isn't going to help +you> because the process start-up overhead is where the bottleneck is. + +There are at least two popular ways to avoid this overhead. One +solution involves running the Apache HTTP server (available from +http://www.apache.org/) with either of the mod_perl or mod_fastcgi +plugin modules. With mod_perl and the Apache::* modules (from CPAN), +httpd will run with an embedded Perl interpreter which pre-compiles +your script and then executes it within the same address space without +forking. The Apache extension also gives Perl access to the internal +server API, so modules written in Perl can do just about anything a +module written in C can. With the FCGI module (from CPAN), a Perl +executable compiled with sfio (see the F<INSTALL> file in the +distribution) and the mod_fastcgi module (available from +http://www.fastcgi.com/) each of your perl scripts becomes a permanent +CGI daemon processes. + +Both of these solutions can have far-reaching effects on your system +and on the way you write your CGI scripts, so investigate them with +care. + +=head2 How can I hide the source for my Perl program? + +Delete it. :-) Seriously, there are a number of (mostly +unsatisfactory) solutions with varying levels of "security". + +First of all, however, you I<can't> take away read permission, because +the source code has to be readable in order to be compiled and +interpreted. (That doesn't mean that a CGI script's source is +readable by people on the web, though.) So you have to leave the +permissions at the socially friendly 0755 level. + +Some people regard this as a security problem. If your program does +insecure things, and relies on people not knowing how to exploit those +insecurities, it is not secure. It is often possible for someone to +determine the insecure things and exploit them without viewing the +source. Security through obscurity, the name for hiding your bugs +instead of fixing them, is little security indeed. + +You can try using encryption via source filters (Filter::* from CPAN). +But crackers might be able to decrypt it. You can try using the +byte-code compiler and interpreter described below, but crackers might +be able to de-compile it. You can try using the native-code compiler +described below, but crackers might be able to disassemble it. These +pose varying degrees of difficulty to people wanting to get at your +code, but none can definitively conceal it (this is true of every +language, not just Perl). + +If you're concerned about people profiting from your code, then the +bottom line is that nothing but a restrictive licence will give you +legal security. License your software and pepper it with threatening +statements like "This is unpublished proprietary software of XYZ Corp. +Your access to it does not give you permission to use it blah blah +blah." We are not lawyers, of course, so you should see a lawyer if +you want to be sure your licence's wording will stand up in court. + +=head2 How can I compile my Perl program into byte-code or C? + +Malcolm Beattie has written a multifunction backend compiler, +available from CPAN, that can do both these things. It is as of +Feb-1997 in late alpha release, which means it's fun to play with if +you're a programmer but not really for people looking for turn-key +solutions. + +I<Please> understand that 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 thus +will still 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 +(like several times faster), but this takes some tweaking of your +code. + +Malcolm will be in charge of the 5.005 release of Perl itself +to try to unify and merge his compiler and multithreading work into +the main release. + +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 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 miniscule. +For example, on one author's system, /usr/bin/perl is only 11k in +size! + +=head2 How can I get '#!perl' to work on [MSDOS,NT,...]? + +For OS/2 just use + + extproc perl -S -your_switches + +as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's +`extproc' handling). For DOS one should first invent a corresponding +batch file, and codify it in C<ALTERNATIVE_SHEBANG> (see the +F<INSTALL> file in the source distribution for more information). + +The Win95/NT installation, when using the Activeware port of Perl, +will modify the Registry to associate the .pl extension with the perl +interpreter. If you install another port, or (eventually) build your +own Win95/NT Perl using WinGCC, then you'll have to modify the +Registry yourself. + +Macintosh perl scripts will have the the appropriate Creator and +Type, so that double-clicking them will invoke the perl application. + +I<IMPORTANT!>: Whatever you do, PLEASE don't get frustrated, and just +throw the perl interpreter into your cgi-bin directory, in order to +get your scripts working for a web server. This is an EXTREMELY big +security risk. Take the time to figure out how to do it correctly. + +=head2 Can I write useful perl programs on the command line? + +Yes. Read L<perlrun> for more information. Some examples follow. +(These assume standard Unix shell quoting rules.) + + # sum first and last fields + perl -lane 'print $F[0] + $F[-1]' + + # identify text files + perl -le 'for(@ARGV) {print if -f && -T _}' * + + # remove comments from C program + perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c + + # make file a month younger than today, defeating reaper daemons + perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' * + + # find first unused uid + perl -le '$i++ while getpwuid($i); print $i' + + # display reasonable manpath + echo $PATH | perl -nl -072 -e ' + s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}' + +Ok, the last one was actually an obfuscated perl entry. :-) + +=head2 Why don't perl one-liners work on my DOS/Mac/VMS system? + +The problem is usually that the command interpreters on those systems +have rather different ideas about quoting than the Unix shells under +which the one-liners were created. On some systems, you may have to +change single-quotes to double ones, which you must I<NOT> do on Unix +or Plan9 systems. You might also have to change a single % to a %%. + +For example: + + # Unix + perl -e 'print "Hello world\n"' + + # DOS, etc. + perl -e "print \"Hello world\n\"" + + # Mac + print "Hello world\n" + (then Run "Myscript" or Shift-Command-R) + + # VMS + perl -e "print ""Hello world\n""" + +The problem is that none of this is reliable: it depends on the command +interpreter. Under Unix, the first two often work. Under DOS, it's +entirely possible neither works. If 4DOS was the command shell, I'd +probably have better luck like this: + + perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" + +Under the Mac, it depends which environment you are using. The MacPerl +shell, or MPW, is much like Unix shells in its support for several +quoting variants, except that it makes free use of the Mac's non-ASCII +characters as control characters. + +I'm afraid that there is no general solution to all of this. It is a +mess, pure and simple. + +[Some of this answer was contributed by Kenneth Albanowski.] + +=head2 Where can I learn about CGI or Web programming in Perl? + +For modules, get the CGI or LWP modules from CPAN. For textbooks, +see the two especially dedicated to web stuff in the question on +books. For problems and questions related to the web, like "Why +do I get 500 Errors" or "Why doesn't it run from the browser right +when it runs fine on the command line", see these sources: + + The Idiot's Guide to Solving Perl/CGI Problems, by Tom Christiansen + http://www.perl.com/perl/faq/idiots-guide.html + + Frequently Asked Questions about CGI Programming, by Nick Kew + ftp://rtfm.mit.edu/pub/usenet/news.answers/www/cgi-faq + http://www3.pair.com/webthing/docs/cgi/faqs/cgifaq.shtml + + Perl/CGI programming FAQ, by Shishir Gundavaram and Tom Christiansen + http://www.perl.com/perl/faq/perl-cgi-faq.html + + The WWW Security FAQ, by Lincoln Stein + http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html + + World Wide Web FAQ, by Thomas Boutell + http://www.boutell.com/faq/ + +=head2 Where can I learn about object-oriented Perl programming? + +L<perltoot> is a good place to start, and you can use L<perlobj> and +L<perlbot> for reference. Perltoot didn't come out until the 5.004 +release, but you can get a copy (in pod, html, or postscript) from +http://www.perl.com/CPAN/doc/FMTEYEWTK/ . + +=head2 Where can I learn about linking C with Perl? [h2xs, xsubpp] + +If you want to call C from Perl, start with L<perlxstut>, +moving on to L<perlxs>, L<xsubpp>, and L<perlguts>. If you want to +call Perl from C, then read L<perlembed>, L<perlcall>, and +L<perlguts>. Don't forget that you can learn a lot from looking at +how the authors of existing extension modules wrote their code and +solved their problems. + +=head2 I've read perlembed, perlguts, etc., but I can't embed perl in +my C program, what am I doing wrong? + +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 +fail, see L<perlbug> and send a bugreport with the output of +C<make test TEST_VERBOSE=1> along with C<perl -V>. + +=head2 When I tried to run my script, I got this message. What does it +mean? + +L<perldiag> has a complete list of perl's error messages and warnings, +with explanatory text. You can also use the splain program (distributed +with perl) to explain the error messages: + + perl program 2>diag.out + splain [-v] [-p] diag.out + +or change your program to explain the messages for you: + + use diagnostics; + +or + + use diagnostics -verbose; + +=head2 What's MakeMaker? + +This module (part of the standard perl distribution) is designed to +write a Makefile for an extension module from a Makefile.PL. For more +information, see L<ExtUtils::MakeMaker>. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod new file mode 100644 index 0000000000..1c1edfa467 --- /dev/null +++ b/pod/perlfaq4.pod @@ -0,0 +1,1034 @@ +=head1 NAME + +perlfaq4 - Data Manipulation ($Revision: 1.15 $) + +=head1 DESCRIPTION + +The section of the FAQ answers question related to the manipulation +of data as numbers, dates, strings, arrays, hashes, and miscellaneous +data issues. + +=head1 Data: Numbers + +=head2 Why isn't my octal data interpreted correctly? + +Perl only understands octal and hex numbers as such when they occur +as literals in your program. If they are read in from somewhere and +assigned, no automatic conversion takes place. You must explicitly +use oct() or hex() if you want the values converted. oct() interprets +both hex ("0x350") numbers and octal ones ("0350" or even without the +leading "0", like "377"), while hex() only converts hexadecimal ones, +with or without a leading "0x", like "0x255", "3A", "ff", or "deadbeef". + +This problem shows up most often when people try using chmod(), mkdir(), +umask(), or sysopen(), which all want permissions in octal. + + chmod(644, $file); # WRONG -- perl -w catches this + chmod(0644, $file); # right + +=head2 Does perl have a round function? What about ceil() and floor()? +Trig functions? + +For rounding to a certain number of digits, sprintf() or printf() is +usually the easiest route. + +The POSIX module (part of the standard perl distribution) implements +ceil(), floor(), and a number of other mathematical and trigonometric +functions. + +The Math::Complex module (part of the standard perl distribution) +defines a number of mathematical functions that can also work on real +numbers. It's not as efficient as the POSIX library, but the POSIX +library can't work with complex numbers. + +Rounding in financial applications can have serious implications, and +the rounding method used should be specified precisely. In these +cases, it probably pays not to trust whichever system rounding is +being used by Perl, but to instead implement the rounding function you +need yourself. + +=head2 How do I convert bits into ints? + +To turn a string of 1s and 0s like '10110110' into a scalar containing +its binary value, use the pack() function (documented in +L<perlfunc/"pack">): + + $decimal = pack('B8', '10110110'); + +Here's an example of going the other way: + + $binary_string = join('', unpack('B*', "\x29")); + +=head2 How do I multiply matrices? + +Use the Math::Matrix or Math::MatrixReal modules (available from CPAN) +or the PDL extension (also available from CPAN). + +=head2 How do I perform an operation on a series of integers? + +To call a function on each element in an array, and collect the +results, use: + + @results = map { my_func($_) } @array; + +For example: + + @triple = map { 3 * $_ } @single; + +To call a function on each element of an array, but ignore the +results: + + foreach $iterator (@array) { + &my_func($iterator); + } + +To call a function on each integer in a (small) range, you B<can> use: + + @results = map { &my_func($_) } (5 .. 25); + +but you should be aware that the C<..> operator creates an array of +all integers in the range. This can take a lot of memory for large +ranges. Instead use: + + @results = (); + for ($i=5; $i < 500_005; $i++) { + push(@results, &my_func($i)); + } + +=head2 How can I output Roman numerals? + +Get the http://www.perl.com/CPAN/modules/by-module/Roman module. + +=head2 Why aren't my random numbers random? + +The short explanation is that you're getting pseudorandom numbers, not +random ones, because that's how these things work. A longer +explanation is available on +http://www.perl.com/CPAN/doc/FMTEYEWTK/random, courtesy of Tom +Phoenix. + +You should also check out the Math::TrulyRandom module from CPAN. + +=head1 Data: Dates + +=head2 How do I find the week-of-the-year/day-of-the-year? + +The day of the year is in the array returned by localtime() (see +L<perlfunc/"localtime">): + + $day_of_year = (localtime(time()))[7]; + +or more legibly (in 5.004 or higher): + + use Time::localtime; + $day_of_year = localtime(time())->yday; + +You can find the week of the year by dividing this by 7: + + $week_of_year = int($day_of_year / 7); + +Of course, this believes that weeks start at zero. + +=head2 How can I compare two date strings? + +Use the Date::Manip or Date::DateCalc modules from CPAN. + +=head2 How can I take a string and turn it into epoch seconds? + +If it's a regular enough string that it always has the same format, +you can split it up and pass the parts to timelocal in the standard +Time::Local module. Otherwise, you should look into one of the +Date modules from CPAN. + +=head2 How can I find the Julian Day? + +Neither Date::Manip nor Date::DateCalc deal with Julian days. +Instead, there is an example of Julian date calculation in +http://www.perl.com/CPAN/authors/David_Muir_Sharnoff/modules/Time/JulianDay.pm.gz, +which should help. + +=head2 Does Perl have a year 2000 problem? + +Not unless you use Perl to create one. The date and time functions +supplied with perl (gmtime and localtime) supply adequate information +to determine the year well beyond 2000 (2038 is when trouble strikes). +The year returned by these functions when used in an array context is +the year minus 1900. For years between 1910 and 1999 this I<happens> +to be a 2-digit decimal number. To avoid the year 2000 problem simply +do not treat the year as a 2-digit number. It isn't. + +When gmtime() and localtime() are used in a scalar context they return +a timestamp string that contains a fully-expanded year. For example, +C<$timestamp = gmtime(1005613200)> sets $timestamp to "Tue Nov 13 01:00:00 +2001". There's no year 2000 problem here. + +=head1 Data: Strings + +=head2 How do I validate input? + +The answer to this question is usually a regular expression, perhaps +with auxiliary logic. See the more specific questions (numbers, email +addresses, etc.) for details. + +=head2 How do I unescape a string? + +It depends just what you mean by "escape". URL escapes are dealt with +in L<perlfaq9>. Shell escapes with the backslash (\) +character are removed with: + + s/\\(.)/$1/g; + +Note that this won't expand \n or \t or any other special escapes. + +=head2 How do I remove consecutive pairs of characters? + +To turn "abbcccd" into "abccd": + + s/(.)\1/$1/g; + +=head2 How do I expand function calls in a string? + +This is documented in L<perlref>. In general, this is fraught with +quoting and readability problems, but it is possible. To interpolate +a subroutine call (in a list context) into a string: + + print "My sub returned @{[mysub(1,2,3)]} that time.\n"; + +If you prefer scalar context, similar chicanery is also useful for +arbitrary expressions: + + print "That yields ${\($n + 5)} widgets\n"; + +=head2 How do I find matching/nesting anything? + +This isn't something that can be tackled in one regular expression, no +matter how complicated. To find something between two single characters, +a pattern like C</x([^x]*)x/> will get the intervening bits in $1. For +multiple ones, then something more like C</alpha(.*?)omega/> would +be needed. But none of these deals with nested patterns, nor can they. +For that you'll have to write a parser. + +=head2 How do I reverse a string? + +Use reverse() in a scalar context, as documented in +L<perlfunc/reverse>. + + $reversed = reverse $string; + +=head2 How do I expand tabs in a string? + +You can do it the old-fashioned way: + + 1 while $string =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e; + +Or you can just use the Text::Tabs module (part of the standard perl +distribution). + + use Text::Tabs; + @expanded_lines = expand(@lines_with_tabs); + +=head2 How do I reformat a paragraph? + +Use Text::Wrap (part of the standard perl distribution): + + use Text::Wrap; + print wrap("\t", ' ', @paragraphs); + +=head2 How can I access/change the first N letters of a string? + +There are many ways. If you just want to grab a copy, use +substr: + + $first_byte = substr($a, 0, 1); + +If you want to modify part of a string, the simplest way is often to +use substr() as an lvalue: + + substr($a, 0, 3) = "Tom"; + +Although those with a regexp kind of thought process will likely prefer + + $a =~ s/^.../Tom/; + +=head2 How do I change the Nth occurrence of something? + +You have to keep track. For example, let's say you want +to change the fifth occurrence of "whoever" or "whomever" +into "whosoever", case insensitively. + + $count = 0; + s{((whom?)ever)}{ + ++$count == 5 # is it the 5th? + ? "${2}soever" # yes, swap + : $1 # renege and leave it there + }igex; + +=head2 How can I count the number of occurrences of a substring within a string? + +There are a number of ways, with varying efficiency: If you want a +count of a certain single character (X) within a string, you can use the +C<tr///> function like so: + + $string = "ThisXlineXhasXsomeXx'sXinXit": + $count = ($string =~ tr/X//); + print "There are $count X charcters in the string"; + +This is fine if you are just looking for a single character. However, +if you are trying to count multiple character substrings within a +larger string, C<tr///> won't work. What you can do is wrap a while() +loop around a global pattern match. For example, let's count negative +integers: + + $string = "-9 55 48 -2 23 -76 4 14 -44"; + while ($string =~ /-\d+/g) { $count++ } + print "There are $count negative numbers in the string"; + +=head2 How do I capitalize all the words on one line? + +To make the first letter of each word upper case: + $line =~ s/\b(\w)/\U$1/g; + +To make the whole line upper case: + $line = uc($line); + +To force each word to be lower case, with the first letter upper case: + $line =~ s/(\w+)/\u\L$1/g; + +=head2 How can I split a [character] delimited string except when inside +[character]? (Comma-separated files) + +Take the example case of trying to split a string that is comma-separated +into its different fields. (We'll pretend you said comma-separated, not +comma-delimited, which is different and almost never what you mean.) You +can't use C<split(/,/)> because you shouldn't split if the comma is inside +quotes. For example, take a data line like this: + + SAR001,"","Cimetrix, Inc","Bob Smith","CAM",N,8,1,0,7,"Error, Core Dumped" + +Due to the restriction of the quotes, this is a fairly complex +problem. Thankfully, we have Jeffrey Friedl, author of a highly +recommended book on regular expressions, to handle these for us. He +suggests (assuming your string is contained in $text): + + @new = (); + push(@new, $+) while $text =~ m{ + "([^\"\\]*(?:\\.[^\"\\]*)*)",? # groups the phrase inside the quotes + | ([^,]+),? + | , + }gx; + push(@new, undef) if substr($text,-1,1) eq ','; + +Alternatively, the Text::ParseWords module (part of the standard perl +distribution) lets you say: + + use Text::ParseWords; + @new = quotewords(",", 0, $text); + +=head2 How do I strip blank space from the beginning/end of a string? + +The simplest approach, albeit not the fastest, is probably like this: + + $string =~ s/^\s*(.*?)\s*$/$1/; + +It would be faster to do this in two steps: + + $string =~ s/^\s+//; + $string =~ s/\s+$//; + +Or more nicely written as: + + for ($string) { + s/^\s+//; + s/\s+$//; + } + +=head2 How do I extract selected columns from a string? + +Use substr() or unpack(), both documented in L<perlfunc>. + +=head2 How do I find the soundex value of a string? + +Use the standard Text::Soundex module distributed with perl. + +=head2 How can I expand variables in text strings? + +Let's assume that you have a string like: + + $text = 'this has a $foo in it and a $bar'; + $text =~ s/\$(\w+)/${$1}/g; + +Before version 5 of perl, this had to be done with a double-eval +substitution: + + $text =~ s/(\$\w+)/$1/eeg; + +Which is bizarre enough that you'll probably actually need an EEG +afterwards. :-) + +=head2 What's wrong with always quoting "$vars"? + +The problem is that those double-quotes force stringification, +coercing numbers and references into strings, even when you +don't want them to be. + +If you get used to writing odd things like these: + + print "$var"; # BAD + $new = "$old"; # BAD + somefunc("$var"); # BAD + +You'll be in trouble. Those should (in 99.8% of the cases) be +the simpler and more direct: + + print $var; + $new = $old; + somefunc($var); + +Otherwise, besides slowing you down, you're going to break code when +the thing in the scalar is actually neither a string nor a number, but +a reference: + + func(\@array); + sub func { + my $aref = shift; + my $oref = "$aref"; # WRONG + } + +You can also get into subtle problems on those few operations in Perl +that actually do care about the difference between a string and a +number, such as the magical C<++> autoincrement operator or the +syscall() function. + +=head2 Why don't my <<HERE documents work? + +Check for these three things: + +=over 4 + +=item 1. There must be no space after the << part. + +=item 2. There (probably) should be a semicolon at the end. + +=item 3. You can't (easily) have any space in front of the tag. + +=back + +=head1 Data: Arrays + +=head2 What is the difference between $array[1] and @array[1]? + +The former is a scalar value, the latter an array slice, which makes +it a list with one (scalar) value. You should use $ when you want a +scalar value (most of the time) and @ when you want a list with one +scalar value in it (very, very rarely; nearly never, in fact). + +Sometimes it doesn't make a difference, but sometimes it does. +For example, compare: + + $good[0] = `some program that outputs several lines`; + +with + + @bad[0] = `same program that outputs several lines`; + +The B<-w> flag will warn you about these matters. + +=head2 How can I extract just the unique elements of an array? + +There are several possible ways, depending on whether the array is +ordered and whether you wish to preserve the ordering. + +=over 4 + +=item a) If @in is sorted, and you want @out to be sorted: + + $prev = 'nonesuch'; + @out = grep($_ ne $prev && ($prev = $_), @in); + +This is nice in that it doesn't use much extra memory, +simulating uniq(1)'s behavior of removing only adjacent +duplicates. + +=item b) If you don't know whether @in is sorted: + + undef %saw; + @out = grep(!$saw{$_}++, @in); + +=item c) Like (b), but @in contains only small integers: + + @out = grep(!$saw[$_]++, @in); + +=item d) A way to do (b) without any loops or greps: + + undef %saw; + @saw{@in} = (); + @out = sort keys %saw; # remove sort if undesired + +=item e) Like (d), but @in contains only small positive integers: + + undef @ary; + @ary[@in] = @in; + @out = @ary; + +=back + +=head2 How can I tell whether an array contains a certain element? + +There are several ways to approach this. If you are going to make +this query many times and the values are arbitrary strings, the +fastest way is probably to invert the original array and keep an +associative array lying about whose keys are the first array's values. + + @blues = qw/azure cerulean teal turquoise lapis-lazuli/; + undef %is_blue; + for (@blues) { $is_blue{$_} = 1 } + +Now you can check whether $is_blue{$some_color}. It might have been a +good idea to keep the blues all in a hash in the first place. + +If the values are all small integers, you could use a simple indexed +array. This kind of an array will take up less space: + + @primes = (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31); + undef @is_tiny_prime; + for (@primes) { $is_tiny_prime[$_] = 1; } + +Now you check whether $is_tiny_prime[$some_number]. + +If the values in question are integers instead of strings, you can save +quite a lot of space by using bit strings instead: + + @articles = ( 1..10, 150..2000, 2017 ); + undef $read; + grep (vec($read,$_,1) = 1, @articles); + +Now check whether C<vec($read,$n,1)> is true for some C<$n>. + +Please do not use + + $is_there = grep $_ eq $whatever, @array; + +or worse yet + + $is_there = grep /$whatever/, @array; + +These are slow (checks every element even if the first matches), +inefficient (same reason), and potentially buggy (what if there are +regexp characters in $whatever?). + +=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 +each element is unique in a given array: + + @union = @intersection = @difference = (); + %count = (); + foreach $element (@array1, @array2) { $count{$element}++ } + foreach $element (keys %count) { + push @union, $element; + push @{ $count{$element} > 1 ? \@intersection : \@difference }, $element; + } + +=head2 How do I find the first array element for which a condition is true? + +You can use this if you care about the index: + + for ($i=0; $i < @array; $i++) { + if ($array[$i] eq "Waldo") { + $found_index = $i; + last; + } + } + +Now C<$found_index> has what you want. + +=head2 How do I handle linked lists? + +In general, you usually don't need a linked list in Perl, since with +regular arrays, you can push and pop or shift and unshift at either end, +or you can use splice to add and/or remove arbitrary number of elements +at arbitrary points. + +If you really, really wanted, you could use structures as described in +L<perldsc> or L<perltoot> and do just what the algorithm book tells you +to do. + +=head2 How do I handle circular lists? + +Circular lists could be handled in the traditional fashion with linked +lists, or you could just do something like this with an array: + + unshift(@array, pop(@array)); # the last shall be first + push(@array, shift(@array)); # and vice versa + +=head2 How do I shuffle an array randomly? + +Here's a shuffling algorithm which works its way through the list, +randomly picking another element to swap the current element with: + + srand; + @new = (); + @old = 1 .. 10; # just a demo + while (@old) { + push(@new, splice(@old, rand @old, 1)); + } + +For large arrays, this avoids a lot of the reshuffling: + + srand; + @new = (); + @old = 1 .. 10000; # just a demo + for( @old ){ + my $r = rand @new+1; + push(@new,$new[$r]); + $new[$r] = $_; + } + +=head2 How do I process/modify each element of an array? + +Use C<for>/C<foreach>: + + for (@lines) { + s/foo/bar/; + tr[a-z][A-Z]; + } + +Here's another; let's compute spherical volumes: + + for (@radii) { + $_ **= 3; + $_ *= (4/3) * 3.14159; # this will be constant folded + } + +=head2 How do I select a random element from an array? + +Use the rand() function (see L<perlfunc/rand>): + + srand; # not needed for 5.004 and later + $index = rand @array; + $element = $array[$index]; + +=head2 How do I permute N elements of a list? + +Here's a little program that generates all permutations +of all the words on each line of input. The algorithm embodied +in the permut() function should work on any list: + + #!/usr/bin/perl -n + # permute - tchrist@perl.com + permut([split], []); + sub permut { + my @head = @{ $_[0] }; + my @tail = @{ $_[1] }; + unless (@head) { + # stop recursing when there are no elements in the head + print "@tail\n"; + } else { + # for all elements in @head, move one from @head to @tail + # and call permut() on the new @head and @tail + my(@newhead,@newtail,$i); + foreach $i (0 .. $#head) { + @newhead = @head; + @newtail = @tail; + unshift(@newtail, splice(@newhead, $i, 1)); + permut([@newhead], [@newtail]); + } + } + } + +=head2 How do I sort an array by (anything)? + +Supply a comparison function to sort() (described in L<perlfunc/sort>): + + @list = sort { $a <=> $b } @list; + +The default sort function is cmp, string comparison, which would +sort C<(1, 2, 10)> into C<(1, 10, 2)>. C<E<lt>=E<gt>>, used above, is +the numerical comparison operator. + +If you have a complicated function needed to pull out the part you +want to sort on, then don't do it inside the sort function. Pull it +out first, because the sort BLOCK can be called many times for the +same element. Here's an example of how to pull out the first word +after the first number on each item, and then sort those words +case-insensitively. + + @idx = (); + for (@data) { + ($item) = /\d+\s*(\S+)/; + push @idx, uc($item); + } + @sorted = @data[ sort { $idx[$a] cmp $idx[$b] } 0 .. $#idx ]; + +Which could also be written this way, using a trick +that's come to be known as the Schwartzian Transform: + + @sorted = map { $_->[0] } + sort { $a->[1] cmp $b->[1] } + map { [ $_, uc((/\d+\s*(\S+) )[0] ] } @data; + +If you need to sort on several fields, the following paradigm is useful. + + @sorted = sort { field1($a) <=> field1($b) || + field2($a) cmp field2($b) || + field3($a) cmp field3($b) + } @data; + +This can be conveniently combined with precalculation of keys as given +above. + +See http://www.perl.com/CPAN/doc/FMTEYEWTK/sort.html for more about +this approach. + +See also the question below on sorting hashes. + +=head2 How do I manipulate arrays of bits? + +Use pack() and unpack(), or else vec() and the bitwise operations. + +For example, this sets $vec to have bit N set if $ints[N] was set: + + $vec = ''; + foreach(@ints) { vec($vec,$_,1) = 1 } + +And here's how, given a vector in $vec, you can +get those bits into your @ints array: + + sub bitvec_to_list { + my $vec = shift; + my @ints; + # Find null-byte density then select best algorithm + if ($vec =~ tr/\0// / length $vec > 0.95) { + use integer; + my $i; + # This method is faster with mostly null-bytes + while($vec =~ /[^\0]/g ) { + $i = -9 + 8 * pos $vec; + push @ints, $i if vec($vec, ++$i, 1); + push @ints, $i if vec($vec, ++$i, 1); + push @ints, $i if vec($vec, ++$i, 1); + push @ints, $i if vec($vec, ++$i, 1); + push @ints, $i if vec($vec, ++$i, 1); + push @ints, $i if vec($vec, ++$i, 1); + push @ints, $i if vec($vec, ++$i, 1); + push @ints, $i if vec($vec, ++$i, 1); + } + } else { + # This method is a fast general algorithm + use integer; + my $bits = unpack "b*", $vec; + push @ints, 0 if $bits =~ s/^(\d)// && $1; + push @ints, pos $bits while($bits =~ /1/g); + } + return \@ints; + } + +This method gets faster the more sparse the bit vector is. +(Courtesy of Tim Bunce and Winfried Koenig.) + +=head2 Why does defined() return true on empty arrays and hashes? + +See L<perlfunc/defined> in the 5.004 release or later of Perl. + +=head1 Data: Hashes (Associative Arrays) + +=head2 How do I process an entire hash? + +Use the each() function (see L<perlfunc/each>) if you don't care +whether it's sorted: + + while (($key,$value) = each %hash) { + print "$key = $value\n"; + } + +If you want it sorted, you'll have to use foreach() on the result of +sorting the keys as shown in an earlier question. + +=head2 What happens if I add or remove keys from a hash while iterating over it? + +Don't do that. + +=head2 How do I look up a hash element by value? + +Create a reverse hash: + + %by_value = reverse %by_key; + $key = $by_value{$value}; + +That's not particularly efficient. It would be more space-efficient +to use: + + while (($key, $value) = each %by_key) { + $by_value{$value} = $key; + } + +If your hash could have repeated values, the methods above will only +find one of the associated keys. This may or may not worry you. + +=head2 How can I know how many entries are in a hash? + +If you mean how many keys, then all you have to do is +take the scalar sense of the keys() function: + + $num_keys = scalar keys %hash; + +In void context it just resets the iterator, which is faster +for tied hashes. + +=head2 How do I sort a hash (optionally by value instead of key)? + +Internally, hashes are stored in a way that prevents you from imposing +an order on key-value pairs. Instead, you have to sort a list of the +keys or values: + + @keys = sort keys %hash; # sorted by key + @keys = sort { + $hash{$a} cmp $hash{$b} + } keys %hash; # and by value + +Here we'll do a reverse numeric sort by value, and if two keys are +identical, sort by length of key, and if that fails, by straight ASCII +comparison of the keys (well, possibly modified by your locale -- see +L<perllocale>). + + @keys = sort { + $hash{$b} <=> $hash{$a} + || + length($b) <=> length($a) + || + $a cmp $b + } keys %hash; + +=head2 How can I always keep my hash sorted? + +You can look into using the DB_File module and tie() using the +$DB_BTREE hash bindings as documented in L<DB_File/"In Memory Databases">. + +=head2 What's the difference between "delete" and "undef" with hashes? + +Hashes are pairs of scalars: the first is the key, the second is the +value. The key will be coerced to a string, although the value can be +any kind of scalar: string, number, or reference. If a key C<$key> is +present in the array, C<exists($key)> will return true. The value for +a given key can be C<undef>, in which case C<$array{$key}> will be +C<undef> while C<$exists{$key}> will return true. This corresponds to +(C<$key>, C<undef>) being in the hash. + +Pictures help... here's the C<%ary> table: + + keys values + +------+------+ + | a | 3 | + | x | 7 | + | d | 0 | + | e | 2 | + +------+------+ + +And these conditions hold + + $ary{'a'} is true + $ary{'d'} is false + defined $ary{'d'} is true + defined $ary{'a'} is true + exists $ary{'a'} is true (perl5 only) + grep ($_ eq 'a', keys %ary) is true + +If you now say + + undef $ary{'a'} + +your table now reads: + + + keys values + +------+------+ + | a | undef| + | x | 7 | + | d | 0 | + | e | 2 | + +------+------+ + +and these conditions now hold; changes in caps: + + $ary{'a'} is FALSE + $ary{'d'} is false + defined $ary{'d'} is true + defined $ary{'a'} is FALSE + exists $ary{'a'} is true (perl5 only) + grep ($_ eq 'a', keys %ary) is true + +Notice the last two: you have an undef value, but a defined key! + +Now, consider this: + + delete $ary{'a'} + +your table now reads: + + keys values + +------+------+ + | x | 7 | + | d | 0 | + | e | 2 | + +------+------+ + +and these conditions now hold; changes in caps: + + $ary{'a'} is false + $ary{'d'} is false + defined $ary{'d'} is true + defined $ary{'a'} is false + exists $ary{'a'} is FALSE (perl5 only) + grep ($_ eq 'a', keys %ary) is FALSE + +See, the whole entry is gone! + +=head2 Why don't my tied hashes make the defined/exists distinction? + +They may or may not implement the EXISTS() and DEFINED() methods +differently. For example, there isn't the concept of undef with hashes +that are tied to DBM* files. This means the true/false tables above +will give different results when used on such a hash. It also means +that exists and defined do the same thing with a DBM* file, and what +they end up doing is not what they do with ordinary hashes. + +=head2 How do I reset an each() operation part-way through? + +Using C<keys %hash> in a scalar context returns the number of keys in +the hash I<and> resets the iterator associated with the hash. You may +need to do this if you use C<last> to exit a loop early so that when you +re-enter it, the hash iterator has been reset. + +=head2 How can I get the unique keys from two hashes? + +First you extract the keys from the hashes into arrays, and then solve +the uniquifying the array problem described above. For example: + + %seen = (); + for $element (keys(%foo), keys(%bar)) { + $seen{$element}++; + } + @uniq = keys %seen; + +Or more succinctly: + + @uniq = keys %{{%foo,%bar}}; + +Or if you really want to save space: + + %seen = (); + while (defined ($key = each %foo)) { + $seen{$key}++; + } + while (defined ($key = each %bar)) { + $seen{$key}++; + } + @uniq = keys %seen; + +=head2 How can I store a multidimensional array in a DBM file? + +Either stringify the structure yourself (no fun), or else +get the MLDBM (which uses Data::Dumper) module from CPAN and layer +it on top of either DB_File or GDBM_File. + +=head2 How can I make my hash remember the order I put elements into it? + +Use the Tie::IxHash from CPAN. + +=head2 Why does passing a subroutine an undefined element in a hash create it? + +If you say something like: + + somefunc($hash{"nonesuch key here"}); + +Then that element "autovivifies"; that is, it springs into existence +whether you store something there or not. That's because functions +get scalars passed in by reference. If somefunc() modifies C<$_[0]>, +it has to be ready to write it back into the caller's version. + +This has been fixed as of perl5.004. + +Normally, merely accessing a key's value for a nonexistent key does +I<not> cause that key to be forever there. This is different than +awk's behavior. + +=head2 How can I make the Perl equivalent of a C structure/C++ class/hash +or array of hashes or arrays? + +Use references (documented in L<perlref>). Examples of complex data +structures are given in L<perldsc> and L<perllol>. Examples of +structures and object-oriented classes are 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. + +=head1 Data: Misc + +=head2 How do I handle binary data correctly? + +Perl is binary clean, so this shouldn't be a problem. For example, +this works fine (assuming the files are found): + + if (`cat /vmunix` =~ /gzip/) { + print "Your kernel is GNU-zip enabled!\n"; + } + +On some systems, however, you have to play tedious games with "text" +versus "binary" files. See L<perlfunc/"binmode">. + +If you're concerned about 8-bit ASCII data, then see L<perllocale>. + +If you want to deal with multi-byte characters, however, there are +some gotchas. See the section on Regular Expressions. + +=head2 How do I determine whether a scalar is a number/whole/integer/float? + +Assuming that you don't care about IEEE notations like "NaN" or +"Infinity", you probably just want to use a regular expression. + + warn "has nondigits" if /\D/; + warn "not a whole number" unless /^\d+$/; + warn "not an integer" unless /^-?\d+$/; # reject +3 + warn "not an integer" unless /^[+-]?\d+$/; + warn "not a decimal number" unless /^-?\d+\.?\d*$/; # rejects .2 + warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/; + warn "not a C float" + unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/; + +Or you could check out +http://www.perl.com/CPAN/modules/by-module/String/String-Scanf-1.1.tar.gz +instead. The POSIX module (part of the standard Perl distribution) +provides the C<strtol> and C<strtod> for converting strings to double +and longs, respectively. + +=head2 How do I keep persistent data across program calls? + +For some specific applications, you can use one of the DBM modules. +See L<AnyDBM_File>. More generically, you should consult the +FreezeThaw, Storable, or Class::Eroot modules from CPAN. + +=head2 How do I print out or copy a recursive data structure? + +The Data::Dumper module on CPAN is nice for printing out +data structures, and FreezeThaw for copying them. For example: + + use FreezeThaw qw(freeze thaw); + $new = thaw freeze $old; + +Where $old can be (a reference to) any kind of data structure you'd like. +It will be deeply copied. + +=head2 How do I define methods for every class/object? + +Use the UNIVERSAL class (see L<UNIVERSAL>). + +=head2 How do I verify a credit card checksum? + +Get the Business::CreditCard module from CPAN. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod new file mode 100644 index 0000000000..c36576ff7f --- /dev/null +++ b/pod/perlfaq5.pod @@ -0,0 +1,788 @@ +=head1 NAME + +perlfaq5 - Files and Formats ($Revision: 1.19 $) + +=head1 DESCRIPTION + +This section deals with I/O and the "f" issues: filehandles, flushing, +formats, and footers. + +=head2 How do I flush/unbuffer a filehandle? Why must I do this? + +The C standard I/O library (stdio) normally buffers characters sent to +devices. This is done for efficiency reasons, so that there isn't a +system call for each byte. Any time you use print() or write() in +Perl, you go though this buffering. syswrite() circumvents stdio and +buffering. + +In most stdio implementations, the type of buffering and the size of +the buffer varies according to the type of device. Disk files are block +buffered, often with a buffer size of more than 2k. Pipes and sockets +are often buffered with a buffer size between 1/2 and 2k. Serial devices +(e.g. modems, terminals) are normally line-buffered, and stdio sends +the entire line when it gets the newline. + +Perl does not support truly unbuffered output (except insofar as you can +C<syswrite(OUT, $char, 1)>). What it does instead support is "command +buffering", in which a physical write is performed after every output +command. This isn't as hard on your system as unbuffering, but does +get the output where you want it when you want it. + +If you expect characters to get to your device when you print them there, +you'll want to autoflush its handle, as in the older: + + use FileHandle; + open(DEV, "<+/dev/tty"); # ceci n'est pas une pipe + DEV->autoflush(1); + +or the newer IO::* modules: + + use IO::Handle; + open(DEV, ">/dev/printer"); # but is this? + DEV->autoflush(1); + +or even this: + + use IO::Socket; # this one is kinda a pipe? + $sock = IO::Socket::INET->new(PeerAddr => 'www.perl.com', + PeerPort => 'http(80)', + Proto => 'tcp'); + die "$!" unless $sock; + + $sock->autoflush(); + $sock->print("GET /\015\012"); + $document = join('', $sock->getlines()); + print "DOC IS: $document\n"; + +Note the hardcoded carriage return and newline in their octal +equivalents. This is the ONLY way (currently) to assure a proper +flush on all platforms, including Macintosh. + +You can use select() and the C<$|> variable to control autoflushing +(see L<perlvar/$|> and L<perlfunc/select>): + + $oldh = select(DEV); + $| = 1; + select($oldh); + +You'll also see code that does this without a temporary variable, as in + + select((select(DEV), $| = 1)[0]); + +=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? + +Although humans have an easy time thinking of a text file as being a +sequence of lines that operates much like a stack of playing cards -- +or punch cards -- computers usually see the text file as a sequence of +bytes. In general, there's no direct way for Perl to seek to a +particular line of a file, insert text into a file, or remove text +from a file. + +(There are exceptions in special circumstances. Replacing a sequence +of bytes with another sequence of the same length is one. Another is +using the C<$DB_RECNO> array bindings as documented in L<DB_File>. +Yet another is manipulating files with all lines the same length.) + +The general solution is to create a temporary copy of the text file with +the changes you want, then copy that over the original. + + $old = $file; + $new = "$file.tmp.$$"; + $bak = "$file.bak"; + + open(OLD, "< $old") or die "can't open $old: $!"; + open(NEW, "> $new") or die "can't open $new: $!"; + + # Correct typos, preserving case + while (<OLD>) { + s/\b(p)earl\b/${1}erl/i; + (print NEW $_) or die "can't write to $new: $!"; + } + + close(OLD) or die "can't close $old: $!"; + close(NEW) or die "can't close $new: $!"; + + rename($old, $bak) or die "can't rename $old to $bak: $!"; + rename($new, $old) or die "can't rename $new to $old: $!"; + +Perl can do this sort of thing for you automatically with the C<-i> +command-line switch or the closely-related C<$^I> variable (see +L<perlrun> for more details). Note that +C<-i> may require a suffix on some non-Unix systems; see the +platform-specific documentation that came with your port. + + # Renumber a series of tests from the command line + perl -pi -e 's/(^\s+test\s+)\d+/ $1 . ++$count /e' t/op/taint.t + + # form a script + local($^I, @ARGV) = ('.bak', glob("*.c")); + while (<>) { + if ($. == 1) { + print "This line should appear at the top of each file\n"; + } + s/\b(p)earl\b/${1}erl/i; # Correct typos, preserving case + print; + close ARGV if eof; # Reset $. + } + +If you need to seek to an arbitrary line of a file that changes +infrequently, you could build up an index of byte positions of where +the line ends are in the file. If the file is large, an index of +every tenth or hundredth line end would allow you to seek and read +fairly efficiently. If the file is sorted, try the look.pl library +(part of the standard perl distribution). + +In the unique case of deleting lines at the end of a file, you +can use tell() and truncate(). The following code snippet deletes +the last line of a file without making a copy or reading the +whole file into memory: + + open (FH, "+< $file"); + while ( <FH> ) { $addr = tell(FH) unless eof(FH) } + truncate(FH, $addr); + +Error checking is left as an exercise for the reader. + +=head2 How do I count the number of lines in a file? + +One fairly efficient way is to count newlines in the file. The +following program uses a feature of tr///, as documented in L<perlop>. +If your text file doesn't end with a newline, then it's not really a +proper text file, so this may report one fewer line than you expect. + + $lines = 0; + open(FILE, $filename) or die "Can't open `$filename': $!"; + while (sysread FILE, $buffer, 4096) { + $lines += ($buffer =~ tr/\n//); + } + close FILE; + +=head2 How do I make a temporary file name? + +Use the process ID and/or the current time-value. If you need to have +many temporary files in one process, use a counter: + + BEGIN { + use IO::File; + use Fcntl; + my $temp_dir = -d '/tmp' ? '/tmp' : $ENV{TMP} || $ENV{TEMP}; + my $base_name = sprintf("%s/%d-%d-0000", $temp_dir, $$, time()); + sub temp_file { + my $fh = undef; + my $count = 0; + until (defined($fh) || $count > 100) { + $base_name =~ s/-(\d+)$/"-" . (1 + $1)/e; + $fh = IO::File->new($base_name, O_WRONLY|O_EXCL|O_CREAT, 0644) + } + if (defined($fh)) { + return ($fh, $base_name); + } else { + return (); + } + } + } + +Or you could simply use IO::Handle::new_tmpfile. + +=head2 How can I manipulate fixed-record-length files? + +The most efficient way is using pack() and unpack(). This is faster +than using substr(). Here is a sample chunk of code to break up and +put back together again some fixed-format input lines, in this case +from the output of a normal, Berkeley-style ps: + + # sample input line: + # 15158 p5 T 0:00 perl /home/tchrist/scripts/now-what + $PS_T = 'A6 A4 A7 A5 A*'; + open(PS, "ps|"); + $_ = <PS>; print; + while (<PS>) { + ($pid, $tt, $stat, $time, $command) = unpack($PS_T, $_); + for $var (qw!pid tt stat time command!) { + print "$var: <$$var>\n"; + } + print 'line=', pack($PS_T, $pid, $tt, $stat, $time, $command), + "\n"; + } + +=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? + +You may have some success with typeglobs, as we always had to use +in days of old: + + local(*FH); + +But while still supported, that isn't the best to go about getting +local filehandles. Typeglobs have their drawbacks. You may well want +to use the C<FileHandle> module, which creates new filehandles for you +(see L<FileHandle>): + + use FileHandle; + sub findme { + my $fh = FileHandle->new(); + open($fh, "</etc/hosts") or die "no /etc/hosts: $!"; + while (<$fh>) { + print if /\b127\.(0\.0\.)?1\b/; + } + # $fh automatically closes/disappears here + } + +Internally, Perl believes filehandles to be of class IO::Handle. You +may use that module directly if you'd like (see L<IO::Handle>), or +one of its more specific derived classes. + +=head2 How can I set up a footer format to be used with write()? + +There's no built-in 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? + +See L<perlform> for an swrite() function. + +=head2 How can I output my numbers with commas added? + +This one will do it for you: + + sub commify { + local $_ = shift; + 1 while s/^(-?\d+)(\d{3})/$1,$2/; + return $_; + } + + $n = 23659019423.2331; + print "GOT: ", commify($n), "\n"; + + GOT: 23,659,019,423.2331 + +You can't just: + + s/^(-?\d+)(\d{3})/$1,$2/g; + +because you have to put the comma in and then recalculate your +position. + +=head2 How can I translate tildes (~) in a filename? + +Use the E<lt>E<gt> (glob()) operator, documented in L<perlfunc>. This +requires that you have a shell installed that groks tildes, meaning +csh or tcsh or (some versions of) ksh, and thus may have portability +problems. The Glob::KGlob module (available from CPAN) gives more +portable glob functionality. + +Within Perl, you may use this directly: + + $filename =~ s{ + ^ ~ # find a leading tilde + ( # save this in $1 + [^/] # a non-slash character + * # repeated 0 or more times (0 means me) + ) + }{ + $1 + ? (getpwnam($1))[7] + : ( $ENV{HOME} || $ENV{LOGDIR} ) + }ex; + +=head2 How come when I open the file read-write it wipes it out? + +Because you're using something like this, which truncates the file and +I<then> gives you read-write access: + + open(FH, "+> /path/name"); # WRONG + +Whoops. You should instead use this, which will fail if the file +doesn't exist. + + open(FH, "+< /path/name"); # open for update + +If this is an issue, try: + + sysopen(FH, "/path/name", O_RDWR|O_CREAT, 0644); + +Error checking is left as an exercise for the reader. + +=head2 Why do I sometimes get an "Argument list too long" when I use <*>? + +The C<E<lt>E<gt>> operator performs a globbing operation (see above). +By default glob() forks csh(1) to do the actual glob expansion, but +csh can't handle more than 127 items and so gives the error message +C<Argument list too long>. People who installed tcsh as csh won't +have this problem, but their users may be surprised by it. + +To get around this, either do the glob yourself with C<Dirhandle>s and +patterns, or use a module like Glob::KGlob, one that doesn't use the +shell to do globbing. + +=head2 Is there a leak/bug in glob()? + +Due to the current implementation on some operating systems, when you +use the glob() function or its angle-bracket alias in a scalar +context, you may cause a leak and/or unpredictable behavior. It's +best therefore to use glob() only in list context. + +=head2 How can I open a file with a leading "E<gt>" or trailing blanks? + +Normally perl ignores trailing blanks in filenames, and interprets +certain leading characters (or a trailing "|") to mean something +special. To avoid this, you might want to use a routine like this. +It makes incomplete pathnames into explicit relative ones, and tacks a +trailing null byte on the name to make perl leave it alone: + + sub safe_filename { + local $_ = shift; + return m#^/# + ? "$_\0" + : "./$_\0"; + } + + $fn = safe_filename("<<<something really wicked "); + open(FH, "> $fn") or "couldn't open $fn: $!"; + +You could also use the sysopen() function (see L<perlfunc/sysopen>). + +=head2 How can I reliably rename a file? + +Well, usually you just use Perl's rename() function. But that may +not work everywhere, in particular, renaming files across file systems. +If your operating system supports a mv(1) program or its moral equivalent, +this works: + + rename($old, $new) or system("mv", $old, $new); + +It may be more compelling to use the File::Copy module instead. You +just copy to the new file to the new name (checking return values), +then delete the old one. This isn't really the same semantics as a +real rename(), though, which preserves metainformation like +permissions, timestamps, inode info, etc. + +=head2 How can I lock a file? + +Perl's built-in 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 +later), and lockf(3) if neither of the two previous system calls exists. +On some systems, it may even use a different form of native locking. +Here are some gotchas with Perl's flock(): + +=over 4 + +=item 1 + +Produces a fatal error if none of the three system calls (or their +close equivalent) exists. + +=item 2 + +lockf(3) does not provide shared locking, and requires that the +filehandle be open for writing (or appending, or read/writing). + +=item 3 + +Some versions of flock() can't lock files over a network (e.g. on NFS +file systems), so you'd need to force the use of fcntl(2) when you +build Perl. See the flock entry of L<perlfunc>, and the F<INSTALL> +file in the source distribution for information on building Perl to do +this. + +=back + +The CPAN module File::Lock offers similar functionality and (if you +have dynamic loading) won't require you to rebuild perl if your +flock() can't lock network files. + +=head2 What can't I just open(FH, ">file.lock")? + +A common bit of code B<NOT TO USE> is this: + + sleep(3) while -e "file.lock"; # PLEASE DO NOT USE + open(LCK, "> file.lock"); # THIS BROKEN CODE + +This is a classic race condition: you take two steps to do something +which must be done in one. That's why computer hardware provides an +atomic test-and-set instruction. In theory, this "ought" to work: + + sysopen(FH, "file.lock", O_WRONLY|O_EXCL|O_CREAT, 0644) + or die "can't open file.lock: $!": + +except that lamentably, file creation (and deletion) is not atomic +over NFS, so this won't work (at least, not every time) over the net. +Various schemes involving involving link() have been suggested, but +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? + +Didn't anyone ever tell you web-page hit counters were useless? + +Anyway, this is what to do: + + use Fcntl; + sysopen(FH, "numfile", O_RDWR|O_CREAT, 0644) or die "can't open numfile: $!"; + flock(FH, 2) or die "can't flock numfile: $!"; + $num = <FH> || 0; + seek(FH, 0, 0) or die "can't rewind numfile: $!"; + truncate(FH, 0) or die "can't truncate numfile: $!"; + (print FH $num+1, "\n") or die "can't write numfile: $!"; + # DO NOT UNLOCK THIS UNTIL YOU CLOSE + close FH or die "can't close numfile: $!"; + +Here's a much better web-page hit counter: + + $hits = int( (time() - 850_000_000) / rand(1_000) ); + +If the count doesn't impress your friends, then the code might. :-) + +=head2 How do I randomly update a binary file? + +If you're just trying to patch a binary, in many cases something as +simple as this works: + + perl -i -pe 's{window manager}{window mangler}g' /usr/bin/emacs + +However, if you have fixed sized records, then you might do something more +like this: + + $RECSIZE = 220; # size of record, in bytes + $recno = 37; # which record to update + open(FH, "+<somewhere") || die "can't update somewhere: $!"; + seek(FH, $recno * $RECSIZE, 0); + read(FH, $record, $RECSIZE) == $RECSIZE || die "can't read record $recno: $!"; + # munge the record + seek(FH, $recno * $RECSIZE, 0); + print FH $record; + close FH; + +Locking and error checking are left as an exercise for the reader. +Don't forget them, or you'll be quite sorry. + +Don't forget to set binmode() under DOS-like platforms when operating +on files that have anything other than straight text in them. See the +docs on open() and on binmode() for more details. + +=head2 How do I get a file's timestamp in perl? + +If you want to retrieve the time at which the file was last read, +written, or had its meta-data (owner, etc) changed, you use the B<-M>, +B<-A>, or B<-C> filetest operations as documented in L<perlfunc>. These +retrieve the age of the file (measured against the start-time of your +program) in days as a floating point number. To retrieve the "raw" +time in seconds since the epoch, you would call the stat function, +then use localtime(), gmtime(), or POSIX::strftime() to convert this +into human-readable form. + +Here's an example: + + $write_secs = (stat($file))[9]; + print "file $file updated at ", scalar(localtime($file)), "\n"; + +If you prefer something more legible, use the File::stat module +(part of the standard distribution in version 5.004 and later): + + use File::stat; + use Time::localtime; + $date_string = ctime(stat($file)->mtime); + print "file $file updated at $date_string\n"; + +Error checking is left as an exercise for the reader. + +=head2 How do I set a file's timestamp in perl? + +You use the utime() function documented in L<perlfunc/utime>. +By way of example, here's a little program that copies the +read and write times from its first argument to all the rest +of them. + + if (@ARGV < 2) { + die "usage: cptimes timestamp_file other_files ...\n"; + } + $timestamp = shift; + ($atime, $mtime) = (stat($timestamp))[8,9]; + utime $atime, $mtime, @ARGV; + +Error checking is left as an exercise for the reader. + +Note that utime() currently doesn't work correctly with Win95/NT +ports. A bug has been reported. Check it carefully before using +it on those platforms. + +=head2 How do I print to more than one file at once? + +If you only have to do this once, you can do this: + + for $fh (FH1, FH2, FH3) { print $fh "whatever\n" } + +To connect up to one filehandle to several output filehandles, it's +easiest to use the tee(1) program if you have it, and let it take care +of the multiplexing: + + open (FH, "| tee file1 file2 file3"); + +Otherwise you'll have to write your own multiplexing print function -- +or your own tee program -- or use Tom Christiansen's, at +http://www.perl.com/CPAN/authors/id/TOMC/scripts/tct.gz, which is +written in Perl. + +In theory a IO::Tee class could be written, but to date we haven't +seen such. + +=head2 How can I read in a file 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">, +for instance, gets treated as two paragraphs and not three), or +C<"\n\n"> to accept empty paragraphs. + +=head2 How can I read a single character from a file? From the keyboard? + +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 +the Term::ReadKey module from CPAN, or use the sample code in +L<perlfunc/getc>. + +If your system supports POSIX, you can use the following code, which +you'll note turns off echo processing as well. + + #!/usr/bin/perl -w + use strict; + $| = 1; + for (1..4) { + my $got; + print "gimme: "; + $got = getone(); + print "--> $got\n"; + } + exit; + + BEGIN { + use POSIX qw(:termios_h); + + my ($term, $oterm, $echo, $noecho, $fd_stdin); + + $fd_stdin = fileno(STDIN); + + $term = POSIX::Termios->new(); + $term->getattr($fd_stdin); + $oterm = $term->getlflag(); + + $echo = ECHO | ECHOK | ICANON; + $noecho = $oterm & ~$echo; + + sub cbreak { + $term->setlflag($noecho); + $term->setcc(VTIME, 1); + $term->setattr($fd_stdin, TCSANOW); + } + + sub cooked { + $term->setlflag($oterm); + $term->setcc(VTIME, 0); + $term->setattr($fd_stdin, TCSANOW); + } + + sub getone { + my $key = ''; + cbreak(); + sysread(STDIN, $key, 1); + cooked(); + return $key; + } + + } + + END { cooked() } + +The Term::ReadKey module from CPAN may be easier to use: + + use Term::ReadKey; + open(TTY, "</dev/tty"); + print "Gimme a char: "; + ReadMode "raw"; + $key = ReadKey 0, *TTY; + ReadMode "normal"; + printf "\nYou said %s, char number %03d\n", + $key, ord $key; + +For DOS systems, Dan Carson <dbc@tc.fluke.COM> reports the following: + +To put the PC in "raw" mode, use ioctl with some magic numbers gleaned +from msdos.c (Perl source file) and Ralf Brown's interrupt list (comes +across the net every so often): + + $old_ioctl = ioctl(STDIN,0,0); # Gets device info + $old_ioctl &= 0xff; + ioctl(STDIN,1,$old_ioctl | 32); # Writes it back, setting bit 5 + +Then to read a single character: + + sysread(STDIN,$c,1); # Read a single character + +And to put the PC back to "cooked" mode: + + ioctl(STDIN,1,$old_ioctl); # Sets it back to cooked mode. + +So now you have $c. If C<ord($c) == 0>, you have a two byte code, which +means you hit a special key. Read another byte with C<sysread(STDIN,$c,1)>, +and that value tells you what combination it was according to this +table: + + # PC 2-byte keycodes = ^@ + the following: + + # HEX KEYS + # --- ---- + # 0F SHF TAB + # 10-19 ALT QWERTYUIOP + # 1E-26 ALT ASDFGHJKL + # 2C-32 ALT ZXCVBNM + # 3B-44 F1-F10 + # 47-49 HOME,UP,PgUp + # 4B LEFT + # 4D RIGHT + # 4F-53 END,DOWN,PgDn,Ins,Del + # 54-5D SHF F1-F10 + # 5E-67 CTR F1-F10 + # 68-71 ALT F1-F10 + # 73-77 CTR LEFT,RIGHT,END,PgDn,HOME + # 78-83 ALT 1234567890-= + # 84 CTR PgUp + +This is all trial and error I did a long time ago, I hope I'm reading the +file that worked. + +=head2 How can I tell if there's a character waiting on a filehandle? + +You should check out the Frequently Asked Questions list in +comp.unix.* for things like this: the answer is essentially the same. +It's very system dependent. Here's one solution that works on BSD +systems: + + sub key_ready { + my($rin, $nfd); + vec($rin, fileno(STDIN), 1) = 1; + return $nfd = select($rin,undef,undef,0); + } + +You should look into getting the Term::ReadKey extension from CPAN. + +=head2 How do I open a file without blocking? + +You need to use the O_NDELAY or O_NONBLOCK flag from the Fcntl module +in conjunction with sysopen(): + + use Fcntl; + sysopen(FH, "/tmp/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644) + or die "can't open /tmp/somefile: $!": + +=head2 How do I create a file only if it doesn't exist? + +You need to use the O_CREAT and O_EXCL flags from the Fcntl module in +conjunction with sysopen(): + + use Fcntl; + sysopen(FH, "/tmp/somefile", O_WRONLY|O_EXCL|O_CREAT, 0644) + or die "can't open /tmp/somefile: $!": + +Be warned that neither creation nor deletion of files is guaranteed to +be an atomic operation over NFS. That is, two processes might both +successful create or unlink the same file! + +=head2 How do I do a C<tail -f> in perl? + +First try + + seek(GWFILE, 0, 1); + +The statement C<seek(GWFILE, 0, 1)> doesn't change the current position, +but it does clear the end-of-file condition on the handle, so that the +next <GWFILE> makes Perl try again to read something. + +If that doesn't work (it relies on features of your stdio implementation), +then you need something more like this: + + for (;;) { + for ($curpos = tell(GWFILE); <GWFILE>; $curpos = tell(GWFILE)) { + # search for some stuff and put it into files + } + # sleep for a while + seek(GWFILE, $curpos, 0); # seek to where we had been + } + +If this still doesn't work, look into the POSIX module. POSIX defines +the clearerr() method, which can remove the end of file condition on a +filehandle. The method: read until end of file, clearerr(), read some +more. Lather, rinse, repeat. + +=head2 How do I dup() a filehandle in Perl? + +If you check L<perlfunc/open>, you'll see that several of the ways +to call open() should do the trick. For example: + + open(LOG, ">>/tmp/logfile"); + open(STDERR, ">&LOG"); + +Or even with a literal numeric descriptor: + + $fd = $ENV{MHCONTEXTFD}; + open(MHCONTEXT, "<&=$fd"); # like fdopen(3S) + +Error checking has been left as an exercise for the reader. + +=head2 How do I close a file descriptor by number? + +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 +numeric descriptor, as with MHCONTEXT above. But if you really have +to, you may be able to do this: + + require 'sys/syscall.ph'; + $rc = syscall(&SYS_close, $fd + 0); # must force numeric + die "can't sysclose $fd: $!" unless $rc == -1; + +=head2 Why can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` work? + +Whoops! You just put a tab and a formfeed into that filename! +Remember that within double quoted strings ("like\this"), the +backslash is an escape character. The full list of these is in +L<perlop/Quote and Quote-like Operators>. Unsurprisingly, you don't +have a file called "c:(tab)emp(formfeed)oo" or +"c:(tab)emp(formfeed)oo.exe" on your DOS filesystem. + +Either single-quote your strings, or (preferably) use forward slashes. +Since all DOS and Windows versions since something like MS-DOS 2.0 or so +have treated C</> and C<\> the same in a path, you might as well use the +one that doesn't clash with Perl -- or the POSIX shell, ANSI C and C++, +awk, Tcl, Java, or Python, just to mention a few. + +=head2 Why doesn't glob("*.*") get all the files? + +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) +files. + +=head2 Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl? + +This is elaborately and painstakingly described in the "Far More Than +You Every Wanted To Know" in +http://www.perl.com/CPAN/doc/FMTEYEWTK/file-dir-perms . + +The executive summary: learn how your filesystem works. The +permissions on a file say what can happen to the data in that file. +The permissions on a directory say what can happen to the list of +files in that directory. If you delete a file, you're removing its +name from the directory (so the operation depends on the permissions +of the directory, not of the file). If you try to write to the file, +the permissions of the file govern whether you're allowed to. + +=head2 How do I select a random line from a file? + +Here's an algorithm from the Camel Book: + + srand; + rand($.) < 1 && ($line = $_) while <>; + +This has a significant advantage in space over reading the whole +file in. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlfaq6.pod b/pod/perlfaq6.pod new file mode 100644 index 0000000000..589d89e495 --- /dev/null +++ b/pod/perlfaq6.pod @@ -0,0 +1,580 @@ +=head1 NAME + +perlfaq6 - Regexps ($Revision: 1.14 $) + +=head1 DESCRIPTION + +This section is surprisingly small because the rest of the FAQ is +littered with answers involving regular expressions. For example, +decoding a URL and checking whether something is a number are handled +with regular expressions, but those answers are found elsewhere in +this document (in the section on Data and the Networking one on +networking, to be precise). + +=head2 How can I hope to use regular expressions without creating illegible and unmaintainable code? + +Three techniques can make regular expressions maintainable and +understandable. + +=over 4 + +=item Comments Outside the Regexp + +Describe what you're doing and how you're doing it, using normal Perl +comments. + + # turn the line into the first word, a colon, and the + # number of characters on the rest of the line + s/^(\w+)(.*)/ lc($1) . ":" . length($2) /ge; + +=item Comments Inside the Regexp + +The C</x> modifier causes whitespace to be ignored in a regexp pattern +(except in a character class), and also allows you to use normal +comments there, too. As you can imagine, whitespace and comments help +a lot. + +C</x> lets you turn this: + + s{<(?:[^>'"]*|".*?"|'.*?')+>}{}gs; + +into this: + + s{ < # opening angle bracket + (?: # Non-backreffing grouping paren + [^>'"] * # 0 or more things that are neither > nor ' nor " + | # or else + ".*?" # a section between double quotes (stingy match) + | # or else + '.*?' # a section between single quotes (stingy match) + ) + # all occurring one or more times + > # closing angle bracket + }{}gsx; # replace with nothing, i.e. delete + +It's still not quite so clear as prose, but it is very useful for +describing the meaning of each part of the pattern. + +=item Different Delimiters + +While we normally think of patterns as being delimited with C</> +characters, they can be delimited by almost any character. L<perlre> +describes this. For example, the C<s///> above uses braces as +delimiters. Selecting another delimiter can avoid quoting the +delimiter within the pattern: + + s/\/usr\/local/\/usr\/share/g; # bad delimiter choice + s#/usr/local#/usr/share#g; # better + +=back + +=head2 I'm having trouble matching over more than one line. What's wrong? + +Either you don't have newlines in your string, or you aren't using the +correct modifier(s) on your pattern. + +There are many ways to get multiline data into a string. If you want +it to happen automatically while reading input, you'll want to set $/ +(probably to '' for paragraphs or C<undef> for the whole file) to +allow you to read more than one line at a time. + +Read L<perlre> to help you decide which of C</s> and C</m> (or both) +you might want to use: C</s> allows dot to include newline, and C</m> +allows caret and dollar to match next to a newline, not just at the +end of the string. You do need to make sure that you've actually +got a multiline string in there. + +For example, this program detects duplicate words, even when they span +line breaks (but not paragraph ones). For this example, we don't need +C</s> because we aren't using dot in a regular expression that we want +to cross line boundaries. Neither do we need C</m> because we aren't +wanting caret or dollar to match at any point inside the record next +to newlines. But it's imperative that $/ be set to something other +than the default, or else we won't actually ever have a multiline +record read in. + + $/ = ''; # read in more whole paragraph, not just one line + while ( <> ) { + while ( /\b(\w\S+)(\s+\1)+\b/gi ) { + print "Duplicate $1 at paragraph $.\n"; + } + } + +Here's code that finds sentences that begin with "From " (which would +be mangled by many mailers): + + $/ = ''; # read in more whole paragraph, not just one line + while ( <> ) { + while ( /^From /gm ) { # /m makes ^ match next to \n + print "leading from in paragraph $.\n"; + } + } + +Here's code that finds everything between START and END in a paragraph: + + undef $/; # read in whole file, not just one line or paragraph + while ( <> ) { + while ( /START(.*?)END/sm ) { # /s makes . cross line boundaries + print "$1\n"; + } + } + +=head2 How can I pull out lines between two patterns that are themselves on different lines? + +You can use Perl's somewhat exotic C<..> operator (documented in +L<perlop>): + + perl -ne 'print if /START/ .. /END/' file1 file2 ... + +If you wanted text and not lines, you would use + + perl -0777 -pe 'print "$1\n" while /START(.*?)END/gs' file1 file2 ... + +But if you want nested occurrences of C<START> through C<END>, you'll +run up against the problem described in the question in this section +on matching balanced text. + +=head2 I put a regular expression into $/ but it didn't work. What's wrong? + +$/ must be a string, not a regular expression. Awk has to be better +for something. :-) + +Actually, you could do this if you don't mind reading the whole file into + + undef $/; + @records = split /your_pattern/, <FH>; + +=head2 How do I substitute case insensitively on the LHS, but preserving case on the RHS? + +It depends on what you mean by "preserving case". The following +script makes the substitution have the same case, letter by letter, as +the original. If the substitution has more characters than the string +being substituted, the case of the last character is used for the rest +of the substitution. + + # Original by Nathan Torkington, massaged by Jeffrey Friedl + # + sub preserve_case($$) + { + my ($old, $new) = @_; + my ($state) = 0; # 0 = no change; 1 = lc; 2 = uc + my ($i, $oldlen, $newlen, $c) = (0, length($old), length($new)); + my ($len) = $oldlen < $newlen ? $oldlen : $newlen; + + for ($i = 0; $i < $len; $i++) { + if ($c = substr($old, $i, 1), $c =~ /[\W\d_]/) { + $state = 0; + } elsif (lc $c eq $c) { + substr($new, $i, 1) = lc(substr($new, $i, 1)); + $state = 1; + } else { + substr($new, $i, 1) = uc(substr($new, $i, 1)); + $state = 2; + } + } + # finish up with any remaining new (for when new is longer than old) + if ($newlen > $oldlen) { + if ($state == 1) { + substr($new, $oldlen) = lc(substr($new, $oldlen)); + } elsif ($state == 2) { + substr($new, $oldlen) = uc(substr($new, $oldlen)); + } + } + return $new; + } + + $a = "this is a TEsT case"; + $a =~ s/(test)/preserve_case($1, "success")/gie; + print "$a\n"; + +This prints: + + this is a SUcCESS case + +=head2 How can I make C<\w> match accented characters? + +See L<perllocale>. + +=head2 How can I match a locale-smart version of C</[a-zA-Z]/>? + +One alphabetic character would be C</[^\W\d_]/>, no matter what locale +you're in. Non-alphabetics would be C</[\W\d_]/> (assuming you don't +consider an underscore a letter). + +=head2 How can I quote a variable to use in a regexp? + +The Perl parser will expand $variable and @variable references in +regular expressions unless the delimiter is a single quote. Remember, +too, that the right-hand side of a C<s///> substitution is considered +a double-quoted string (see L<perlop> for more details). Remember +also that any regexp special characters will be acted on unless you +precede the substitution with \Q. Here's an example: + + $string = "to die?"; + $lhs = "die?"; + $rhs = "sleep no more"; + + $string =~ s/\Q$lhs/$rhs/; + # $string is now "to sleep no more" + +Without the \Q, the regexp would also spuriously match "di". + +=head2 What is C</o> really for? + +Using a variable in a regular expression match forces a re-evaluation +(and perhaps recompilation) each time through. The C</o> modifier +locks in the regexp 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. + +Use of C</o> is irrelevant unless variable interpolation is used in +the pattern, and if so, the regexp engine will neither know nor care +whether the variables change after the pattern is evaluated the I<very +first> time. + +C</o> 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 regexp to notice if they do. + +For example, here's a "paragrep" program: + + $/ = ''; # paragraph mode + $pat = shift; + while (<>) { + print if /$pat/o; + } + +=head2 How do I use a regular expression to strip C style comments from a file? + +While this actually can be done, it's much harder than you'd think. +For example, this one-liner + + perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c + +will work in many but not all cases. You see, it's too simple-minded for +certain kinds of C programs, in particular, those with what appear to be +comments in quoted strings. For that, you'd need something like this, +created by Jeffrey Friedl: + + $/ = undef; + $_ = <>; + s#/\*[^*]*\*+([^/*][^*]*\*+)*/|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|\n+|.[^/"'\\]*)#$2#g; + print; + +This could, of course, be more legibly written with the C</x> modifier, adding +whitespace and comments. + +=head2 Can I use Perl regular expressions to match balanced text? + +Although Perl regular expressions are more powerful than "mathematical" +regular expressions, because they feature conveniences like backreferences +(C<\1> and its ilk), they still aren't powerful enough. You still need +to use non-regexp techniques to parse balanced text, such as the text +enclosed between matching parentheses or braces, for example. + +An elaborate subroutine (for 7-bit ASCII only) to pull out balanced +and possibly nested single chars, like C<`> and C<'>, C<{> and C<}>, +or C<(> and C<)> can be found in +http://www.perl.com/CPAN/authors/id/TOMC/scripts/pull_quotes.gz . + +The C::Scan module from CPAN contains such subs for internal usage, +but they are undocumented. + +=head2 What does it mean that regexps are greedy? How can I get around it? + +Most people mean that greedy regexps match as much as they can. +Technically speaking, it's actually the quantifiers (C<?>, C<*>, C<+>, +C<{}>) that are greedy rather than the whole pattern; Perl prefers local +greed and immediate gratification to overall greed. To get non-greedy +versions of the same quantifiers, use (C<??>, C<*?>, C<+?>, C<{}?>). + +An example: + + $s1 = $s2 = "I am very very cold"; + $s1 =~ s/ve.*y //; # I am cold + $s2 =~ s/ve.*?y //; # I am very cold + +Notice how the second substitution stopped matching as soon as it +encountered "y ". The C<*?> quantifier effectively tells the regular +expression engine to find a match as quickly as possible and pass +control on to whatever is next in line, like you would if you were +playing hot potato. + +=head2 How do I process each word on each line? + +Use the split function: + + while (<>) { + foreach $word ( split ) { + # do something with $word here + } + } + +Note that this isn't really a word in the English sense; it's just +chunks of consecutive non-whitespace characters. + +To work with only alphanumeric sequences, you might consider + + while (<>) { + foreach $word (m/(\w+)/g) { + # do something with $word here + } + } + +=head2 How can I print out a word-frequency or line-frequency summary? + +To do this, you have to parse out each word in the input stream. We'll +pretend that by word you mean chunk of alphabetics, hyphens, or +apostrophes, rather than the non-whitespace chunk idea of a word given +in the previous question: + + while (<>) { + while ( /(\b[^\W_\d][\w'-]+\b)/g ) { # misses "`sheep'" + $seen{$1}++; + } + } + while ( ($word, $count) = each %seen ) { + print "$count $word\n"; + } + +If you wanted to do the same thing for lines, you wouldn't need a +regular expression: + + while (<>) { + $seen{$_}++; + } + while ( ($line, $count) = each %seen ) { + print "$count $line"; + } + +If you want these output in a sorted order, see the section on Hashes. + +=head2 How can I do approximate matching? + +See the module String::Approx available from CPAN. + +=head2 How do I efficiently match many regular expressions at once? + +The following is super-inefficient: + + while (<FH>) { + foreach $pat (@patterns) { + if ( /$pat/ ) { + # do something + } + } + } + +Instead, you either need to use one of the experimental Regexp extension +modules from CPAN (which might well be overkill for your purposes), +or else put together something like this, inspired from a routine +in Jeffrey Friedl's book: + + sub _bm_build { + my $condition = shift; + my @regexp = @_; # this MUST not be local(); need my() + my $expr = join $condition => map { "m/\$regexp[$_]/o" } (0..$#regexp); + my $match_func = eval "sub { $expr }"; + die if $@; # propagate $@; this shouldn't happen! + return $match_func; + } + + sub bm_and { _bm_build('&&', @_) } + sub bm_or { _bm_build('||', @_) } + + $f1 = bm_and qw{ + xterm + (?i)window + }; + + $f2 = bm_or qw{ + \b[Ff]ree\b + \bBSD\B + (?i)sys(tem)?\s*[V5]\b + }; + + # feed me /etc/termcap, prolly + while ( <> ) { + print "1: $_" if &$f1; + print "2: $_" if &$f2; + } + +=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 behaviour of all the regexp 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". + +=head2 Why does using $&, $`, or $' slow my program down? + +Because once Perl sees that you need one of these variables anywhere +in the program, it has to provide them on each and every pattern +match. The same mechanism that handles these provides for the use of +$1, $2, etc., so you pay the same price for each regexp that contains +capturing parentheses. But if you never use $&, etc., in your script, +then regexps I<without> capturing parentheses won't be penalized. So +avoid $&, $', and $` if you can, but if you can't (and some algorithms +really appreciate them), once you've used them once, use them at will, +because you've already paid the price. + +=head2 What good is C<\G> in a regular expression? + +The notation C<\G> is used in a match or substitution in conjunction the +C</g> modifier (and ignored if there's no C</g>) to anchor the regular +expression to the point just past where the last match occurred, i.e. the +pos() point. + +For example, suppose you had a line of text quoted in standard mail +and Usenet notation, (that is, with leading C<E<gt>> characters), and +you want change each leading C<E<gt>> into a corresponding C<:>. You +could do so in this way: + + s/^(>+)/':' x length($1)/gem; + +Or, using C<\G>, the much simpler (and faster): + + s/\G>/:/g; + +A more sophisticated use might involve a tokenizer. The following +lex-like example is courtesy of Jeffrey Friedl. It did not work in +5.003 due to bugs in that release, but does work in 5.004 or better: + + while (<>) { + chomp; + PARSER: { + m/ \G( \d+\b )/gx && do { print "number: $1\n"; redo; }; + m/ \G( \w+ )/gx && do { print "word: $1\n"; redo; }; + m/ \G( \s+ )/gx && do { print "space: $1\n"; redo; }; + m/ \G( [^\w\d]+ )/gx && do { print "other: $1\n"; redo; }; + } + } + +Of course, that could have been written as + + while (<>) { + chomp; + PARSER: { + if ( /\G( \d+\b )/gx { + print "number: $1\n"; + redo PARSER; + } + if ( /\G( \w+ )/gx { + print "word: $1\n"; + redo PARSER; + } + if ( /\G( \s+ )/gx { + print "space: $1\n"; + redo PARSER; + } + if ( /\G( [^\w\d]+ )/gx { + print "other: $1\n"; + redo PARSER; + } + } + } + +But then you lose the vertical alignment of the regular expressions. + +=head2 Are Perl regexps DFAs or NFAs? Are they POSIX compliant? + +While it's true that Perl's regular expressions resemble the DFAs +(deterministic finite automata) of the egrep(1) program, they are in +fact implemented as NFAs (non-deterministic finite automata) to allow +backtracking and backreferencing. And they aren't POSIX-style either, +because those guarantee worst-case behavior for all cases. (It seems +that some people prefer guarantees of consistency, even when what's +guaranteed is slowness.) See the book "Mastering Regular Expressions" +(from O'Reilly) by Jeffrey Friedl for all the details you could ever +hope to know on these matters (a full citation appears in +L<perlfaq2>). + +=head2 What's wrong with using grep or map in a void context? + +Strictly speaking, nothing. Stylistically speaking, it's not a good +way to write maintainable code. That's because you're using these +constructs not for their return values but rather for their +side-effects, and side-effects can be mystifying. There's no void +grep() that's not better written as a C<for> (well, C<foreach>, +technically) loop. + +=head2 How can I match strings with multi-byte characters? + +This is hard, and there's no good way. Perl does not directly support +wide characters. It pretends that a byte and a character are +synonymous. The following set of approaches was offered by Jeffrey +Friedl, whose article in issue #5 of The Perl Journal talks about this +very matter. + +Let's suppose you have some weird Martian encoding where pairs of ASCII +uppercase letters encode single Martian letters (i.e. the two bytes +"CV" make a single Martian letter, as do the two bytes "SG", "VS", +"XX", etc.). Other bytes represent single characters, just like ASCII. + +So, the string of Martian "I am CVSGXX!" uses 12 bytes to encode the nine +characters 'I', ' ', 'a', 'm', ' ', 'CV', 'SG', 'XX', '!'. + +Now, say you want to search for the single character C</GX/>. Perl +doesn't know about Martian, so it'll find the two bytes "GX" in the +"I am CVSGXX!" string, even though that character isn't there: it just +looks like it is because "SG" is next to "XX", but there's no real "GX". +This is a big problem. + +Here are a few ways, all painful, to deal with it: + + $martian =~ s/([A-Z][A-Z])/ $1 /g; # Make sure adjacent ``maritan'' bytes + # are no longer adjacent. + print "found GX!\n" if $martian =~ /GX/; + +Or like this: + + @chars = $martian =~ m/([A-Z][A-Z]|[^A-Z])/g; + # above is conceptually similar to: @chars = $text =~ m/(.)/g; + # + foreach $char (@chars) { + print "found GX!\n", last if $char eq 'GX'; + } + +Or like this: + + while ($martian =~ m/\G([A-Z][A-Z]|.)/gs) { # \G probably unneeded + print "found GX!\n", last if $1 eq 'GX'; + } + +Or like this: + + die "sorry, Perl doesn't (yet) have Martian support )-:\n"; + +In addition, a sample program which converts half-width to full-width +katakana (in Shift-JIS or EUC encoding) is available from CPAN as + +=for Tom make it so + +There are many double- (and multi-) byte encodings commonly used these +days. Some versions of these have 1-, 2-, 3-, and 4-byte characters, +all mixed. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod new file mode 100644 index 0000000000..14bfc678fc --- /dev/null +++ b/pod/perlfaq7.pod @@ -0,0 +1,675 @@ +=head1 NAME + +perlfaq7 - Perl Language Issues ($Revision: 1.15 $) + +=head1 DESCRIPTION + +This section deals with general Perl language issues that don't +clearly fit into any of the other sections. + +=head2 Can I get a BNF/yacc/RE for the Perl language? + +No, in the words of Chaim Frenkel: "Perl's grammar can not be reduced +to BNF. The work of parsing perl is distributed between yacc, the +lexer, smoke and mirrors." + +=head2 What are all these $@%* punctuation signs, and how do I know when to use them? + +They are type specifiers, as detailed in L<perldata>: + + $ for scalar values (number, string or reference) + @ for arrays + % for hashes (associative arrays) + * for all types of that symbol name. In version 4 you used them like + pointers, but in modern perls you can just use references. + +While there are a few places where you don't actually need these type +specifiers, you should always use them. + +A couple of others that you're likely to encounter that aren't +really type specifiers are: + + <> are used for inputting a record from a filehandle. + \ takes a reference to something. + +Note that E<lt>FILEE<gt> is I<neither> the type specifier for files +nor the name of the handle. It is the C<E<lt>E<gt>> operator applied +to the handle FILE. It reads one line (well, record - see +L<perlvar/$/>) from the handle FILE in scalar context, or I<all> lines +in list context. When performing open, close, or any other operation +besides C<E<lt>E<gt>> on files, or even talking about the handle, do +I<not> use the brackets. These are correct: C<eof(FH)>, C<seek(FH, 0, +2)> and "copying from STDIN to FILE". + +=head2 Do I always/never have to quote my strings or use semicolons and commas? + +Normally, a bareword doesn't need to be quoted, but in most cases +probably should be (and must be under C<use strict>). But a hash key +consisting of a simple word (that isn't the name of a defined +subroutine) and the left-hand operand to the C<=E<gt>> operator both +count as though they were quoted: + + This is like this + ------------ --------------- + $foo{line} $foo{"line"} + bar => stuff "bar" => stuff + +The final semicolon in a block is optional, as is the final comma in a +list. Good style (see L<perlstyle>) says to put them in except for +one-liners: + + if ($whoops) { exit 1 } + @nums = (1, 2, 3); + + if ($whoops) { + exit 1; + } + @lines = ( + "There Beren came from mountains cold", + "And lost he wandered under leaves", + ); + +=head2 How do I skip some return values? + +One way is to treat the return values as a list and index into it: + + $dir = (getpwnam($user))[7]; + +Another way is to use undef as an element on the left-hand-side: + + ($dev, $ino, undef, undef, $uid, $gid) = stat($file); + +=head2 How do I temporarily block warnings? + +The C<$^W> variable (documented in L<perlvar>) controls +runtime warnings for a block: + + { + local $^W = 0; # temporarily turn off warnings + $a = $b + $c; # I know these might be undef + } + +Note that like all the punctuation variables, you cannot currently +use my() on C<$^W>, only local(). + +A new C<use warnings> pragma is in the works to provide finer control +over all this. The curious should check the perl5-porters mailing list +archives for details. + +=head2 What's an extension? + +A way of calling compiled C code from Perl. Reading L<perlxstut> +is a good place to learn more about extensions. + +=head2 Why do Perl operators have different precedence than C operators? + +Actually, they don't. All C operators that Perl copies have the same +precedence in Perl as they do in C. The problem is with operators that C +doesn't have, especially functions that give a list context to everything +on their right, eg print, chmod, exec, and so on. Such functions are +called "list operators" and appear as such in the precedence table in +L<perlop>. + +A common mistake is to write: + + unlink $file || die "snafu"; + +This gets interpreted as: + + unlink ($file || die "snafu"); + +To avoid this problem, either put in extra parentheses or use the +super low precedence C<or> operator: + + (unlink $file) || die "snafu"; + unlink $file or die "snafu"; + +The "English" operators (C<and>, C<or>, C<xor>, and C<not>) +deliberately have precedence lower than that of list operators for +just such situations as the one above. + +Another operator with surprising precedence is exponentiation. It +binds more tightly even than unary minus, making C<-2**2> product a +negative not a positive four. It is also right-associating, meaning +that C<2**3**2> is two raised to the ninth power, not eight squared. + +=head2 How do I declare/create a structure? + +In general, you don't "declare" a structure. Just use a (probably +anonymous) hash reference. See L<perlref> and L<perldsc> for details. +Here's an example: + + $person = {}; # new anonymous hash + $person->{AGE} = 24; # set field AGE to 24 + $person->{NAME} = "Nat"; # set field NAME to "Nat" + +If you're looking for something a bit more rigorous, try L<perltoot>. + +=head2 How do I create a module? + +A module is a package that lives in a file of the same name. For +example, the Hello::There module would live in Hello/There.pm. For +details, read L<perlmod>. You'll also find L<Exporter> helpful. If +you're writing a C or mixed-language module with both C and Perl, then +you should study L<perlxstut>. + +Here's a convenient template you might wish you use when starting your +own module. Make sure to change the names appropriately. + + package Some::Module; # assumes Some/Module.pm + + use strict; + + BEGIN { + use Exporter (); + use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); + + ## set the version for version checking; uncomment to use + ## $VERSION = 1.00; + + # if using RCS/CVS, this next line may be preferred, + # but beware two-digit versions. + $VERSION = do{my@r=q$Revision: 1.15 $=~/\d+/g;sprintf '%d.'.'%02d'x$#r,@r}; + + @ISA = qw(Exporter); + @EXPORT = qw(&func1 &func2 &func3); + %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ], + + # your exported package globals go here, + # as well as any optionally exported functions + @EXPORT_OK = qw($Var1 %Hashit); + } + use vars @EXPORT_OK; + + # non-exported package globals go here + use vars qw( @more $stuff ); + + # initialize package globals, first exported ones + $Var1 = ''; + %Hashit = (); + + # then the others (which are still accessible as $Some::Module::stuff) + $stuff = ''; + @more = (); + + # all file-scoped lexicals must be created before + # the functions below that use them. + + # file-private lexicals go here + my $priv_var = ''; + my %secret_hash = (); + + # here's a file-private function as a closure, + # callable as &$priv_func; it cannot be prototyped. + my $priv_func = sub { + # stuff goes here. + }; + + # make all your functions, whether exported or not; + # remember to put something interesting in the {} stubs + sub func1 {} # no prototype + sub func2() {} # proto'd void + sub func3($$) {} # proto'd to 2 scalars + + # this one isn't exported, but could be called! + sub func4(\%) {} # proto'd to 1 hash ref + + END { } # module clean-up code here (global destructor) + + 1; # modules must return true + +=head2 How do I create a class? + +See L<perltoot> for an introduction to classes and objects, as well as +L<perlobj> and L<perlbot>. + +=head2 How can I tell if a variable is tainted? + +See L<perlsec/"Laundering and Detecting Tainted Data">. Here's an +example (which doesn't use any system calls, because the kill() +is given no processes to signal): + + sub is_tainted { + return ! eval { join('',@_), kill 0; 1; }; + } + +This is not C<-w> clean, however. There is no C<-w> clean way to +detect taintedness - take this as a hint that you should untaint +all possibly-tainted data. + +=head2 What's a closure? + +Closures are documented in L<perlref>. + +I<Closure> is a computer science term with a precise but +hard-to-explain meaning. Closures are implemented in Perl as anonymous +subroutines with lasting references to lexical variables outside their +own scopes. These lexicals magically refer to the variables that were +around when the subroutine was defined (deep binding). + +Closures make sense in any programming language where you can have the +return value of a function be itself a function, as you can in Perl. +Note that some languages provide anonymous functions but are not +capable of providing proper closures; the Python language, for +example. For more information on closures, check out any textbook on +functional programming. Scheme is a language that not only supports +but encourages closures. + +Here's a classic function-generating function: + + sub add_function_generator { + return sub { shift + shift }; + } + + $add_sub = add_function_generator(); + $sum = &$add_sub(4,5); # $sum is 9 now. + +The closure works as a I<function template> with some customization +slots left out to be filled later. The anonymous subroutine returned +by add_function_generator() isn't technically a closure because it +refers to no lexicals outside its own scope. + +Contrast this with the following make_adder() function, in which the +returned anonymous function contains a reference to a lexical variable +outside the scope of that function itself. Such a reference requires +that Perl return a proper closure, thus locking in for all time the +value that the lexical had when the function was created. + + sub make_adder { + my $addpiece = shift; + return sub { shift + $addpiece }; + } + + $f1 = make_adder(20); + $f2 = make_adder(555); + +Now C<&$f1($n)> is always 20 plus whatever $n you pass in, whereas +C<&$f2($n)> is always 555 plus whatever $n you pass in. The $addpiece +in the closure sticks around. + +Closures are often used for less esoteric purposes. For example, when +you want to pass in a bit of code into a function: + + my $line; + timeout( 30, sub { $line = <STDIN> } ); + +If the code to execute had been passed in as a string, C<'$line = +E<lt>STDINE<gt>'>, there would have been no way for the hypothetical +timeout() function to access the lexical variable $line back in its +caller's scope. + +=head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regexp}? + +With the exception of regexps, you need to pass references to these +objects. See L<perlsub/"Pass by Reference"> for this particular +question, and L<perlref> for information on references. + +=over 4 + +=item Passing Variables and Functions + +Regular variables and functions are quite easy: just pass in a +reference to an existing or anonymous variable or function: + + func( \$some_scalar ); + + func( \$some_array ); + func( [ 1 .. 10 ] ); + + func( \%some_hash ); + func( { this => 10, that => 20 } ); + + func( \&some_func ); + func( sub { $_[0] ** $_[1] } ); + +=item Passing Filehandles + +To create filehandles you can pass to subroutines, you can use C<*FH> +or C<\*FH> notation ("typeglobs" - see L<perldata> for more information), +or create filehandles dynamically using the old FileHandle or the new +IO::File modules, both part of the standard Perl distribution. + + use Fcntl; + use IO::File; + my $fh = new IO::File $filename, O_WRONLY|O_APPEND; + or die "Can't append to $filename: $!"; + func($fh); + +=item Passing Regexps + +To pass regexps around, you'll need to either use one of the highly +experimental regular expression modules from CPAN (Nick Ing-Simmons's +Regexp or Ilya Zakharevich's Devel::Regexp), pass around strings +and use an exception-trapping eval, or else be be very, very clever. +Here's an example of how to pass in a string to be regexp compared: + + sub compare($$) { + my ($val1, $regexp) = @_; + my $retval = eval { $val =~ /$regexp/ }; + die if $@; + return $retval; + } + + $match = compare("old McDonald", q/d.*D/); + +Make sure you never say something like this: + + return eval "\$val =~ /$regexp/"; # WRONG + +or someone can sneak shell escapes into the regexp due to the double +interpolation of the eval and the double-quoted string. For example: + + $pattern_of_evil = 'danger ${ system("rm -rf * &") } danger'; + + eval "\$string =~ /$pattern_of_evil/"; + +Those preferring to be very, very clever might see the O'Reilly book, +I<Mastering Regular Expressions>, by Jeffrey Friedl. Page 273's +Build_MatchMany_Function() is particularly interesting. A complete +citation of this book is given in L<perlfaq2>. + +=item Passing Methods + +To pass an object method into a subroutine, you can do this: + + call_a_lot(10, $some_obj, "methname") + sub call_a_lot { + my ($count, $widget, $trick) = @_; + for (my $i = 0; $i < $count; $i++) { + $widget->$trick(); + } + } + +or you can use a closure to bundle up the object and its method call +and arguments: + + my $whatnot = sub { $some_obj->obfuscate(@args) }; + func($whatnot); + sub func { + my $code = shift; + &$code(); + } + +You could also investigate the can() method in the UNIVERSAL class +(part of the standard perl distribution). + +=back + +=head2 How do I create a static variable? + +As with most things in Perl, TMTOWTDI. What is a "static variable" in +other languages could be either a function-private variable (visible +only within a single function, retaining its value between calls to +that function), or a file-private variable (visible only to functions +within the file it was declared in) in Perl. + +Here's code to implement a function-private variable: + + BEGIN { + my $counter = 42; + sub prev_counter { return --$counter } + sub next_counter { return $counter++ } + } + +Now prev_counter() and next_counter() share a private variable $counter +that was initialized at compile time. + +To declare a file-private variable, you'll still use a my(), putting +it at the outer scope level at the top of the file. Assume this is in +file Pax.pm: + + package Pax; + my $started = scalar(localtime(time())); + + sub begun { return $started } + +When C<use Pax> or C<require Pax> loads this module, the variable will +be initialized. It won't get garbage-collected the way most variables +going out of scope do, because the begun() function cares about it, +but no one else can get it. It is not called $Pax::started because +its scope is unrelated to the package. It's scoped to the file. You +could conceivably have several packages in that same file all +accessing the same private variable, but another file with the same +package couldn't get to it. + +=head2 What's the difference between dynamic and lexical (static) scoping? Between local() and my()? + +C<local($x)> saves away the old value of the global variable C<$x>, +and assigns a new value for the duration of the subroutine, I<which is +visible in other functions called from that subroutine>. This is done +at run-time, so is called dynamic scoping. local() always affects global +variables, also called package variables or dynamic variables. + +C<my($x)> creates a new variable that is only visible in the current +subroutine. This is done at compile-time, so is called lexical or +static scoping. my() always affects private variables, also called +lexical variables or (improperly) static(ly scoped) variables. + +For instance: + + sub visible { + print "var has value $var\n"; + } + + sub dynamic { + local $var = 'local'; # new temporary value for the still-global + visible(); # variable called $var + } + + sub lexical { + my $var = 'private'; # new private variable, $var + visible(); # (invisible outside of sub scope) + } + + $var = 'global'; + + visible(); # prints global + dynamic(); # prints local + lexical(); # prints global + +Notice how at no point does the value "private" get printed. That's +because $var only has that value within the block of the lexical() +function, and it is hidden from called subroutine. + +In summary, local() doesn't make what you think of as private, local +variables. It gives a global variable a temporary value. my() is +what you're looking for if you want private variables. + +See also L<perlsub>, which explains this all in more detail. + +=head2 How can I access a dynamic variable while a similarly named lexical is in scope? + +You can do this via symbolic references, provided you haven't set +C<use strict "refs">. So instead of $var, use C<${'var'}>. + + local $var = "global"; + my $var = "lexical"; + + print "lexical is $var\n"; + + no strict 'refs'; + print "global is ${'var'}\n"; + +If you know your package, you can just mention it explicitly, as in +$Some_Pack::var. Note that the notation $::var is I<not> the dynamic +$var in the current package, but rather the one in the C<main> +package, as though you had written $main::var. Specifying the package +directly makes you hard-code its name, but it executes faster and +avoids running afoul of C<use strict "refs">. + +=head2 What's the difference between deep and shallow binding? + +In deep binding, lexical variables mentioned in anonymous subroutines +are the same ones that were in scope when the subroutine was created. +In shallow binding, they are whichever variables with the same names +happen to be in scope when the subroutine is called. Perl always uses +deep binding of lexical variables (i.e., those created with my()). +However, dynamic variables (aka global, local, or package variables) +are effectively shallowly bound. Consider this just one more reason +not to use them. See the answer to L<"What's a closure?">. + +=head2 Why doesn't "local($foo) = <FILE>;" work right? + +C<local()> gives list context to the right hand side of C<=>. The +E<lt>FHE<gt> read operation, like so many of Perl's functions and +operators, can tell which context it was called in and behaves +appropriately. In general, the scalar() function can help. This +function does nothing to the data itself (contrary to popular myth) +but rather tells its argument to behave in whatever its scalar fashion +is. If that function doesn't have a defined scalar behavior, this of +course doesn't help you (such as with sort()). + +To enforce scalar context in this particular case, however, you need +merely omit the parentheses: + + local($foo) = <FILE>; # WRONG + local($foo) = scalar(<FILE>); # ok + local $foo = <FILE>; # right + +You should probably be using lexical variables anyway, although the +issue is the same here: + + my($foo) = <FILE>; # WRONG + my $foo = <FILE>; # right + +=head2 How do I redefine a built-in function, operator, or method? + +Why do you want to do that? :-) + +If you want to override a predefined function, such as open(), +then you'll have to import the new definition from a different +module. See L<perlsub/"Overriding Builtin Functions">. There's +also an example in L<perltoot/"Class::Template">. + +If you want to overload a Perl operator, such as C<+> or C<**>, +then you'll want to use the C<use overload> pragma, documented +in L<overload>. + +If you're talking about obscuring method calls in parent classes, +see L<perltoot/"Overridden Methods">. + +=head2 What's the difference between calling a function as &foo and foo()? + +When you call a function as C<&foo>, you allow that function access to +your current @_ values, and you by-pass prototypes. That means that +the function doesn't get an empty @_, it gets yours! While not +strictly speaking a bug (it's documented that way in L<perlsub>), it +would be hard to consider this a feature in most cases. + +When you call your function as C<&foo()>, then you do get a new @_, +but prototyping is still circumvented. + +Normally, you want to call a function using C<foo()>. You may only +omit the parentheses if the function is already known to the compiler +because it already saw the definition (C<use> but not C<require>), +or via a forward reference or C<use subs> declaration. Even in this +case, you get a clean @_ without any of the old values leaking through +where they don't belong. + +=head2 How do I create a switch or case statement? + +This is explained in more depth in the L<perlsyn>. Briefly, there's +no official case statement, because of the variety of tests possible +in Perl (numeric comparison, string comparison, glob comparison, +regexp matching, overloaded comparisons, ...). Larry couldn't decide +how best to do this, so he left it out, even though it's been on the +wish list since perl1. + +Here's a simple example of a switch based on pattern matching. We'll +do a multi-way conditional based on the type of reference stored in +$whatchamacallit: + + SWITCH: + for (ref $whatchamacallit) { + + /^$/ && die "not a reference"; + + /SCALAR/ && do { + print_scalar($$ref); + last SWITCH; + }; + + /ARRAY/ && do { + print_array(@$ref); + last SWITCH; + }; + + /HASH/ && do { + print_hash(%$ref); + last SWITCH; + }; + + /CODE/ && do { + warn "can't print function ref"; + last SWITCH; + }; + + # DEFAULT + + warn "User defined type skipped"; + + } + +=head2 How can I catch accesses to undefined variables/functions/methods? + +The AUTOLOAD method, discussed in L<perlsub/"Autoloading"> and +L<perltoot/"AUTOLOAD: Proxy Methods">, lets you capture calls to +undefined functions and methods. + +When it comes to undefined variables that would trigger a warning +under C<-w>, you can use a handler to trap the pseudo-signal +C<__WARN__> like this: + + $SIG{__WARN__} = sub { + + for ( $_[0] ) { + + /Use of uninitialized value/ && do { + # promote warning to a fatal + die $_; + }; + + # other warning cases to catch could go here; + + warn $_; + } + + }; + +=head2 Why can't a method included in this same file be found? + +Some possible reasons: your inheritance is getting confused, you've +misspelled the method name, or the object is of the wrong type. Check +out L<perltoot> for details on these. You may also use C<print +ref($object)> to find out the class C<$object> was blessed into. + +Another possible reason for problems is because you've used the +indirect object syntax (eg, C<find Guru "Samy">) on a class name +before Perl has seen that such a package exists. It's wisest to make +sure your packages are all defined before you start using them, which +will be taken care of if you use the C<use> statement instead of +C<require>. If not, make sure to use arrow notation (eg, +C<Guru->find("Samy")>) instead. Object notation is explained in +L<perlobj>. + +=head2 How can I find out my current package? + +If you're just a random program, you can do this to find +out what the currently compiled package is: + + my $packname = ref bless []; + +But if you're a method and you want to print an error message +that includes the kind of object you were called on (which is +not necessarily the same as the one in which you were compiled): + + sub amethod { + my $self = shift; + my $class = ref($self) || $self; + warn "called me from a $class object"; + } + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlfaq8.pod b/pod/perlfaq8.pod new file mode 100644 index 0000000000..6ad5c15750 --- /dev/null +++ b/pod/perlfaq8.pod @@ -0,0 +1,749 @@ +=head1 NAME + +perlfaq8 - System Interaction ($Revision: 1.15 $) + +=head1 DESCRIPTION + +This section of the Perl FAQ covers questions involving operating +system interaction. This involves interprocess communication (IPC), +control over the user-interface (keyboard, screen and pointing +devices), and most anything else not related to data manipulation. + +Read the FAQs and documentation specific to the port of perl to your +operating system (eg, L<perlvms>, L<perlplan9>, ...). These should +contain more detailed information on the vagaries of your perl. + +=head2 How do I find out which operating system I'm running under? + +The $^O variable ($OSTYPE if you use English) contains the operating +system that your perl binary was built for. + +=head2 How come exec() doesn't return? + +Because that's what it does: it replaces your currently running +program with a different one. If you want to keep going (as is +probably the case if you're asking this question) use system() +instead. + +=head2 How do I do fancy stuff with the keyboard/screen/mouse? + +How you access/control keyboards, screens, and pointing devices +("mice") is system-dependent. Try the following modules: + +=over 4 + +=item Keyboard + + Term::Cap Standard perl distribution + Term::ReadKey CPAN + Term::ReadLine::Gnu CPAN + Term::ReadLine::Perl CPAN + Term::Screen CPAN + +=item Screen + + Term::Cap Standard perl distribution + Curses CPAN + Term::ANSIColor CPAN + +=item Mouse + + Tk CPAN + +=back + +=head2 How do I ask the user for a password? + +(This question has nothing to do with the web. See a different +FAQ for that.) + +There's an example of this in L<perlfunc/crypt>). First, you put +the terminal into "no echo" mode, then just read the password +normally. You may do this with an old-style ioctl() function, POSIX +terminal control (see L<POSIX>, and Chapter 7 of the Camel), or a call +to the B<stty> program, with varying degrees of portability. + +You can also do this for most systems using the Term::ReadKey module +from CPAN, which is easier to use and in theory more portable. + +=head2 How do I read and write the serial port? + +This depends on which operating system your program is running on. In +the case of Unix, the serial ports will be accessible through files in +/dev; on other systems, the devices names will doubtless differ. +Several problem areas common to all device interaction are the +following + +=over 4 + +=item lockfiles + +Your system may use lockfiles to control multiple access. Make sure +you follow the correct protocol. Unpredictable behaviour can result +from multiple processes reading from one device. + +=item open mode + +If you expect to use both read and write operations on the device, +you'll have to open it for update (see L<perlfunc/"open"> for +details). You may wish to open it without running the risk of +blocking by using sysopen() and C<O_RDWR|O_NDELAY|O_NOCTTY> from the +Fcntl module (part of the standard perl distribution). See +L<perlfunc/"sysopen"> for more on this approach. + +=item end of line + +Some devices will be expecting a "\r" at the end of each line rather +than a "\n". In some ports of perl, "\r" and "\n" are different from +their usual (Unix) ASCII values of "\012" and "\015". You may have to +give the numeric values you want directly, using octal ("\015"), hex +("0x0D"), or as a control-character specification ("\cM"). + + print DEV "atv1\012"; # wrong, for some devices + print DEV "atv1\015"; # right, for some devices + +Even though with normal text files, a "\n" will do the trick, there is +still no unified scheme for terminating a line that is portable +between Unix, DOS/Win, and Macintosh, except to terminate I<ALL> line +ends with "\015\012", and strip what you don't need from the output. +This applies especially to socket I/O and autoflushing, discussed +next. + +=item flushing output + +If you expect characters to get to your device when you print() them, +you'll want to autoflush that filehandle, as in the older + + use FileHandle; + DEV->autoflush(1); + +and the newer + + use IO::Handle; + DEV->autoflush(1); + +You can use select() and the C<$|> variable to control autoflushing +(see L<perlvar/$|> and L<perlfunc/select>): + + $oldh = select(DEV); + $| = 1; + select($oldh); + +You'll also see code that does this without a temporary variable, as in + + select((select(DEV), $| = 1)[0]); + +As mentioned in the previous item, this still doesn't work when using +socket I/O between Unix and Macintosh. You'll need to hardcode your +line terminators, in that case. + +=item non-blocking input + +If you are doing a blocking read() or sysread(), you'll have to +arrange for an alarm handler to provide a timeout (see +L<perlfunc/alarm>). If you have a non-blocking open, you'll likely +have a non-blocking read, which means you may have to use a 4-arg +select() to determine whether I/O is ready on that device (see +L<perlfunc/"select">. + +=back + +=head2 How do I decode encrypted password files? + +You spend lots and lots of money on dedicated hardware, but this is +bound to get you talked about. + +Seriously, you can't if they are Unix password files - the Unix +password system employs one-way encryption. Programs like Crack can +forcibly (and intelligently) try to guess passwords, but don't (can't) +guarantee quick success. + +If you're worried about users selecting bad passwords, you should +proactively check when they try to change their password (by modifying +passwd(1), for example). + +=head2 How do I start a process in the background? + +You could use + + system("cmd &") + +or you could use fork as documented in L<perlfunc/"fork">, with +further examples in L<perlipc>. Some things to be aware of, if you're +on a Unix-like system: + +=over 4 + +=item STDIN, STDOUT and STDERR are shared + +Both the main process and the backgrounded one (the "child" process) +share the same STDIN, STDOUT and STDERR filehandles. If both try to +access them at once, strange things can happen. You may want to close +or reopen these for the child. You can get around this with +C<open>ing a pipe (see L<perlfunc/"open">) but on some systems this +means that the child process cannot outlive the parent. + +=item Signals + +You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too. +SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is +sent when you write to a filehandle whose child process has closed (an +untrapped SIGPIPE can cause your program to silently die). This is +not an issue with C<system("cmd&")>. + +=item Zombies + +You have to be prepared to "reap" the child process when it finishes + + $SIG{CHLD} = sub { wait }; + +See L<perlipc/"Signals"> for other examples of code to do this. +Zombies are not an issue with C<system("prog &")>. + +=back + +=head2 How do I trap control characters/signals? + +You don't actually "trap" a control character. Instead, that +character generates a signal, which you then trap. Signals are +documented in L<perlipc/"Signals"> and chapter 6 of the Camel. + +Be warned that very few C libraries are re-entrant. Therefore, if you +attempt to print() in a handler that got invoked during another stdio +operation your internal structures will likely be in an +inconsistent state, and your program will dump core. You can +sometimes avoid this by using syswrite() instead of print(). + +Unless you're exceedingly careful, the only safe things to do inside a +signal handler are: set a variable and exit. And in the first case, +you should only set a variable in such a way that malloc() is not +called (eg, by setting a variable that already has a value). + +For example: + + $Interrupted = 0; # to ensure it has a value + $SIG{INT} = sub { + $Interrupted++; + syswrite(STDERR, "ouch\n", 5); + } + +However, because syscalls restart by default, you'll find that if +you're in a "slow" call, such as E<lt>FHE<gt>, read(), connect(), or +wait(), that the only way to terminate them is by "longjumping" out; +that is, by raising an exception. See the time-out handler for a +blocking flock() in L<perlipc/"Signals"> or chapter 6 of the Camel. + +=head2 How do I modify the shadow password file on a Unix system? + +If perl was installed correctly, the getpw*() functions described in +L<perlfunc> provide (read-only) access to the shadow password file. +To change the file, make a new shadow password file (the format varies +from system to system - see L<passwd(5)> for specifics) and use +pwd_mkdb(8) to install it (see L<pwd_mkdb(5)> for more details). + +=head2 How do I set the time and date? + +Assuming you're running under sufficient permissions, you should be +able to set the system-wide date and time by running the date(1) +program. (There is no way to set the time and date on a per-process +basis.) This mechanism will work for Unix, MS-DOS, Windows, and NT; +the VMS equivalent is C<set time>. + +However, if all you want to do is change your timezone, you can +probably get away with setting an environment variable: + + $ENV{TZ} = "MST7MDT"; # unixish + $ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms + system "trn comp.lang.perl"; + +=head2 How can I sleep() or alarm() for under a second? + +If you want finer granularity than the 1 second that the sleep() +function provides, the easiest way is to use the select() function as +documented in L<perlfunc/"select">. If your system has itimers and +syscall() support, you can check out the old example in +http://www.perl.com/CPAN/doc/misc/ancient/tutorial/eg/itimers.pl . + +=head2 How can I measure time under a second? + +In general, you may not be able to. The Time::HiRes module (available +from CPAN) provides this functionality for some systems. + +In general, you may not be able to. But if you system supports both the +syscall() function in Perl as well as a system call like gettimeofday(2), +then you may be able to do something like this: + + require 'sys/syscall.ph'; + + $TIMEVAL_T = "LL"; + + $done = $start = pack($TIMEVAL_T, ()); + + syscall( &SYS_gettimeofday, $start, 0)) != -1 + or die "gettimeofday: $!"; + + ########################## + # DO YOUR OPERATION HERE # + ########################## + + syscall( &SYS_gettimeofday, $done, 0) != -1 + or die "gettimeofday: $!"; + + @start = unpack($TIMEVAL_T, $start); + @done = unpack($TIMEVAL_T, $done); + + # fix microseconds + for ($done[1], $start[1]) { $_ /= 1_000_000 } + + $delta_time = sprintf "%.4f", ($done[0] + $done[1] ) + - + ($start[0] + $start[1] ); + +=head2 How can I do an atexit() or setjmp()/longjmp()? (Exception handling) + +Release 5 of Perl added the END block, which can be used to simulate +atexit(). Each package's END block is called when the program or +thread ends (see L<perlmod> manpage for more details). It isn't +called when untrapped signals kill the program, though, so if you use +END blocks you should also use + + use sigtrap qw(die normal-signals); + +Perl's exception-handling mechanism is its eval() operator. You can +use eval() as setjmp and die() as longjmp. For details of this, see +the section on signals, especially the time-out handler for a blocking +flock() in L<perlipc/"Signals"> and chapter 6 of the Camel. + +If exception handling is all you're interested in, try the +exceptions.pl library (part of the standard perl distribution). + +If you want the atexit() syntax (and an rmexit() as well), try the +AtExit module available from CPAN. + +=head2 Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? + +Some Sys-V based systems, notably Solaris 2.X, redefined some of the +standard socket constants. Since these were constant across all +architectures, they were often hardwired into perl code. The proper +way to deal with this is to "use Socket" to get the correct values. + +Note that even though SunOS and Solaris are binary compatible, these +values are different. Go figure. + +=head2 How can I call my system's unique C functions from Perl? + +In most cases, you write an external module to do it - see the answer +to "Where can I learn about linking C with Perl? [h2xs, xsubpp]". +However, if the function is a system call, and your system supports +syscall(), you can use the syscall function (documented in +L<perlfunc>). + +Remember to check the modules that came with your distribution, and +CPAN as well - someone may already have written a module to do it. + +=head2 Where do I get the include files to do ioctl() or syscall()? + +Historically, these would be generated by the h2ph tool, part of the +standard perl distribution. This program converts cpp(1) directives +in C header files to files containing subroutine definitions, like +&SYS_getitimer, which you can use as arguments to your functions. +It doesn't work perfectly, but it usually gets most of the job done. +Simple files like F<errno.h>, F<syscall.h>, and F<socket.h> were fine, +but the hard ones like F<ioctl.h> nearly always need to hand-edited. +Here's how to install the *.ph files: + + 1. become super-user + 2. cd /usr/include + 3. h2ph *.h */*.h + +If your system supports dynamic loading, for reasons of portability and +sanity you probably ought to use h2xs (also part of the standard perl +distribution). This tool converts C header files to Perl extensions. +See L<perlxstut> for how to get started with h2xs. + +If your system doesn't support dynamic loading, you still probably +ought to use h2xs. See L<perlxstut> and L<ExtUtils::MakeMaker> for +more information (in brief, just use B<make perl> instead of a plain +B<make> to rebuild perl with a new static extension). + +=head2 Why do setuid perl scripts complain about kernel problems? + +Some operating systems have bugs in the kernel that make setuid +scripts inherently insecure. Perl gives you a number of options +(described in L<perlsec>) to work around such systems. + +=head2 How can I open a pipe both to and from a command? + +The IPC::Open2 module (part of the standard perl distribution) is an +easy-to-use approach that internally uses pipe(), fork(), and exec() +to do the job. Make sure you read the deadlock warnings in its +documentation, though (see L<IPC::Open2>). + +=head2 How can I capture STDERR from an external command? + +There are three basic ways of running external commands: + + system $cmd; # using system() + $output = `$cmd`; # using backticks (``) + open (PIPE, "cmd |"); # using open() + +With system(), both STDOUT and STDERR will go the same place as the +script's versions of these, unless the command redirects them. +Backticks and open() read B<only> the STDOUT of your command. + +With any of these, you can change file descriptors before the call: + + open(STDOUT, ">logfile"); + system("ls"); + +or you can use Bourne shell file-descriptor redirection: + + $output = `$cmd 2>some_file`; + open (PIPE, "cmd 2>some_file |"); + +You can also use file-descriptor redirection to make STDERR a +duplicate of STDOUT: + + $output = `$cmd 2>&1`; + open (PIPE, "cmd 2>&1 |"); + +Note that you I<cannot> simply open STDERR to be a dup of STDOUT +in your Perl program and avoid calling the shell to do the redirection. +This doesn't work: + + open(STDERR, ">&STDOUT"); + $alloutput = `cmd args`; # stderr still escapes + +This fails because the open() makes STDERR go to where STDOUT was +going at the time of the open(). The backticks then make STDOUT go to +a string, but don't change STDERR (which still goes to the old +STDOUT). + +Note that you I<must> use Bourne shell (sh(1)) redirection syntax in +backticks, not csh(1)! Details on why Perl's system() and backtick +and pipe opens all use the Bourne shell are in +http://www.perl.com/CPAN/doc/FMTEYEWTK/versus/csh.whynot . + +You may also use the IPC::Open3 module (part of the standard perl +distribution), but be warned that it has a different order of +arguments from IPC::Open2 (see L<IPC::Open3>). + +=head2 Why doesn't open() return an error when a pipe open fails? + +It does, but probably not how you expect it to. On systems that +follow the standard fork()/exec() paradigm (eg, Unix), it works like +this: open() causes a fork(). In the parent, open() returns with the +process ID of the child. The child exec()s the command to be piped +to/from. The parent can't know whether the exec() was successful or +not - all it can return is whether the fork() succeeded or not. To +find out if the command succeeded, you have to catch SIGCHLD and +wait() to get the exit status. + +On systems that follow the spawn() paradigm, open() I<might> do what +you expect - unless perl uses a shell to start your command. In this +case the fork()/exec() description still applies. + +=head2 What's wrong with using backticks in a void context? + +Strictly speaking, nothing. Stylistically speaking, it's not a good +way to write maintainable code because backticks have a (potentially +humungous) return value, and you're ignoring it. It's may also not be very +efficient, because you have to read in all the lines of output, allocate +memory for them, and then throw it away. Too often people are lulled +to writing: + + `cp file file.bak`; + +And now they think "Hey, I'll just always use backticks to run programs." +Bad idea: backticks are for capturing a program's output; the system() +function is for running programs. + +Consider this line: + + `cat /etc/termcap`; + +You haven't assigned the output anywhere, so it just wastes memory +(for a little while). Plus you forgot to check C<$?> to see whether +the program even ran correctly. Even if you wrote + + print `cat /etc/termcap`; + +In most cases, this could and probably should be written as + + system("cat /etc/termcap") == 0 + or die "cat program failed!"; + +Which will get the output quickly (as its generated, instead of only +at the end ) and also check the return value. + +system() also provides direct control over whether shell wildcard +processing may take place, whereas backticks do not. + +=head2 How can I call backticks without shell processing? + +This is a bit tricky. Instead of writing + + @ok = `grep @opts '$search_string' @filenames`; + +You have to do this: + + my @ok = (); + if (open(GREP, "-|")) { + while (<GREP>) { + chomp; + push(@ok, $_); + } + close GREP; + } else { + exec 'grep', @opts, $search_string, @filenames; + } + +Just as with system(), no shell escapes happen when you exec() a list. + +=head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MSDOS)? + +Because some stdio's set error and eof flags that need clearing. The +POSIX module defines clearerr() that you can use. That is the +technically correct way to do it. Here are some less reliable +workarounds: + +=over 4 + +=item 1 + +Try keeping around the seekpointer and go there, like this: + + $where = tell(LOG); + seek(LOG, $where, 0); + +=item 2 + +If that doesn't work, try seeking to a different part of the file and +then back. + +=item 3 + +If that doesn't work, try seeking to a different part of +the file, reading something, and then seeking back. + +=item 4 + +If that doesn't work, give up on your stdio package and use sysread. + +=back + +=head2 How can I convert my shell script to perl? + +Learn Perl and rewrite it. Seriously, there's no simple converter. +Things that are awkward to do in the shell are easy to do in Perl, and +this very awkwardness is what would make a shell->perl converter +nigh-on impossible to write. By rewriting it, you'll think about what +you're really trying to do, and hopefully will escape the shell's +pipeline datastream paradigm, which while convenient for some matters, +causes many inefficiencies. + +=head2 Can I use perl to run a telnet or ftp session? + +Try the Net::FTP and TCP::Client modules (available from CPAN). +http://www.perl.com/CPAN/scripts/netstuff/telnet.emul.shar will also +help for emulating the telnet protocol. + +=head2 How can I write expect in Perl? + +Once upon a time, there was a library called chat2.pl (part of the +standard perl distribution), which never really got finished. These +days, your best bet is to look at the Comm.pl library available from +CPAN. + +=head2 Is there a way to hide perl's command line from programs such as "ps"? + +First of all note that if you're doing this for security reasons (to +avoid people seeing passwords, for example) then you should rewrite +your program so that critical information is never given as an +argument. Hiding the arguments won't make your program completely +secure. + +To actually alter the visible command line, you can assign to the +variable $0 as documented in L<perlvar>. This won't work on all +operating systems, though. Daemon programs like sendmail place their +state there, as in: + + $0 = "orcus [accepting connections]"; + +=head2 I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible? + +=over 4 + +=item Unix + +In the strictest sense, it can't be done -- the script executes as a +different process from the shell it was started from. Changes to a +process are not reflected in its parent, only in its own children +created after the change. There is shell magic that may allow you to +fake it by eval()ing the script's output in your shell; check out the +comp.unix.questions FAQ for details. + +=item VMS + +Change to %ENV persist after Perl exits, but directory changes do not. + +=back + +=head2 How do I close a process's filehandle without waiting for it to complete? + +Assuming your system supports such things, just send an appropriate signal +to the process (see L<perlfunc/"kill">. It's common to first send a TERM +signal, wait a little bit, and then send a KILL signal to finish it off. + +=head2 How do I fork a daemon process? + +If by daemon process you mean one that's detached (disassociated from +its tty), then the following process is reported to work on most +Unixish systems. Non-Unix users should check their Your_OS::Process +module for other solutions. + +=over 4 + +=item * + +Open /dev/tty and use the the TIOCNOTTY ioctl on it. See L<tty(4)> +for details. + +=item * + +Change directory to / + +=item * + +Reopen STDIN, STDOUT, and STDERR so they're not connected to the old +tty. + +=item * + +Background yourself like this: + + fork && exit; + +=back + +=head2 How do I make my program run with sh and csh? + +See the F<eg/nih> script (part of the perl source distribution). + +=head2 How do I keep my own module/library directory? + +When you build modules, use the PREFIX option when generating +Makefiles: + + perl Makefile.PL PREFIX=/u/mydir/perl + +then either set the PERL5LIB environment variable before you run +scripts that use the modules/libraries (see L<perlrun>) or say + + use lib '/u/mydir/perl'; + +See Perl's L<lib> for more information. + +=head2 How do I find out if I'm running interactively or not? + +Good question. Sometimes C<-t STDIN> and C<-t STDOUT> can give clues, +sometimes not. + + if (-t STDIN && -t STDOUT) { + print "Now what? "; + } + +On POSIX systems, you can test whether your own process group matches +the current process group of your controlling terminal as follows: + + use POSIX qw/getpgrp tcgetpgrp/; + open(TTY, "/dev/tty") or die $!; + $tpgrp = tcgetpgrp(TTY); + $pgrp = getpgrp(); + if ($tpgrp == $pgrp) { + print "foreground\n"; + } else { + print "background\n"; + } + +=head2 How do I timeout a slow event? + +Use the alarm() function, probably in conjunction with a signal +handler, as documented L<perlipc/"Signals"> and chapter 6 of the +Camel. You may instead use the more flexible Sys::AlarmCall module +available from CPAN. + +=head2 How do I set CPU limits? + +Use the BSD::Resource module from CPAN. + +=head2 How do I avoid zombies on a Unix system? + +Use the reaper code from L<perlipc/"Signals"> to call wait() when a +SIGCHLD is received, or else use the double-fork technique described +in L<perlfunc/fork>. + +=head2 How do I use an SQL database? + +There are a number of excellent interfaces to SQL databases. See the +DBD::* modules available from +http://www.perl.com/CPAN/modules/dbperl/DBD . + +=head2 How do I make a system() exit on control-C? + +You can't. You need to imitate the system() call (see L<perlipc> for +sample code) and then have a signal handler for the INT signal that +passes the signal on to the subprocess. + +=head2 How do I open a file without blocking? + +If you're lucky enough to be using a system that supports +non-blocking reads (most Unixish systems do), you need only to use the +O_NDELAY or O_NONBLOCK flag from the Fcntl module in conjunction with +sysopen(): + + use Fcntl; + sysopen(FH, "/tmp/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644) + or die "can't open /tmp/somefile: $!": + +=head2 How do I install a CPAN module? + +The easiest way is to have the CPAN module do it for you. This module +comes with perl version 5.004 and later. To manually install the CPAN +module, or any well-behaved CPAN module for that matter, follow these +steps: + +=over 4 + +=item 1 + +Unpack the source into a temporary area. + +=item 2 + + perl Makefile.PL + +=item 3 + + make + +=item 4 + + make test + +=item 5 + + make install + +=back + +If your version of perl is compiled without dynamic loading, then you +just need to replace step 3 (B<make>) with B<make perl> and you will +get a new F<perl> binary with your extension linked in. + +See L<ExtUtils::MakeMaker> for more details on building extensions. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod new file mode 100644 index 0000000000..e62dac4bd3 --- /dev/null +++ b/pod/perlfaq9.pod @@ -0,0 +1,277 @@ +=head1 NAME + +perlfaq9 - Networking ($Revision: 1.13 $) + +=head1 DESCRIPTION + +This section deals with questions related to networking, the internet, +and a few on the web. + +=head2 My CGI script runs from the command line but not the browser. Can you help me fix it? + +Sure, but you probably can't afford our contracting rates :-) + +Seriously, if you can demonstrate that you've read the following FAQs +and that your problem isn't something simple that can be easily +answered, you'll probably receive a courteous and useful reply to your +question if you post it on comp.infosystems.www.authoring.cgi (if it's +something to do with HTTP, HTML, or the CGI protocols). Questions that +appear to be Perl questions but are really CGI ones that are posted to +comp.lang.perl.misc may not be so well received. + +The useful FAQs are: + + http://www.perl.com/perl/faq/idiots-guide.html + http://www3.pair.com/webthing/docs/cgi/faqs/cgifaq.shtml + http://www.perl.com/perl/faq/perl-cgi-faq.html + http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html + http://www.boutell.com/faq/ + +=head2 How do I remove HTML from a string? + +The most correct way (albeit not the fastest) is to use HTML::Parse +from CPAN (part of the libwww-perl distribution, which is a must-have +module for all web hackers). + +Many folks attempt a simple-minded regular expression approach, like +C<s/E<lt>.*?E<gt>//g>, but that fails in many cases because the tags +may continue over line breaks, they may contain quoted angle-brackets, +or HTML comment may be present. Plus folks forget to convert +entities, like C<<> for example. + +Here's one "simple-minded" approach, that works for most files: + + #!/usr/bin/perl -p0777 + s/<(?:[^>'"]*|(['"]).*?\1)*>//gs + +If you want a more complete solution, see the 3-stage striphtml +program in +http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/striphtml.gz +. + +=head2 How do I extract URLs? + +A quick but imperfect approach is + + #!/usr/bin/perl -n00 + # qxurl - tchrist@perl.com + print "$2\n" while m{ + < \s* + A \s+ HREF \s* = \s* (["']) (.*?) \1 + \s* > + }gsix; + +This version does not adjust relative URLs, understand alternate +bases, deal with HTML comments, or accept URLs themselves as +arguments. It also runs about 100x faster than a more "complete" +solution using the LWP suite of modules, such as the +http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/xurl.gz +program. + +=head2 How do I download a file from the user's machine? How do I open a file on another machine? + +In the context of an HTML form, you can use what's known as +B<multipart/form-data> encoding. The CGI.pm module (available from +CPAN) supports this in the start_multipart_form() method, which isn't +the same as the startform() method. + +=head2 How do I make a pop-up menu in HTML? + +Use the B<E<lt>SELECTE<gt>> and B<E<lt>OPTIONE<gt>> tags. The CGI.pm +module (available from CPAN) supports this widget, as well as many +others, including some that it cleverly synthesizes on its own. + +=head2 How do I fetch an HTML file? + +Use the LWP::Simple module available from CPAN, part of the excellent +libwww-perl (LWP) package. On the other hand, and if you have the +lynx text-based HTML browser installed on your system, this isn't too +bad: + + $html_code = `lynx -source $url`; + $text_data = `lynx -dump $url`; + +=head2 how do I decode or create those %-encodings on the web? + +Here's an example of decoding: + + $string = "http://altavista.digital.com/cgi-bin/query?pg=q&what=news&fmt=.&q=%2Bcgi-bin+%2Bperl.exe"; + $string =~ s/%([a-fA-F0-9]{2})/chr(hex($1))/ge; + +Encoding is a bit harder, because you can't just blindly change +all the non-alphanumunder character (C<\W>) into their hex escapes. +It's important that characters with special meaning like C</> and C<?> +I<not> be translated. Probably the easiest way to get this right is +to avoid reinventing the wheel and just use the URI::Escape module, +which is part of the libwww-perl package (LWP) available from CPAN. + +=head2 How do I redirect to another page? + +Instead of sending back a C<Content-Type> as the headers of your +reply, send back a C<Location:> header. Officially this should be a +C<URI:> header, so the CGI.pm module (available from CPAN) sends back +both: + + Location: http://www.domain.com/newpage + URI: http://www.domain.com/newpage + +Note that relative URLs in these headers can cause strange effects +because of "optimizations" that servers do. + +=head2 How do I put a password on my web pages? + +That depends. You'll need to read the documentation for your web +server, or perhaps check some of the other FAQs referenced above. + +=head2 How do I edit my .htpasswd and .htgroup files with Perl? + +The HTTPD::UserAdmin and HTTPD::GroupAdmin modules provide a +consistent OO interface to these files, regardless of how they're +stored. Databases may be text, dbm, Berkley DB or any database with a +DBI compatible driver. HTTPD::UserAdmin supports files used by the +`Basic' and `Digest' authentication schemes. Here's an example: + + use HTTPD::UserAdmin (); + HTTPD::UserAdmin + ->new(DB => "/foo/.htpasswd") + ->add($username => $password); + +=head2 How do I parse an email header? + +For a quick-and-dirty solution, try this solution derived +from page 222 of the 2nd edition of "Programming Perl": + + $/ = ''; + $header = <MSG>; + $header =~ s/\n\s+/ /g; # merge continuation lines + %head = ( UNIX_FROM_LINE, split /^([-\w]+):\s*/m, $header ); + +That solution doesn't do well if, for example, you're trying to +maintain all the Received lines. A more complete approach is to use +the Mail::Header module from CPAN (part of the MailTools package). + +=head2 How do I decode a CGI form? + +A lot of people are tempted to code this up themselves, so you've +probably all seen a lot of code involving C<$ENV{CONTENT_LENGTH}> and +C<$ENV{QUERY_STRING}>. It's true that this can work, but there are +also a lot of versions of this floating around that are quite simply +broken! + +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://www.bio.cam.ac.uk/web/form.html). + +=head2 How do I check a valid email address? + +You can't. + +Without sending mail to the address and seeing whether it bounces (and +even then you face the halting problem), you cannot determine whether +an email address is valid. Even if you apply the email header +standard, you can have problems, because there are deliverable +addresses that aren't RFC-822 (the mail header standard) compliant, +and addresses that aren't deliverable which are compliant. + +Many are tempted to try to eliminate many frequently-invalid email +addresses with a simple regexp, such as +C</^[\w.-]+\@([\w.-]\.)+\w+$/>. However, this also throws out many +valid ones, and says nothing about potential deliverability, so is not +suggested. Instead, see +http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/ckaddr.gz , +which actually checks against the full RFC spec (except for nested +comments), looks for addresses you may not wish to accept email to +(say, Bill Clinton or your postmaster), and then makes sure that the +hostname given can be looked up in DNS. It's not fast, but it works. + +=head2 How do I decode a MIME/BASE64 string? + +The MIME-tools package (available from CPAN) handles this and a lot +more. Decoding BASE64 becomes as simple as: + + use MIME::base64; + $decoded = decode_base64($encoded); + +A more direct approach is to use the unpack() function's "u" +format after minor transliterations: + + tr#A-Za-z0-9+/##cd; # remove non-base64 chars + tr#A-Za-z0-9+/# -_#; # convert to uuencoded format + $len = pack("c", 32 + 0.75*length); # compute length byte + print unpack("u", $len . $_); # uudecode and print + +=head2 How do I return the user's email address? + +On systems that support getpwuid, the $E<lt> variable and the +Sys::Hostname module (which is part of the standard perl distribution), +you can probably try using something like this: + + use Sys::Hostname; + $address = sprintf('%s@%s', getpwuid($<), hostname); + +Company policies on email address can mean that this generates addresses +that the company's email system will not accept, so you should ask for +users' email addresses when this matters. Furthermore, not all systems +on which Perl runs are so forthcoming with this information as is Unix. + +The Mail::Util module from CPAN (part of the MailTools package) provides a +mailaddress() function that tries to guess the mail address of the user. +It makes a more intelligent guess than the code above, using information +given when the module was installed, but it could still be incorrect. +Again, the best way is often just to ask the user. + +=head2 How do I send/read mail? + +Sending mail: the Mail::Mailer module from CPAN (part of the MailTools +package) is UNIX-centric, while Mail::Internet uses Net::SMTP which is +not UNIX-centric. Reading mail: use the Mail::Folder module from CPAN +(part of the MailFolder package) or the Mail::Internet module from +CPAN (also part of the MailTools package). + +=head2 How do I find out my hostname/domainname/IP address? + +A lot of code has historically cavalierly called the C<`hostname`> +program. While sometimes expedient, this isn't very portable. It's +one of those tradeoffs of convenience versus portability. + +The Sys::Hostname module (part of the standard perl distribution) will +give you the hostname after which you can find out the IP address +(assuming you have working DNS) with a gethostbyname() call. + + use Socket; + use Sys::Hostname; + my $host = hostname(); + my $addr = inet_ntoa(scalar(gethostbyname($name)) || 'localhost'); + +Probably the simplest way to learn your DNS domain name is to grok +it out of /etc/resolv.conf, at least under Unix. Of course, this +assumes several things about your resolv.conf configuration, including +that it exists. + +(We still need a good DNS domain name-learning method for non-Unix +systems.) + +=head2 How do I fetch a news article or the active newsgroups? + +Use the Net::NNTP or News::NNTPClient modules, both available from CPAN. +This can make tasks like fetching the newsgroup list as simple as: + + perl -MNews::NNTPClient + -e 'print News::NNTPClient->new->list("newsgroups")' + +=head2 How do I fetch/put an FTP file? + +LWP::Simple (available from CPAN) can fetch but not put. Net::FTP (also +available from CPAN) is more complex but can put as well as fetch. + +=head2 How can I do RPC in Perl? + +A DCE::RPC module is being developed (but is not yet available), and +will be released as part of the DCE-Perl package (available from +CPAN). No ONC::RPC module is known. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997 Tom Christiansen and Nathan Torkington. +All rights reserved. See L<perlfaq> for distribution information. diff --git a/pod/perlform.pod b/pod/perlform.pod index fcdea2495e..4e55e02800 100644 --- a/pod/perlform.pod +++ b/pod/perlform.pod @@ -194,7 +194,7 @@ If you use the English module, you can even read the variable names: select($ofh); But you still have those funny select()s. So just use the FileHandle -module. Now, you can access these special variables using lower-case +module. Now, you can access these special variables using lowercase method names instead: use FileHandle; @@ -315,12 +315,12 @@ is to printf(), do this: =head1 WARNINGS -The lone dot that ends a format can also prematurely end an E-Mail +The lone dot that ends a format can also prematurely end an email message passing through a misconfigured Internet mailer (and based on experience, such misconfiguration is the rule, not the exception). So -when sending format code through E-Mail, you should indent it so that +when sending format code through email, you should indent it so that the format-ending dot is not on the left margin; this will prevent -E-Mail cutoff. +email cutoff. Lexical variables (declared with "my") are not visible within a format unless the format is declared within the scope of the lexical diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index eb7276a3b4..c4de4a39ae 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -35,11 +35,11 @@ operator or unary operator, and precedence does matter. And whitespace between the function and left parenthesis doesn't count--so you need to be careful sometimes: - print 1+2+3; # Prints 6. - print(1+2) + 3; # Prints 3. - print (1+2)+3; # Also prints 3! - print +(1+2)+3; # Prints 6. - print ((1+2)+3); # Prints 6. + print 1+2+4; # Prints 7. + print(1+2) + 4; # Prints 3. + print (1+2)+4; # Also prints 3! + print +(1+2)+4; # Prints 7. + print ((1+2)+4); # Prints 7. If you run Perl with the B<-w> switch it can warn you about this. For example, the third line above produces: @@ -1123,21 +1123,22 @@ value is taken as the name of the filehandle. =item flock FILEHANDLE,OPERATION Calls flock(2), or an emulation of it, on FILEHANDLE. Returns TRUE for -success, FALSE on failure. Will produce a fatal error if used on a -machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3). -flock() is Perl's portable file locking interface, although it will lock -only entire files, not records. +success, FALSE on failure. Produces a fatal error if used on a machine +that doesn't implement flock(2), fcntl(2) locking, or lockf(3). flock() +is Perl's portable file locking interface, although it locks only entire +files, not records. OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but -you can use the symbolic names if you pull them in with an explicit -request to the Fcntl module. The names can be requested as a group with -the :flock tag (or they can be requested individually, of course). -LOCK_SH requests a shared lock, LOCK_EX requests an exclusive lock, and -LOCK_UN releases a previously requested lock. If LOCK_NB is added to -LOCK_SH or LOCK_EX then flock() will return immediately rather than -blocking waiting for the lock (check the return status to see if you got -it). +you can use the symbolic names if import them from the Fcntl module, +either individually, or as a group using the ':flock' tag. LOCK_SH +requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN +releases a previously requested lock. If LOCK_NB is added to LOCK_SH or +LOCK_EX then flock() will return immediately rather than blocking +waiting for the lock (check the return status to see if you got it). + +To avoid the possibility of mis-coordination, Perl flushes FILEHANDLE +before (un)locking it. Note that the emulation built with lockf(3) doesn't provide shared locks, and it requires that FILEHANDLE be open with write intent. These @@ -1436,9 +1437,11 @@ Returns the socket option requested, or undefined if there is an error. =item glob -Returns the value of EXPR with filename expansions such as a shell -would do. This is the internal function implementing the <*.c> -operator, except it's easier to use. If EXPR is omitted, $_ is used. +Returns the value of EXPR with filename expansions such as a shell would +do. This is the internal function implementing the C<E<lt>*.cE<gt>> +operator, but you can use it directly. If EXPR is omitted, $_ is used. +The C<E<lt>*.cE<gt>> operator is discussed in more detail in +L<perlop/"I/O Operators">. =item gmtime EXPR @@ -2299,7 +2302,7 @@ Generalized quotes. See L<perlop>. =item quotemeta -Returns the value of EXPR with with all non-alphanumeric +Returns the value of EXPR with all non-alphanumeric characters backslashed. (That is, all characters not matching C</[A-Za-z_0-9]/> will be preceded by a backslash in the returned string, regardless of any locale settings.) @@ -2499,9 +2502,9 @@ so you'll probably want to use them instead. See L</my>. =item return LIST -Returns from a subroutine or eval with the value specified. (Note that -in the absence of a return a subroutine or eval() will automatically -return the value of the last expression evaluated.) +Returns from a subroutine, eval(), or do FILE with the value specified. +(Note that in the absence of a return, a subroutine, eval, or do FILE +will automatically return the value of the last expression evaluated.) =item reverse LIST diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 8c78802fb4..866cafb2fc 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -777,9 +777,9 @@ The current kinds of Magic Virtual Tables are: . vtbl_pos $. scalar variable ~ None Used by certain extensions -When an upper-case and lower-case letter both exist in the table, then the -upper-case letter is used to represent some kind of composite type (a list -or a hash), and the lower-case letter is used to represent an element of +When an uppercase and lowercase letter both exist in the table, then the +uppercase letter is used to represent some kind of composite type (a list +or a hash), and the lowercase letter is used to represent an element of that composite type. The '~' magic type is defined specifically for use by extensions and @@ -805,12 +805,12 @@ if the SV is not of type SVt_PVMG, Perl may core-dump. int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen); This routine checks to see what types of magic C<sv> has. If the mg_type -field is an upper-case letter, then the mg_obj is copied to C<nsv>, but -the mg_type field is changed to be the lower-case letter. +field is an uppercase letter, then the mg_obj is copied to C<nsv>, but +the mg_type field is changed to be the lowercase letter. =head1 Subroutines -=head2 XSUB's and the Argument Stack +=head2 XSUBs and the Argument Stack The XSUB mechanism is a simple way for Perl programs to access C subroutines. An XSUB routine will have a stack that contains the arguments from the Perl @@ -954,7 +954,7 @@ The most recent development releases of Perl has been experimenting with removing Perl's dependency on the "normal" standard I/O suite and allowing other stdio implementations to be used. This involves creating a new abstraction layer that then calls whichever implementation of stdio Perl -was compiled with. All XSUB's should now use the functions in the PerlIO +was compiled with. All XSUBs should now use the functions in the PerlIO abstraction layer and not make any assumptions about what kind of stdio is being used. @@ -1396,7 +1396,7 @@ be the glob for "AUTOLOAD". In this case the corresponing variable $AUTOLOAD is already setup. Note that if you want to keep this glob for a long time, you need to -check for it being "AUTOLOAD", since at the later time the the call +check for it being "AUTOLOAD", since at the later time the call may load a different subroutine due to $AUTOLOAD changing its value. Use the glob created via a side effect to do this. @@ -1427,27 +1427,12 @@ Returns a pointer to the stash for a specified package. See C<gv_stashpv>. Return the SV from the GV. -=item he_delayfree - -Releases a hash entry, such as while iterating though the hash, but -delays actual freeing of key and value until the end of the current -statement (or thereabouts) with C<sv_2mortal>. See C<hv_iternext>. - - void he_delayfree _((HV* hv, HE* hent)); - =item HEf_SVKEY This flag, used in the length slot of hash entries and magic structures, specifies the structure contains a C<SV*> pointer where a C<char*> pointer is to be expected. (For information only--not to be used). -=item he_free - -Releases a hash entry, such as while iterating though the hash. See -C<hv_iternext>. - - void he_free _((HV* hv, HE* hent)); - =item HeHASH Returns the computed hash (type C<U32>) stored in the hash entry. @@ -1519,6 +1504,15 @@ Clears a hash, making it empty. void hv_clear _((HV* tb)); +=item hv_delayfree_ent + +Releases a hash entry, such as while iterating though the hash, but +delays actual freeing of key and value until the end of the current +statement (or thereabouts) with C<sv_2mortal>. See C<hv_iternext> +and C<hv_free_ent>. + + void hv_delayfree_ent _((HV* hv, HE* entry)); + =item hv_delete Deletes a key/value pair in the hash. The value SV is removed from the hash @@ -1572,6 +1566,13 @@ structure if you need to store it somewhere. HE* hv_fetch_ent _((HV* tb, SV* key, I32 lval, U32 hash)); +=item hv_free_ent + +Releases a hash entry, such as while iterating though the hash. See +C<hv_iternext> and C<hv_delayfree_ent>. + + void hv_free_ent _((HV* hv, HE* entry)); + =item hv_iterinit Prepares a starting point to traverse a hash table. @@ -1821,7 +1822,7 @@ SV is B<not> incremented. =item newSV Creates a new SV. The C<len> parameter indicates the number of bytes of -pre-allocated string space the SV should have. The reference count for the +preallocated string space the SV should have. The reference count for the new SV is set to 1. SV* newSV _((STRLEN len)); @@ -2909,4 +2910,4 @@ API Listing by Dean Roehrich <F<roehrich@cray.com>>. =head1 DATE -Version 31.2: 1997/3/5 +Version 31.3: 1997/3/14 diff --git a/pod/perlipc.pod b/pod/perlipc.pod index d289ad380c..ab4a912bc6 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -258,6 +258,57 @@ handle. Consider: print FH "bang\n"; close FH; +=head2 Filehandles + +Both the main process and the child process share the same STDIN, +STDOUT and STDERR filehandles. If both processes try to access them +at once, strange things can happen. You may want to close or reopen +the filehandles for the child. You can get around this by opening +your pipe with open(), but on some systems this means that the child +process cannot outlive the parent. + +=head2 Background Processes + +You can run a command in the background with: + + system("cmd&"); + +The command's STDOUT and STDERR (and possibly STDIN, depending on your +shell) will be the same as the parent's. You won't need to catch +SIGCHLD because of the double-fork taking place (see below for more +details). + +=head2 Complete Dissociation of Child from Parent + +In some cases (starting server processes, for instance) you'll want to +complete dissociate the child process from the parent. The following +process is reported to work on most Unixish systems. Non-Unix users +should check their Your_OS::Process module for other solutions. + +=over 4 + +=item * + +Open /dev/tty and use the the TIOCNOTTY ioctl on it. See L<tty(4)> +for details. + +=item * + +Change directory to / + +=item * + +Reopen STDIN, STDOUT, and STDERR so they're not connected to the old +tty. + +=item * + +Background yourself like this: + + fork && exit; + +=back + =head2 Safe Pipe Opens Another interesting approach to IPC is making your single program go @@ -428,6 +479,14 @@ setting C<$AF_INET = 2>, you know you're in for big trouble: An immeasurably superior approach is to use the C<Socket> module, which more reliably grants access to various constants and functions you'll need. +If you're not writing a server/client for an existing protocol like +NNTP or SMTP, you should give some thought to how your server will +know when the client has finished talking, and vice-versa. Most +protocols are based on one-line messages and responses (so one party +knows the other has finished when a "\n" is received) or multiline +messages and responses that end with a period on an empty line +("\n.\n" terminates a message/response). + =head2 Internet TCP Clients and Servers Use Internet-domain sockets when you want to do client-server diff --git a/pod/perllocale.pod b/pod/perllocale.pod index d393b81483..31ab40a58d 100644 --- a/pod/perllocale.pod +++ b/pod/perllocale.pod @@ -5,7 +5,7 @@ perllocale - Perl locale handling (internationalization and localization) =head1 DESCRIPTION Perl supports language-specific notions of data such as "is this a -letter", "what is the upper-case equivalent of this letter", and "which +letter", "what is the uppercase equivalent of this letter", and "which of these letters comes first". These are important issues, especially for languages other than English - but also for English: it would be very naE<iuml>ve to think that C<A-Za-z> defines all the "letters". Perl @@ -371,7 +371,7 @@ setting, characters like 'E<aelig>', 'E<eth>', 'E<szlig>', and 'E<oslash>' may be understood as C<\w> characters. The C<LC_CTYPE> locale also provides the map used in translating -characters between lower- and upper-case. This affects the case-mapping +characters between lower and uppercase. This affects the case-mapping functions - lc(), lcfirst, uc() and ucfirst(); case-mapping interpolation with C<\l>, C<\L>, C<\u> or <\U> in double-quoted strings and in C<s///> substitutions; and case-independent regular expression diff --git a/pod/perlobj.pod b/pod/perlobj.pod index c8b85b4b7d..07a71dc203 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -283,7 +283,7 @@ are inherited by all other classes: =item isa(CLASS) -C<isa> returns I<true> if its object is blessed into a sub-class of C<CLASS> +C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS> C<isa> is also exportable and can be called as a sub with two arguments. This allows the ability to check what a reference points to. Example diff --git a/pod/perlop.pod b/pod/perlop.pod index 71794fa759..c4a342be7b 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -767,12 +767,13 @@ Here is the output (split into several lines): =item C<'STRING'> -A single-quoted, literal string. Backslashes are ignored, unless -followed by the delimiter or another backslash, in which case the -delimiter or backslash is interpolated. +A single-quoted, literal string. A backslash represents a backslash +unless followed by the delimiter or another backslash, in which case +the delimiter or backslash is interpolated. $foo = q!I said, "You said, 'She said it.'"!; $bar = q('This is it.'); + $baz = '\n'; # a two-character string =item qq/STRING/ @@ -783,6 +784,7 @@ A double-quoted, interpolated string. $_ .= qq (*** The previous line contains the naughty word "$1".\n) if /(tcl|rexx|python)/; # :-) + $baz = "\n"; # a one-character string =item qx/STRING/ @@ -1190,3 +1192,23 @@ for them. By default, their results are interpreted as unsigned integers. However, if C<use integer> is in effect, their results are interpreted as signed integers. For example, C<~0> usually evaluates to a large integral value. However, C<use integer; ~0> is -1. + +=head2 Floating-point Arithmetic + +While C<use integer> provides integer-only arithmetic, there is no +similar ways to provide rounding or truncation at a certain number of +decimal places. For rounding to a certain number of digits, sprintf() +or printf() is usually the easiest route. + +The POSIX module (part of the standard perl distribution) implements +ceil(), floor(), and a number of other mathematical and trigonometric +functions. The Math::Complex module (part of the standard perl +distribution) defines a number of mathematical functions that can also +work on real numbers. Math::Complex not as efficient as POSIX, but +POSIX can't work with complex numbers. + +Rounding in financial applications can have serious implications, and +the rounding method used should be specified precisely. In these +cases, it probably pays not to trust whichever system rounding is +being used by Perl, but to instead implement the rounding function you +need yourself. diff --git a/pod/perlre.pod b/pod/perlre.pod index cb3ce032d0..74a8bd9fd5 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -9,9 +9,10 @@ description of how to I<use> regular expressions in matching operations, plus various examples of the same, see C<m//> and C<s///> in L<perlop>. -The matching operations can -have various modifiers, some of which relate to the interpretation of -the regular expression inside. These are: +The matching operations can have various modifiers. The modifiers +which relate to the interpretation of the regular expression inside +are listed below. For the modifiers that alter the behaviour of the +operation, see L<perlop/"m//"> and L<perlop/"s//">. =over 4 @@ -167,7 +168,7 @@ Perl defines the following zero-width assertions: \G Match only where previous m//g left off A word boundary (C<\b>) is defined as a spot between two characters that -has a C<\w> on one side of it and and a C<\W> on the other side of it (in +has a C<\w> on one side of it and a C<\W> on the other side of it (in either order), counting the imaginary characters off the beginning and end of the string as matching a C<\W>. (Within character classes C<\b> represents backspace rather than a word boundary.) The C<\A> and C<\Z> are @@ -214,6 +215,17 @@ everything after the matched string. Examples: $seconds = $3; } +Once perl sees that you need one of C<$&>, C<$`> or C<$'> anywhere in +the program, it has to provide them on each and every pattern match. +This can slow your program down. The same mechanism that handles +these provides for the use of $1, $2, etc., so you pay the same price +for each regexp that contains capturing parentheses. But if you never +use $&, etc., in your script, then regexps I<without> capturing +parentheses won't be penalized. So avoid $&, $', and $` if you can, +but if you can't (and some algorithms really appreciate them), once +you've used them once, use them at will, because you've already paid +the price. + You will note that all backslashed metacharacters in Perl are alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular expression languages, there are no backslashed symbols that aren't alphanumeric. @@ -326,7 +338,7 @@ When the match runs, the first part of the regular expression (C<\b(foo)>) finds a possible match right at the beginning of the string, and loads up $1 with "Foo". However, as soon as the matching engine sees that there's no whitespace following the "Foo" that it had saved in $1, it realizes its -mistake and starts over again one character after where it had had the +mistake and starts over again one character after where it had the tentative match. This time it goes all the way until the next occurrence of "foo". The complete regular expression matches this time, and you get the expected output of "table follows foo." diff --git a/pod/perlrun.pod b/pod/perlrun.pod index f90e642d40..a2e0764c7b 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -87,6 +87,84 @@ If the script is syntactically correct, it is executed. If the script runs off the end without hitting an exit() or die() operator, an implicit C<exit(0)> is provided to indicate successful completion. +=head2 #! and quoting on non-Unix systems + +Unix's #! technique can be simulated on other systems: + +=over 4 + +=item OS/2 + +Put + + extproc perl -S -your_switches + +as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's +`extproc' handling). + +=item DOS + +Create a batch file to run your script, and codify it in +C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source +distribution for more information). + +=item Win95/NT + +The Win95/NT installation, when using the Activeware port of Perl, +will modify the Registry to associate the .pl extension with the perl +interpreter. If you install another port of Perl, including the one +in the win32 directory of the Perl distribution, then you'll have to +modify the Registry yourself. + +=item Macintosh + +Macintosh perl scripts will have the the appropriate Creator and +Type, so that double-clicking them will invoke the perl application. + +=back + +Command-interpreters on non-Unix systems have rather different ideas +on quoting than Unix shells. You'll need to learn the special +characters in your command-interpreter (C<*>, C<\> and C<"> are +common) and how to protect whitespace and these characters to run +one-liners (see C<-e> below). + +On some systems, you may have to change single-quotes to double ones, +which you must I<NOT> do on Unix or Plan9 systems. You might also +have to change a single % to a %%. + +For example: + + # Unix + perl -e 'print "Hello world\n"' + + # DOS, etc. + perl -e "print \"Hello world\n\"" + + # Mac + print "Hello world\n" + (then Run "Myscript" or Shift-Command-R) + + # VMS + perl -e "print ""Hello world\n""" + +The problem is that none of this is reliable: it depends on the command +tirely possible neither works. If 4DOS was the command shell, this would +probably work better: + + perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" + +CMD.EXE in Windows NT slipped a lot of standard Unix functionality in +when nobody was looking, but just try to find documentation for its +quoting rules. + +Under the Mac, it depends which environment you are using. The MacPerl +shell, or MPW, is much like Unix shells in its support for several +quoting variants, except that it makes free use of the Mac's non-ASCII +characters as control characters. + +There is no general solution to all of this. It's just a mess. + =head2 Switches A single-character switch may be combined with the following switch, if diff --git a/pod/perlsec.pod b/pod/perlsec.pod index 6089431a2a..0d72cf0ca6 100644 --- a/pod/perlsec.pod +++ b/pod/perlsec.pod @@ -287,3 +287,38 @@ SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition. Prior to release 5.003 of Perl, a bug in the code of B<suidperl> could introduce a security hole in systems compiled with strict POSIX compliance. + +=head2 Protecting Your Programs + +There are a number of ways to hide the source to your Perl programs, +with varying levels of "security". + +First of all, however, you I<can't> take away read permission, because +the source code has to be readable in order to be compiled and +interpreted. (That doesn't mean that a CGI script's source is +readable by people on the web, though.) So you have to leave the +permissions at the socially friendly 0755 level. + +Some people regard this as a security problem. If your program does +insecure things, and relies on people not knowing how to exploit those +insecurities, it is not secure. It is often possible for someone to +determine the insecure things and exploit them without viewing the +source. Security through obscurity, the name for hiding your bugs +instead of fixing them, is little security indeed. + +You can try using encryption via source filters (Filter::* from CPAN). +But crackers might be able to decrypt it. You can try using the +byte-code compiler and interpreter described below, but crackers might +be able to de-compile it. You can try using the native-code compiler +described below, but crackers might be able to disassemble it. These +pose varying degrees of difficulty to people wanting to get at your +code, but none can definitively conceal it (this is true of every +language, not just Perl). + +If you're concerned about people profiting from your code, then the +bottom line is that nothing but a restrictive licence will give you +legal security. License your software and pepper it with threatening +statements like "This is unpublished proprietary software of XYZ Corp. +Your access to it does not give you permission to use it blah blah +blah." You should see a lawyer to be sure your licence's wording will +stand up in court. diff --git a/pod/perltoc.pod b/pod/perltoc.pod index eb59cda02e..4e412bd7b8 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -38,6 +38,769 @@ expression enhancements, Innumerable Unbundled Modules, Compilability =item NOTES +=head2 perlfaq - frequently asked questions about Perl ($Date: 1997/03/17 +22:17:56 $) + +=item DESCRIPTION + +perlfaq: Structural overview of the FAQ, L<perlfaq1>: General Questions +About Perl, L<perlfaq2>: Obtaining and Learning about Perl, L<perlfaq3>: +Programming Tools, L<perlfaq4>: Data Manipulation, L<perlfaq5>: Files and +Formats, L<perlfaq6>: Regexps, L<perlfaq7>: General Perl Language Issues, +L<perlfaq8>: System Interaction, L<perlfaq9>: Networking + +=over + +=item Where to get this document + +=item How to contribute to this document + +=item What will happen if you mail your Perl programming problems to the +authors + +=back + +=item Credits + +=item Author and Copyright Information + +=over + +=item Non-commercial Reproduction + +=item Commercial Reproduction + +=item Disclaimer + +=back + +=item Changes + +17/March/97 Version, Initial Release: 11/March/97 + +=head2 perlfaq1 - General Questions About Perl ($Revision: 1.10 $) + +=item DESCRIPTION + +=over + +=item What is Perl? + +=item Who supports Perl? Who develops it? Why is it free? + +=item Which version of Perl should I use? + +=item What are perl4 and perl5? + +=item How stable is Perl? + +=item Is Perl difficult to learn? + +=item How does Perl compare with other languages like Java, Python, REXX, +Scheme, or Tcl? + +=item Can I do [task] in Perl? + +=item When shouldn't I program in Perl? + +=item What's the difference between "perl" and "Perl"? + +=item Is it a Perl program or a Perl script? + +=item What is a JAPH? + +=item Where can I get a list of Larry Wall witticisms? + +=item How can I convince my sysadmin/supervisor/employees to use version +(5/5.004/Perl instead of some other language)? + +=back + +=item AUTHOR AND COPYRIGHT + +=head2 perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.13 $) + +=item DESCRIPTION + +=over + +=item What machines support Perl? Where do I get it? + +=item How can I get a binary version of Perl? + +=item I copied the Perl binary from one machine to another, but scripts +don't work. + +=item I grabbed the sources and tried to compile but gdbm/dynamic +loading/malloc/linking/... failed. How do I make it work? + +=item What modules and extensions are available for Perl? What is CPAN? +What does CPAN/src/... mean? + +=item Is there an ISO or ANSI certified version of Perl? + +=item Where can I get information on Perl? + +=item What are the Perl newsgroups on USENET? Where do I post questions? + +=item Where should I post source code? + +=item Perl Books + +=item Perl in Magazines + +=item Perl on the Net: FTP and WWW Access + +=item What mailing lists are there for perl? + +MacPerl, Perl5-Porters, NTPerl, Perl-Packrats + +=item Archives of comp.lang.perl.misc + +=item Perl Training + +=item Where can I buy a commercial version of Perl? + +=item Where do I send bug reports? + +=item What is perl.com? perl.org? The Perl Institute? + +=item How do I learn about object-oriented Perl programming? + +=back + +=item AUTHOR AND COPYRIGHT + +=head2 perlfaq3 - Programming Tools ($Revision: 1.19 $) + +=item DESCRIPTION + +=over + +=item How do I do (anything)? + +=item How can I use Perl interactively? + +=item Is there a Perl shell? + +=item How do I debug my Perl programs? + +=item How do I profile my Perl programs? + +=item How do I cross-reference my Perl programs? + +=item Is there a pretty-printer (formatter) for Perl? + +=item Is there a ctags for Perl? + +=item Where can I get Perl macros for vi? + +=item Where can I get perl-mode for emacs? + +=item How can I use curses with Perl? + +=item How can I use X or Tk with Perl? + +=item How can I generate simple menus without using CGI or Tk? + +=item Can I dynamically load C routines into Perl? + +=item What is undump? + +=item How can I make my Perl program run faster? + +=item How can I make my Perl program take less memory? + +=item Is it unsafe to return a pointer to local data? + +=item How can I free an array or hash so my program shrinks? + +=item How can I make my CGI script more efficient? + +=item How can I hide the source for my Perl program? + +=item How can I compile my Perl program into byte-code or C? + +=item How can I get '#!perl' to work on [MSDOS,NT,...]? + +=item Can I write useful perl programs on the command line? + +=item Why don't perl one-liners work on my DOS/Mac/VMS system? + +=item Where can I learn about CGI or Web programming in Perl? + +=item Where can I learn about object-oriented Perl programming? + +=item Where can I learn about linking C with Perl? [h2xs, xsubpp] + +=item I've read perlembed, perlguts, etc., but I can't embed perl in +my C program, what am I doing wrong? + +=item When I tried to run my script, I got this message. What does it +mean? + +=item What's MakeMaker? + +=back + +=item AUTHOR AND COPYRIGHT + +=head2 perlfaq4 - Data Manipulation ($Revision: 1.15 $) + +=item DESCRIPTION + +=item Data: Numbers + +=over + +=item Why isn't my octal data interpreted correctly? + +=item Does perl have a round function? What about ceil() and floor()? +Trig functions? + +=item How do I convert bits into ints? + +=item How do I multiply matrices? + +=item How do I perform an operation on a series of integers? + +=item How can I output Roman numerals? + +=item Why aren't my random numbers random? + +=back + +=item Data: Dates + +=over + +=item How do I find the week-of-the-year/day-of-the-year? + +=item How can I compare two date strings? + +=item How can I take a string and turn it into epoch seconds? + +=item How can I find the Julian Day? + +=item Does Perl have a year 2000 problem? + +=back + +=item Data: Strings + +=over + +=item How do I validate input? + +=item How do I unescape a string? + +=item How do I remove consecutive pairs of characters? + +=item How do I expand function calls in a string? + +=item How do I find matching/nesting anything? + +=item How do I reverse a string? + +=item How do I expand tabs in a string? + +=item How do I reformat a paragraph? + +=item How can I access/change the first N letters of a string? + +=item How do I change the Nth occurrence of something? + +=item How can I count the number of occurrences of a substring within a +string? + +=item How do I capitalize all the words on one line? + +=item How can I split a [character] delimited string except when inside +[character]? (Comma-separated files) + +=item How do I strip blank space from the beginning/end of a string? + +=item How do I extract selected columns from a string? + +=item How do I find the soundex value of a string? + +=item How can I expand variables in text strings? + +=item What's wrong with always quoting "$vars"? + +=item Why don't my <<HERE documents work? + +1. There must be no space after the << part, 2. There (probably) should be +a semicolon at the end, 3. You can't (easily) have any space in front of +the tag + +=back + +=item Data: Arrays + +=over + +=item What is the difference between $array[1] and @array[1]? + +=item How can I extract just the unique elements of an array? + +a) If @in is sorted, and you want @out to be sorted:, b) If you don't know +whether @in is sorted:, c) Like (b), but @in contains only small integers:, +d) A way to do (b) without any loops or greps:, e) Like (d), but @in +contains only small positive integers: + +=item How can I tell whether an array contains a certain element? + +=item How do I compute the difference of two arrays? How do I compute the +intersection of two arrays? + +=item How do I find the first array element for which a condition is true? + +=item How do I handle linked lists? + +=item How do I handle circular lists? + +=item How do I shuffle an array randomly? + +=item How do I process/modify each element of an array? + +=item How do I select a random element from an array? + +=item How do I permute N elements of a list? + +=item How do I sort an array by (anything)? + +=item How do I manipulate arrays of bits? + +=item Why does defined() return true on empty arrays and hashes? + +=back + +=item Data: Hashes (Associative Arrays) + +=over + +=item How do I process an entire hash? + +=item What happens if I add or remove keys from a hash while iterating over +it? + +=item How do I look up a hash element by value? + +=item How can I know how many entries are in a hash? + +=item How do I sort a hash (optionally by value instead of key)? + +=item How can I always keep my hash sorted? + +=item What's the difference between "delete" and "undef" with hashes? + +=item Why don't my tied hashes make the defined/exists distinction? + +=item How do I reset an each() operation part-way through? + +=item How can I get the unique keys from two hashes? + +=item How can I store a multidimensional array in a DBM file? + +=item How can I make my hash remember the order I put elements into it? + +=item Why does passing a subroutine an undefined element in a hash create +it? + +=item How can I make the Perl equivalent of a C structure/C++ class/hash +or array of hashes or arrays? + +=item How can I use a reference as a hash key? + +=back + +=item Data: Misc + +=over + +=item How do I handle binary data correctly? + +=item How do I determine whether a scalar is a number/whole/integer/float? + +=item How do I keep persistent data across program calls? + +=item How do I print out or copy a recursive data structure? + +=item How do I define methods for every class/object? + +=item How do I verify a credit card checksum? + +=back + +=item AUTHOR AND COPYRIGHT + +=head2 perlfaq5 - Files and Formats ($Revision: 1.19 $) + +=item DESCRIPTION + +=over + +=item How do I flush/unbuffer a filehandle? Why must I do this? + +=item 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? + +=item How do I count the number of lines in a file? + +=item How do I make a temporary file name? + +=item How can I manipulate fixed-record-length files? + +=item 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? + +=item How can I set up a footer format to be used with write()? + +=item How can I write() into a string? + +=item How can I output my numbers with commas added? + +=item How can I translate tildes (~) in a filename? + +=item How come when I open the file read-write it wipes it out? + +=item Why do I sometimes get an "Argument list too long" when I use <*>? + +=item Is there a leak/bug in glob()? + +=item How can I open a file with a leading "E<gt>" or trailing blanks? + +=item How can I reliably rename a file? + +=item How can I lock a file? + +=item What can't I just open(FH, ">file.lock")? + +=item I still don't get locking. I just want to increment the number +in the file. How can I do this? + +=item How do I randomly update a binary file? + +=item How do I get a file's timestamp in perl? + +=item How do I set a file's timestamp in perl? + +=item How do I print to more than one file at once? + +=item How can I read in a file by paragraphs? + +=item How can I read a single character from a file? From the keyboard? + +=item How can I tell if there's a character waiting on a filehandle? + +=item How do I open a file without blocking? + +=item How do I create a file only if it doesn't exist? + +=item How do I do a C<tail -f> in perl? + +=item How do I dup() a filehandle in Perl? + +=item How do I close a file descriptor by number? + +=item Why can't I use "C:\temp\foo" in DOS paths? What doesn't +`C:\temp\foo.exe` work? + +=item Why doesn't glob("*.*") get all the files? + +=item Why does Perl let me delete read-only files? Why does C<-i> clobber +protected files? Isn't this a bug in Perl? + +=item How do I select a random line from a file? + +=back + +=item AUTHOR AND COPYRIGHT + +=head2 perlfaq6 - Regexps ($Revision: 1.14 $) + +=item DESCRIPTION + +=over + +=item How can I hope to use regular expressions without creating illegible +and unmaintainable code? + +Comments Outside the Regexp, Comments Inside the Regexp, Different +Delimiters + +=item I'm having trouble matching over more than one line. What's wrong? + +=item How can I pull out lines between two patterns that are themselves on +different lines? + +=item I put a regular expression into $/ but it didn't work. What's wrong? + +=item How do I substitute case insensitively on the LHS, but preserving +case on the RHS? + +=item How can I make C<\w> match accented characters? + +=item How can I match a locale-smart version of C</[a-zA-Z]/>? + +=item How can I quote a variable to use in a regexp? + +=item What is C</o> really for? + +=item How do I use a regular expression to strip C style comments from a +file? + +=item Can I use Perl regular expressions to match balanced text? + +=item What does it mean that regexps are greedy? How can I get around it? + +=item How do I process each word on each line? + +=item How can I print out a word-frequency or line-frequency summary? + +=item How can I do approximate matching? + +=item How do I efficiently match many regular expressions at once? + +=item Why don't word-boundary searches with C<\b> work for me? + +=item Why does using $&, $`, or $' slow my program down? + +=item What good is C<\G> in a regular expression? + +=item Are Perl regexps DFAs or NFAs? Are they POSIX compliant? + +=item What's wrong with using grep or map in a void context? + +=item How can I match strings with multi-byte characters? + +=back + +=item AUTHOR AND COPYRIGHT + +=head2 perlfaq7 - Perl Language Issues ($Revision: 1.15 $) + +=item DESCRIPTION + +=over + +=item Can I get a BNF/yacc/RE for the Perl language? + +=item What are all these $@%* punctuation signs, and how do I know when to +use them? + +=item Do I always/never have to quote my strings or use semicolons and +commas? + +=item How do I skip some return values? + +=item How do I temporarily block warnings? + +=item What's an extension? + +=item Why do Perl operators have different precedence than C operators? + +=item How do I declare/create a structure? + +=item How do I create a module? + +=item How do I create a class? + +=item How can I tell if a variable is tainted? + +=item What's a closure? + +=item How can I pass/return a {Function, FileHandle, Array, Hash, Method, +Regexp}? + +Passing Variables and Functions, Passing Filehandles, Passing Regexps, +Passing Methods + +=item How do I create a static variable? + +=item What's the difference between dynamic and lexical (static) scoping? +Between local() and my()? + +=item How can I access a dynamic variable while a similarly named lexical +is in scope? + +=item What's the difference between deep and shallow binding? + +=item Why doesn't "local($foo) = <FILE>;" work right? + +=item How do I redefine a built-in function, operator, or method? + +=item What's the difference between calling a function as &foo and foo()? + +=item How do I create a switch or case statement? + +=item How can I catch accesses to undefined variables/functions/methods? + +=item Why can't a method included in this same file be found? + +=item How can I find out my current package? + +=back + +=item AUTHOR AND COPYRIGHT + +=head2 perlfaq8 - System Interaction ($Revision: 1.15 $) + +=item DESCRIPTION + +=over + +=item How do I find out which operating system I'm running under? + +=item How come exec() doesn't return? + +=item How do I do fancy stuff with the keyboard/screen/mouse? + +Keyboard, Screen, Mouse + +=item How do I ask the user for a password? + +=item How do I read and write the serial port? + +lockfiles, open mode, end of line, flushing output, non-blocking input + +=item How do I decode encrypted password files? + +=item How do I start a process in the background? + +STDIN, STDOUT and STDERR are shared, Signals, Zombies + +=item How do I trap control characters/signals? + +=item How do I modify the shadow password file on a Unix system? + +=item How do I set the time and date? + +=item How can I sleep() or alarm() for under a second? + +=item How can I measure time under a second? + +=item How can I do an atexit() or setjmp()/longjmp()? (Exception handling) + +=item Why doesn't my sockets program work under System V (Solaris)? What +does the error message "Protocol not supported" mean? + +=item How can I call my system's unique C functions from Perl? + +=item Where do I get the include files to do ioctl() or syscall()? + +=item Why do setuid perl scripts complain about kernel problems? + +=item How can I open a pipe both to and from a command? + +=item How can I capture STDERR from an external command? + +=item Why doesn't open() return an error when a pipe open fails? + +=item What's wrong with using backticks in a void context? + +=item How can I call backticks without shell processing? + +=item Why can't my script read from STDIN after I gave it EOF (^D on Unix, +^Z on MSDOS)? + +=item How can I convert my shell script to perl? + +=item Can I use perl to run a telnet or ftp session? + +=item How can I write expect in Perl? + +=item Is there a way to hide perl's command line from programs such as +"ps"? + +=item I {changed directory, modified my environment} in a perl script. How +come the change disappeared when I exited the script? How do I get my +changes to be visible? + +Unix, VMS + +=item How do I close a process's filehandle without waiting for it to +complete? + +=item How do I fork a daemon process? + +=item How do I make my program run with sh and csh? + +=item How do I keep my own module/library directory? + +=item How do I find out if I'm running interactively or not? + +=item How do I timeout a slow event? + +=item How do I set CPU limits? + +=item How do I avoid zombies on a Unix system? + +=item How do I use an SQL database? + +=item How do I make a system() exit on control-C? + +=item How do I open a file without blocking? + +=item How do I install a CPAN module? + +=back + +=item AUTHOR AND COPYRIGHT + +=head2 perlfaq9 - Networking ($Revision: 1.13 $) + +=item DESCRIPTION + +=over + +=item My CGI script runs from the command line but not the browser. Can +you help me fix it? + +=item How do I remove HTML from a string? + +=item How do I extract URLs? + +=item How do I download a file from the user's machine? How do I open a +file on another machine? + +=item How do I make a pop-up menu in HTML? + +=item How do I fetch an HTML file? + +=item how do I decode or create those %-encodings on the web? + +=item How do I redirect to another page? + +=item How do I put a password on my web pages? + +=item How do I edit my .htpasswd and .htgroup files with Perl? + +=item How do I parse an email header? + +=item How do I decode a CGI form? + +=item How do I check a valid email address? + +=item How do I decode a MIME/BASE64 string? + +=item How do I return the user's email address? + +=item How do I send/read mail? + +=item How do I find out my hostname/domainname/IP address? + +=item How do I fetch a news article or the active newsgroups? + +=item How do I fetch/put an FTP file? + +=item How can I do RPC in Perl? + +=back + +=item AUTHOR AND COPYRIGHT + =head2 perldelta - what's new for perl5.004 =item DESCRIPTION @@ -50,14 +813,18 @@ expression enhancements, Innumerable Unbundled Modules, Compilability =item Compilation Option: Binary Compatibility With 5.003 -=item Subroutine Parameters Are Not Autovivified +=item No Autovivification of Subroutine Parameters =item Fixed Parsing of $$<digit>, &$<digit>, etc. +=item No Resetting of $. on Implicit Close + =item Changes to Tainting Checks =item New Opcode Module and Revised Safe Module +=item Embedding Improvements + =item Internal Change: FileHandle Class Based on IO::* Classes =item Internal Change: PerlIO internal IO abstraction interface @@ -285,6 +1052,8 @@ y/SEARCHLIST/REPLACEMENTLIST/cds =item Integer Arithmetic +=item Floating-point Arithmetic + =back =head2 perlre - Perl regular expressions @@ -315,6 +1084,10 @@ i, m, s, x =over +=item #! and quoting on non-Unix systems + +OS/2, DOS, Win95/NT, Macintosh + =item Switches B<-0>[I<digits>], B<-a>, B<-c>, B<-d>, B<-d:>I<foo>, B<-D>I<number>, @@ -452,7 +1225,7 @@ $EFFECTIVE_USER_ID, $EUID, $>, $REAL_GROUP_ID, $GID, $(, $EFFECTIVE_GROUP_ID, $EGID, $), $PROGRAM_NAME, $0, $[, $PERL_VERSION, $], $DEBUGGING, $^D, $SYSTEM_FD_MAX, $^F, $^H, $INPLACE_EDIT, $^I, $OSNAME, $^O, $PERLDB, $^P, $BASETIME, $^T, $WARNING, $^W, $EXECUTABLE_NAME, $^X, -$ARGV, @ARGV, @INC, %INC, $ENV{expr}, $SIG{expr} +$ARGV, @ARGV, @INC, %INC, $ENV{expr}, $SIG{expr}, $^M =back @@ -1017,6 +1790,12 @@ safe subprocesses, sockets, and semaphores) =over +=item Filehandles + +=item Background Processes + +=item Complete Dissociation of Child from Parent + =item Safe Pipe Opens =item Bidirectional Communication @@ -1115,6 +1894,8 @@ Prompt, Multi-line commands, Stack backtrace, Listing, Frame listing =item Security Bugs +=item Protecting Your Programs + =back =head2 perltrap - Perl traps for the unwary @@ -1144,7 +1925,7 @@ Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps Discontinuance, Deprecation, BugFix, Discontinuance, Discontinuance, Discontinuance, BugFix, Discontinuance, Discontinuance, BugFix, -Discontinuance, Deprecation, Discontinuance +Discontinuance, Discontinuance, Deprecation, Discontinuance =item Parsing Traps @@ -1172,7 +1953,7 @@ Precedence Regular Expression, Regular Expression, Regular Expression, Regular Expression, Regular Expression, Regular Expression, Regular Expression, -Regular Expression +Regular Expression, Regular Expression =item Subroutine, Signal, Sorting Traps @@ -1471,7 +2252,7 @@ B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)> =over -=item XSUB's and the Argument Stack +=item XSUBs and the Argument Stack =item Calling Perl Routines from within C Programs @@ -1512,10 +2293,10 @@ av_shift, av_store, av_undef, av_unshift, CLASS, Copy, croak, CvSTASH, DBsingle, DBsub, DBtrace, dMARK, dORIGMARK, dowarn, dSP, dXSARGS, dXSI32, dXSI32, ENTER, EXTEND, FREETMPS, G_ARRAY, G_DISCARD, G_EVAL, GIMME, G_NOARGS, G_SCALAR, gv_fetchmeth, gv_fetchmethod, gv_stashpv, gv_stashsv, -GvSV, he_delayfree, HEf_SVKEY, he_free, HeHASH, HeKEY, HeKLEN, HePV, -HeSVKEY, HeSVKEY_force, HeSVKEY_set, HeVAL, hv_clear, hv_delete, -hv_delete_ent, hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, -hv_iterinit, hv_iterkey, hv_iterkeysv +GvSV, HEf_SVKEY, HeHASH, HeKEY, HeKLEN, HePV, HeSVKEY, HeSVKEY_force, +HeSVKEY_set, HeVAL, hv_clear, hv_delayfree_ent, hv_delete, hv_delete_ent, +hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, hv_free_ent, hv_iterinit, +hv_iterkey, hv_iterkeysv Returns the key as an C<SV*> from the current position of the hash iterator. The return value will always be a mortal copy of the key. Also see C<hv_iterinit>, hv_iternext, hv_iternextsv, hv_iterval, @@ -1632,6 +2413,20 @@ callback =head1 PRAGMA DOCUMENTATION +=head2 autouse - postpone load of modules until a function is used + +=item SYNOPSIS + +=item DESCRIPTION + +=item WARNING + +=item BUGS + +=item AUTHOR + +=item SEE ALSO + =head2 blib - Use MakeMaker's uninstalled version of a package =item SYNOPSIS @@ -2030,7 +2825,7 @@ B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO> =over -=item How does DB_File interface to Berkeley DB? +=item Interface to Berkeley DB =item Opening a Berkeley DB Database File @@ -2044,7 +2839,7 @@ B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO> =over -=item A Simple Example. +=item A Simple Example =back @@ -2054,9 +2849,9 @@ B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO> =item Changing the BTREE sort order -=item Handling duplicate keys +=item Handling Duplicate Keys -=item The get_dup method. +=item The get_dup() Method =item Matching Partial Keys @@ -2066,7 +2861,7 @@ B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO> =over -=item The bval option +=item The 'bval' Option =item A Simple Example @@ -2092,9 +2887,9 @@ $value, $flags) ;>, B<$status = $X-E<gt>sync([$flags]) ;> =item Locking Databases -=item Sharing databases with C applications +=item Sharing Databases With C Applications -=item The untie gotcha +=item The untie() Gotcha =back @@ -2183,6 +2978,23 @@ variables =back +=head2 ExtUtils::Command - utilities to replace common UNIX commands in +Makefiles etc. + +=item SYNOPSYS + +=item DESCRIPTION + +cat, eqtime src dst, rm_f files..., rm_f files..., touch files .., mv +source... destination, cp source... destination, chmod mode files.., mkpath +directory.., test_f file + +=item BUGS + +=item SEE ALSO + +=item AUTHOR + =head2 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications =item SYNOPSIS @@ -2276,7 +3088,7 @@ post_initialize (o), postamble (o), prefixify, processPL (o), realclean (o), replace_manpage_separator, static (o), static_lib (o), staticmake (o), subdir_x (o), subdirs (o), test (o), test_via_harness (o), test_via_script (o), tool_autosplit (o), tools_other (o), tool_xsubpp (o), top_targets (o), -writedoc, xs_c (o), xs_o (o) +writedoc, xs_c (o), xs_o (o), perl_archive, export_list =back @@ -2316,6 +3128,17 @@ dist_dir (override), dist_test (override), install (override), perldepend =back +=head2 ExtUtils::MM_Win32 - methods to override UN*X behaviour in +ExtUtils::MakeMaker + +=item SYNOPSIS + +=item DESCRIPTION + +catfile, static_lib (o), dynamic_lib (o), canonpath, perl_script, +pm_to_blib, test_via_harness (o), tool_autosplit (override), tools_other +(o), manifypods (o), dist_ci (o), dist_core (o), pasthru (o) + =head2 ExtUtils::MakeMaker - create an extension Makefile =item SYNOPSIS @@ -2951,7 +3774,7 @@ functions =item BUGS -=item AUTHOR +=item AUTHORS =head2 NDBM_File - Tied access to ndbm files diff --git a/pod/perltoot.pod b/pod/perltoot.pod index 41a9a5fd11..a8a77f1c68 100644 --- a/pod/perltoot.pod +++ b/pod/perltoot.pod @@ -268,7 +268,7 @@ Destruction happens automatically via Perl's garbage collection (GC) system, which is a quick but somewhat lazy reference-based GC system. To know what to call, Perl insists that the destructor be named DESTROY. -Why is DESTROY in all caps? Perl on occasion uses purely upper-case +Why is DESTROY in all caps? Perl on occasion uses purely uppercase function names as a convention to indicate that the function will be automatically called by Perl in some way. Others that are called implicitly include BEGIN, END, AUTOLOAD, plus all methods used by @@ -886,7 +886,7 @@ This is a form of Laziness. (Getting polymorphed is also what happens when the wizard decides you'd look better as a frog.) Every now and then you'll want to have a method call trigger both its -derived class (also know as "subclass") version as well as its base class +derived class (also known as "subclass") version as well as its base class (also known as "superclass") version. In practice, constructors and destructors are likely to want to do this, and it probably also makes sense in the debug() method we showed previously. @@ -1112,7 +1112,7 @@ class) has a package global called $VERSION that's high enough, as in: $his_vers = $ob->VERSION(); However, we don't usually call VERSION ourselves. (Remember that an all -upper-case function name is a Perl convention that indicates that the +uppercase function name is a Perl convention that indicates that the function will be automatically used by Perl in some way.) In this case, it happens when you say @@ -1163,7 +1163,7 @@ instead of a hash reference to represent the object. sub new { my $self = []; $self->[$NAME] = undef; # this is unnecessary - $self->[$AGE] = undef; # as it this + $self->[$AGE] = undef; # as is this $self->[$PEERS] = []; # but this isn't, really bless($self); return $self; @@ -1623,7 +1623,7 @@ You can look at other object-based, struct-like overrides of core functions in the 5.004 release of Perl in File::stat, Net::hostent, Net::netent, Net::protoent, Net::servent, Time::gmtime, Time::localtime, User::grent, and User::pwent. These modules have a final component -that's all lower-case, by convention reserved for compiler pragmas, +that's all lowercase, by convention reserved for compiler pragmas, because they affect the compilation and change a built-in function. They also have the type names that a C programmer would most expect. diff --git a/pod/perltrap.pod b/pod/perltrap.pod index 17c576df2f..fd91182d1e 100644 --- a/pod/perltrap.pod +++ b/pod/perltrap.pod @@ -273,7 +273,7 @@ context than they do in a scalar one. See L<perldata> for details. =item * -Avoid barewords if you can, especially all lower-case ones. +Avoid barewords if you can, especially all lowercase ones. You can't tell by just looking at it whether a bareword is a function or a string. By using quotes on strings and parentheses on function calls, you won't ever get them confused. @@ -578,6 +578,24 @@ number of elements in the resulting list. # perl4 prints: second new # perl5 prints: 3 +=item * Discontinuance + +In Perl 4 (and versions of Perl 5 before 5.004), C<'\r'> characters in +Perl code were silently allowed, although they could cause (mysterious!) +failures in certain constructs, particularly here documents. Now, +C<'\r'> characters cause an immediate fatal error. (Note: In this +example, the notation B<\015> represents the incorrect line +ending. Depending upon your text viewer, it will look different.) + + print "foo";\015 + print "bar"; + + # perl4 prints: foobar + # perl5.003 prints: foobar + # perl5.004 dies: Illegal character \015 (carriage return) + +See L<perldiag> for full details. + =item * Deprecation Some error messages will be different. @@ -1031,6 +1049,24 @@ state of the searched string is lost) =item * Regular Expression +Currently, if you use the C<m//o> qualifier on a regular expression +within an anonymous sub, I<all> closures generated from that anonymous +sub will use the regular expression as it was compiled when it was used +the very first time in any such closure. For instance, if you say + + sub build_match { + my($left,$right) = @_; + return sub { $_[0] =~ /$left stuff $right/o; }; + } + +build_match() will always return a sub which matches the contents of +C<$left> and C<$right> as they were the I<first> time that build_match() +was called, not as they are in the current call. + +This is probably a bug, and may change in future versions of Perl. + +=item * Regular Expression + If no parentheses are used in a match, Perl4 sets C<$+> to the whole match, just like C<$&>. Perl5 does not. diff --git a/pod/perlvar.pod b/pod/perlvar.pod index d072d25df9..1406858331 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -213,6 +213,9 @@ delimit line boundaries when quoting poetry.) $_ = <FH>; # whole file now here s/\n[ \t]+/ /g; +Remember: the value of $/ is a string, not a regexp. AWK has to be +better for something :-) + =item autoflush HANDLE EXPR =item $OUTPUT_AUTOFLUSH @@ -740,4 +743,18 @@ The C<__DIE__> handler is explicitly disabled during the call, so that you can die from a C<__DIE__> handler. Similarly for C<__WARN__>. See L<perlfunc/die>, L<perlfunc/warn> and L<perlfunc/eval>. +=item $^M + +By default, running out of memory it is not trappable. However, if +compiled for this, Perl may use the contents of C<$^M> as an emergency +pool after die()ing with this message. Suppose that your Perl were +compiled with -DEMERGENCY_SBRK and used Perl's malloc. Then + + $^M = 'a' x (1<<16); + +would allocate a 64K buffer for use when in emergency. See the F<INSTALL> +file for information on how to enable this option. As a disincentive to +casual use of this advanced feature, there is no L<English> long name for +this variable. + =back diff --git a/pod/perlxs.pod b/pod/perlxs.pod index bc2cce1cfa..ebead849dc 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -731,7 +731,7 @@ prototypes. =head2 The ALIAS: Keyword -The ALIAS: keyword allows an XSUB to have two more more unique Perl names +The ALIAS: keyword allows an XSUB to have two more unique Perl names and to know which of those names was used when it was invoked. The Perl names may be fully-qualified with package names. Each alias is given an index. The compiler will setup a variable called C<ix> which contain the diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod index 7b9b7c60f5..e31de334a8 100644 --- a/pod/perlxstut.pod +++ b/pod/perlxstut.pod @@ -452,7 +452,7 @@ this behavior is tolerated. The next example will show how to do this. =head2 EXAMPLE 4 -In this example, we'll now begin to write XSUB's that will interact with +In this example, we'll now begin to write XSUBs that will interact with pre-defined C libraries. To begin with, we will build a small library of our own, then let h2xs write our .pm and .xs files for us. diff --git a/pod/roffitall b/pod/roffitall index 2d00bdc666..817a8cfe3b 100755 --- a/pod/roffitall +++ b/pod/roffitall @@ -63,6 +63,16 @@ toroff=` $mandir/perlembed.1 \ $mandir/perlpod.1 \ $mandir/perlbook.1 \ + $mandir/perlfaq.1 \ + $mandir/perlfaq1.1 \ + $mandir/perlfaq2.1 \ + $mandir/perlfaq3.1 \ + $mandir/perlfaq4.1 \ + $mandir/perlfaq5.1 \ + $mandir/perlfaq6.1 \ + $mandir/perlfaq7.1 \ + $mandir/perlfaq8.1 \ + $mandir/perlfaq9.1 \ \ $libdir/blib.3 \ $libdir/diagnostics.3 \ |