From: Gurusamy Sarathy Date: Sat, 17 Jul 1999 16:34:09 +0000 (+0000) Subject: pod fixes (with minor edits) from Abigail, Ronald Kimball, Jon X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=87275199ef473a0bd08ce6f46db30d4d432f4876;p=p5sagit%2Fp5-mst-13.2.git pod fixes (with minor edits) from Abigail, Ronald Kimball, Jon Waddington, Tuomas Lukka, Steven Tolkin, Ian Phillipps, and Steve Lidie p4raw-id: //depot/perl@3676 --- diff --git a/pod/Win32.pod b/pod/Win32.pod index a0bf040..dfc78bd 100644 --- a/pod/Win32.pod +++ b/pod/Win32.pod @@ -121,7 +121,7 @@ convert 8.3 components in the supplied FILENAME to longnames or vice-versa. Compare with Win32::GetShortPathName and Win32::GetLongPathName. -This function has been added for Perl 5.006. +This function has been added for Perl 5.6. =item Win32::GetLastError() @@ -137,7 +137,7 @@ than PATHNAME. No attempt is made to convert PATHNAME to the absolute path. Compare with Win32::GetShortPathName and Win32::GetFullPathName. -This function has been added for Perl 5.006. +This function has been added for Perl 5.6. =item Win32::GetNextAvailDrive() @@ -259,7 +259,7 @@ such a feature is not available under Windows 95. [CORE] Sets the value of the last error encountered to ERROR. This is that value that will be returned by the Win32::GetLastError() -function. This functions has been added for Perl 5.006. +function. This functions has been added for Perl 5.6. =item Win32::Sleep(TIME) diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 0a33e3d..dc697e6 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -1,6 +1,6 @@ =head1 NAME -perldelta - what's new for perl5.006 (as of 5.005_56) +perldelta - what's new for perl v5.6 (as of v5.5.58) =head1 DESCRIPTION @@ -19,7 +19,7 @@ None known at this time. =item C Release 5.005 grandfathered old global symbol names by providing preprocessor -macros for extension source compatibility. As of release 5.006, these +macros for extension source compatibility. As of release 5.6, these preprocessor definitions are not available by default. You need to explicitly compile perl with C<-DPERL_POLLUTE> to get these definitions. For extensions still using the old symbols, this option can be @@ -40,7 +40,7 @@ be called in programs that used Perl's malloc. Previous versions of Perl have allowed this behaviour to be suppressed with the HIDEMYMALLOC and EMBEDMYMALLOC preprocessor definitions. -As of release 5.006, Perl's malloc family of functions have default names +As of release 5.6, Perl's malloc family of functions have default names distinct from the system versions. You need to explicitly compile perl with C<-DPERL_POLLUTE_MALLOC> to get the older behaviour. HIDEMYMALLOC and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod index 56cf3d7..0d5dae8 100644 --- a/pod/perlfaq.pod +++ b/pod/perlfaq.pod @@ -766,7 +766,7 @@ in respect of this information or its use. =item 23/May/99 -Extensive updates from the net in preparation for 5.006 release. +Extensive updates from the net in preparation for 5.6 release. =item 13/April/99 diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod index 7566bf5..a55d38d 100644 --- a/pod/perlfaq1.pod +++ b/pod/perlfaq1.pod @@ -36,8 +36,8 @@ 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 -nntp://news.perl.com/perl.porters-gw/ and the Deja News archive at -http://www.dejanews.com/ using the perl.porters-gw newsgroup, or you can +nntp://news.perl.com/perl.porters-gw/ and the Deja archive at +http://www.deja.com/ using the perl.porters-gw newsgroup, or you can subscribe to the mailing list by sending perl5-porters-request@perl.org a subscription request. @@ -125,8 +125,8 @@ and the rare new keyword). No, Perl is easy to start learning -- and easy to keep learning. It looks like most programming languages you're likely to have experience -with, so if you've ever written an C program, an awk script, a shell -script, or even BASIC program, you're already part way there. +with, so if you've ever written a C program, an awk script, a shell +script, or even a BASIC program, 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 @@ -213,8 +213,8 @@ 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. But never -write "PERL", because perl isn't really an acronym, aprocryphal +OK, while "awk and Perl" and "Python and perl" do not. But never +write "PERL", because perl isn't really an acronym, apocryphal folklore and post-facto expansions notwithstanding. =head2 Is it a Perl program or a Perl script? @@ -223,7 +223,7 @@ Larry doesn't really care. He says (half in jest) that "a script is what you give the actors. A program is what you give the audience." Originally, a script was a canned sequence of normally interactive -commands, that is, a chat script. Something like a uucp or ppp chat +commands, that is, a chat script. Something like a UUCP or PPP chat script or an expect script fits the bill nicely, as do configuration scripts run by a program at its start up, such F<.cshrc> or F<.ircrc>, for example. Chat scripts were just drivers for existing programs, @@ -247,7 +247,7 @@ a definitive answer here. Now that "script" and "scripting" are terms that have been seized by unscrupulous or unknowing marketeers for their own nefarious purposes, they have begun to take on strange and often pejorative meanings, -like "non serious" or "not real programming". Consequently, some perl +like "non serious" or "not real programming". Consequently, some Perl programmers prefer to avoid them altogether. =head2 What is a JAPH? @@ -269,7 +269,7 @@ Newer examples can be found by perusing Larry's postings: =head2 How can I convince my sysadmin/supervisor/employees to use version (5/5.005/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 +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 @@ -295,21 +295,21 @@ 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 +(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.005 release, although 5.004 isn't that bad. Several important bugs were fixed from the 5.000 through 5.003 versions, though, so try upgrading past them if possible. -Of particular note is the massive bughunt for buffer overflow +Of particular note is the massive bug hunt for buffer overflow problems that went into the 5.004 release. All releases prior to that, including perl4, are considered insecure and should be upgraded as soon as possible. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997, 1998, 1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as an integrated part of the Standard Distribution @@ -317,7 +317,7 @@ of Perl or of its documentation (printed or otherwise), this works is covered under Perl's Artistic Licence. For separate distributions of all or part of this FAQ outside of that, see L. -Irrespective of its distribution, all code examples here are public +Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod index 26865c7..d5bbb56 100644 --- a/pod/perlfaq2.pod +++ b/pod/perlfaq2.pod @@ -17,7 +17,7 @@ in standard Internet format (a gzipped archive in POSIX tar format). Perl builds and runs on a bewildering number of platforms. Virtually all known and current Unix derivatives are supported (Perl's native -platform), as are proprietary systems like VMS, DOS, OS/2, Windows, +platform), as are other systems like VMS, DOS, OS/2, Windows, QNX, BeOS, and the Amiga. There are also the beginnings of support for MPE/iX. @@ -45,11 +45,12 @@ Some URLs that might help you are: http://www.perl.com/latest/ http://www.perl.com/CPAN/ports/ -Someone looking for a Perl for Win16 might look to LMOLNAR's djgpp +Someone looking for a Perl for Win16 might look to Laszlo Molnar's djgpp port in http://www.perl.com/CPAN/ports/msdos/ , which comes with clear installation instructions. A simple installation guide for MS-DOS using -IlyaZ's OS/2 port is available at http://www.cs.ruu.nl/~piet/perl5dos.html -and similarly for Windows 3.1 at http://www.cs.ruu.nl/~piet/perlwin3.html . +Ilya Zakharevich's OS/2 port is available at +http://www.cs.ruu.nl/%7Epiet/perl5dos.html +and similarly for Windows 3.1 at http://www.cs.ruu.nl/%7Epiet/perlwin3.html . =head2 I don't have a C compiler on my system. How can I compile perl? @@ -74,7 +75,7 @@ the hard-coded @INC which perl is looking for. 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. @INC is also printed as +symbolic links, aliases, or shortcuts appropriately. @INC is also printed as part of the output of % perl -V @@ -111,7 +112,7 @@ 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 +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, @@ -127,13 +128,13 @@ 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 +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 if you're on a system resembling Unix. This will lead you to other important man pages, including how to set your $MANPATH. 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. +proper Perl installations have fully-accessible documentation. You might also try C in case your system doesn't have a proper man command, or it's been misinstalled. If that doesn't @@ -157,7 +158,7 @@ assistance: http://language.perl.com/info/documentation.html http://reference.perl.com/query.cgi?tutorials -=head2 What are the Perl newsgroups on USENET? Where do I post questions? +=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: @@ -170,7 +171,7 @@ following groups: comp.infosystems.www.authoring.cgi Writing CGI scripts for the Web. -There is also USENET gateway to the mailing list used by the crack +There is also Usenet gateway to the mailing list used by the crack Perl development team (perl5-porters) at news://news.perl.com/perl.porters-gw/ . @@ -182,14 +183,15 @@ 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 (http://www.faqs.org/faqs/alt-sources-intro/) for details. -If you're just looking for software, first use Alta Vista, Deja News, and +If you're just looking for software, first use AltaVista +(http://www.altavista.com), Deja (http://www.deja.com), and search CPAN. This is faster and more productive than just posting a request. =head2 Perl Books A number of books on Perl and/or CGI programming are available. A few of -these are good, some are ok, but many aren't worth your money. Tom +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. @@ -254,7 +256,10 @@ a star may be ordered from O'Reilly. by Larry Wall, Tom Christiansen, and Randal L. Schwartz *Perl 5 Desktop Reference - By Johan Vromans + by Johan Vromans + + *Perl in a Nutshell + by Ellen Siever, Stephan Spainhour, and Nathan Patwardhan =item Tutorials @@ -298,6 +303,9 @@ a star may be ordered from O'Reilly. How to Set up and Maintain a World Wide Web Site [2nd edition] by Lincoln Stein + *Learning Perl/Tk + by Nancy Walsh + =back =head2 Perl in Magazines @@ -322,7 +330,7 @@ http://www.stonehenge.com/merlyn/WebTechniques/. 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 +From there you can find the quickest site for you. Remember, the following list is I the complete list of CPAN mirrors. http://www.perl.com/CPAN-local @@ -332,9 +340,9 @@ following list is I the complete list of CPAN mirrors. http://www.cs.ruu.nl/pub/PERL/CPAN/ ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ -=head2 What mailing lists are there for perl? +=head2 What mailing lists are there for Perl? -Most of the major modules (tk, CGI, libwww-perl) have their own +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 Perl Institute attempts to maintain a list of mailing lists at: @@ -343,10 +351,10 @@ list of mailing lists at: =head2 Archives of comp.lang.perl.misc -Have you tried Deja News or Alta Vista? Those are the +Have you tried Deja or AltaVista? Those are the best archives. Just look up "*perl*" as a newsgroup. - http://www.dejanews.com/dnquery.xp?QRY=&DBS=2&ST=PS&defaultOp=AND&LNG=ALL&format=terse&showsort=date&maxhits=25&subjects=&groups=*perl*&authors=&fromdate=&todate= + http://www.deja.com/dnquery.xp?QRY=&DBS=2&ST=PS&defaultOp=AND&LNG=ALL&format=terse&showsort=date&maxhits=25&subjects=&groups=*perl*&authors=&fromdate=&todate= You'll probably want to trim that down a bit, though. @@ -379,8 +387,8 @@ 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 awry. 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. For example, many perl books carry a perl distribution +Shrink-wrapped CDs with Perl on them are available from several sources if +that will help. For example, many Perl books carry a Perl distribution on them, as do the O'Reilly Perl Resource Kits (in both the Unix flavor and in the proprietary Microsoft flavor); the free Unix distributions also all come with Perl. @@ -417,7 +425,7 @@ See also www.perl.com for updates on tutorials, training, and support. =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 I program in the perl distribution or +shipped with Perl, use the I program in the Perl distribution or mail your report to perlbug@perl.com . If you are posting a bug with a non-standard port (see the answer to @@ -434,7 +442,7 @@ The perl.com domain is owned by Tom Christiansen, who created it as a public service long before perl.org came about. Despite the name, it's a pretty non-commercial site meant to be a clearinghouse for information about all things Perlian, accepting no paid advertisements, bouncy -happy gifs, or silly java applets on its pages. The Perl Home Page at +happy GIFs, or silly Java applets on its pages. The Perl Home Page at http://www.perl.com/ is currently hosted on a T3 line courtesy of Songline Systems, a software-oriented subsidiary of O'Reilly and Associates. Other starting points include @@ -453,7 +461,7 @@ of Perl or of its documentation (printed or otherwise), this works is covered under Perl's Artistic License. For separate distributions of all or part of this FAQ outside of that, see L. -Irrespective of its distribution, all code examples here are public +Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod index 4e56a54..d2e83be 100644 --- a/pod/perlfaq3.pod +++ b/pod/perlfaq3.pod @@ -25,7 +25,7 @@ Have you read the appropriate man pages? Here's a brief index: Various http://www.perl.com/CPAN/doc/FMTEYEWTK/index.html (not a man-page but still useful) -L provides a crude table of contents for the perl man page set. +A crude table of contents for the Perl man page set is found in L. =head2 How can I use Perl interactively? @@ -41,8 +41,8 @@ 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 +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. @@ -144,7 +144,7 @@ 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. -The a2ps at http://www.infres.enst.fr/~demaille/a2ps/ does lots of things +The a2ps at http://www.infres.enst.fr/%7Edemaille/a2ps/ does lots of things related to generating nicely printed output of documents. =head2 Is there a ctags for Perl? @@ -180,7 +180,7 @@ your hard-earned cash on. PerlBuilder (XXX URL to follow) is an integrated development environment for Windows that supports Perl development. Perl programs are just plain text, though, so you could download emacs for Windows (???) or a vi clone -(vim) which runs on for win32 (http://www.cs.vu.nl/~tmgil/vi.html). +(vim) which runs on for win32 (http://www.cs.vu.nl/%7Etmgil/vi.html). If you're transferring Windows files to Unix, be sure to transfer in ASCII mode so the ends of lines are appropriately mangled. @@ -195,10 +195,10 @@ 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 +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", +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. @@ -223,11 +223,11 @@ to the Athena Widget set. Both are available from CPAN. See the directory http://www.perl.com/CPAN/modules/by-category/08_User_Interfaces/ Invaluable for Perl/Tk programming are: the Perl/Tk FAQ at -http://w4.lns.cornell.edu/~pvhp/ptk/ptkTOC.html , the Perl/Tk Reference +http://w4.lns.cornell.edu/%7Epvhp/ptk/ptkTOC.html , the Perl/Tk Reference Guide available at http://www.perl.com/CPAN-local/authors/Stephen_O_Lidie/ , and the online manpages at -http://www-users.cs.umn.edu/~amundson/perl/perltk/toc.html . +http://www-users.cs.umn.edu/%7Eamundson/perl/perltk/toc.html . =head2 How can I generate simple menus without using CGI or Tk? @@ -272,9 +272,9 @@ it. See the F 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 +outperform those that don't (for I/O intensive applications). To try this, see the F file in the source distribution, especially -the ``Selecting File IO mechanisms'' section. +the ``Selecting File I/O 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 @@ -369,11 +369,11 @@ anything a module written in C can. For more on mod_perl, see http://perl.apache.org/ With the FCGI module (from CPAN) and the mod_fastcgi -module (available from http://www.fastcgi.com/) each of your perl -scripts becomes a permanent CGI daemon process. +module (available from http://www.fastcgi.com/) each of your Perl +programs becomes a permanent CGI daemon process. 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 +and on the way you write your CGI programs, so investigate them with care. See http://www.perl.com/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . @@ -381,9 +381,9 @@ See http://www.perl.com/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI A non-free, commercial product, ``The Velocity Engine for Perl'', (http://www.binevolve.com/ or http://www.binevolve.com/bine/vep) might also be worth looking at. It will allow you to increase the performance -of your perl scripts, upto 25 times faster than normal CGI perl by -running in persistent perl mode, or 4 to 5 times faster without any -modification to your existing CGI scripts. Fully functional evaluation +of your Perl programs, up to 25 times faster than normal CGI Perl by +running in persistent Perl mode, or 4 to 5 times faster without any +modification to your existing CGI programs. Fully functional evaluation copies are available from the web site. =head2 How can I hide the source for my Perl program? @@ -445,7 +445,7 @@ just as big as the original perl executable, and then some. That's because as currently written, all programs are prepared for a full eval() statement. You can tremendously reduce this cost by building a shared I library and linking against that. See the -F podfile in the perl source distribution for details. If +F podfile in the Perl source distribution for details. If you link your main perl binary with this, it will make it minuscule. For example, on one author's system, F is only 11k in size! @@ -465,7 +465,7 @@ Perl install anyway. You can't. Not yet, anyway. You can integrate Java and Perl with the Perl Resource Kit from O'Reilly and Associates. See http://www.oreilly.com/catalog/prkunix/ for more information. -The Java interface will be supported in the core 5.006 release +The Java interface will be supported in the core 5.6 release of Perl. =head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]? @@ -488,15 +488,15 @@ the Registry yourself. In addition to associating C<.pl> with the interpreter, NT people can use: C to let them run the program C merely by typing C. -Macintosh perl scripts will have the appropriate Creator and -Type, so that double-clicking them will invoke the perl application. +Macintosh Perl programs will have the appropriate Creator and +Type, so that double-clicking them will invoke the Perl application. I: 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 +get your programs 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? +=head2 Can I write useful Perl programs on the command line? Yes. Read L for more information. Some examples follow. (These assume standard Unix shell quoting rules.) @@ -520,9 +520,9 @@ Yes. Read L for more information. Some examples follow. 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. :-) +OK, the last one was actually an Obfuscated Perl Contest entry. :-) -=head2 Why don't perl one-liners work on my DOS/Mac/VMS system? +=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 @@ -598,7 +598,7 @@ when it runs fine on the command line'', see these sources: =head2 Where can I learn about object-oriented Perl programming? -L is a good place to start, and you can use L and +A good place to start is L, and you can use L and L 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/ . @@ -617,15 +617,15 @@ 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 and send a bugreport with the output of +fail, see L and send a bug report with the output of C along with C. =head2 When I tried to run my script, I got this message. What does it mean? -L 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: +A complete list of Perl's error messages and warnings with explanatory +text can be found in L. 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 @@ -640,7 +640,7 @@ or =head2 What's MakeMaker? -This module (part of the standard perl distribution) is designed to +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. @@ -654,7 +654,7 @@ of Perl or of its documentation (printed or otherwise), this works is covered under Perl's Artistic License. For separate distributions of all or part of this FAQ outside of that, see L. -Irrespective of its distribution, all code examples here are public +Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod index 700c42a..63e093f 100644 --- a/pod/perlfaq4.pod +++ b/pod/perlfaq4.pod @@ -31,7 +31,7 @@ representation is converted back to decimal. These decimal numbers are displayed in either the format you specify with printf(), or the current output format for numbers (see L if you use print. C<$#> has a different default value in Perl5 than it did in -Perl4. Changing C<$#> yourself is deprecated. +Perl4. Changing C<$#> yourself is deprecated.) This affects B computer languages that represent decimal floating-point numbers in binary, not just Perl. Perl provides @@ -67,7 +67,7 @@ route. printf("%.3f", 3.1415926535); # prints 3.142 -The POSIX module (part of the standard perl distribution) implements +The POSIX module (part of the standard Perl distribution) implements ceil(), floor(), and a number of other mathematical and trigonometric functions. @@ -76,7 +76,7 @@ functions. $floor = floor(3.5); # 3 In 5.000 to 5.003 Perls, trigonometry was done in the Math::Complex -module. With 5.004, the Math::Trig module (part of the standard perl +module. With 5.004, the Math::Trig module (part of the standard Perl distribution) implements the trigonometric functions. Internally it uses the Math::Complex module and some functions can break out from the real axis into the complex plane, for example the inverse sine of @@ -105,12 +105,12 @@ are not guaranteed. To turn a string of 1s and 0s like C<10110110> into a scalar containing its binary value, use the pack() and unpack() functions (documented in -L): +L and L): $decimal = unpack('c', pack('B8', '10110110')); This packs the string C<10110110> into an eight bit binary structure. -This is then unpack as a character, which returns its ordinal value. +This is then unpacked as a character, which returns its ordinal value. This does the same thing: @@ -183,6 +183,15 @@ ranges. Instead use: push(@results, some_func($i)); } +This situation has been fixed in Perl5.005. Use of C<..> in a C +loop will iterate over the range, without creating the entire range. + + for my $i (5 .. 500_005) { + push(@results, some_func($i)); + } + +will not create a list of 500,000 integers. + =head2 How can I output Roman numerals? Get the http://www.perl.com/CPAN/modules/by-module/Roman module. @@ -333,7 +342,7 @@ A solution to this issue is offered by Russ Allbery. # # The explicit settings of $ndst and $tdst are necessary because localtime # only says it returns the system tm struct, and the system tm struct at - # least on Solaris doesn't guarantee any particuliar positive value (like, + # least on Solaris doesn't guarantee any particular positive value (like, # say, 1) for isdst, just a positive value. And that value can # potentially be negative, if DST information isn't available (this sub # just treats those cases like no DST). @@ -350,7 +359,7 @@ A solution to this issue is offered by Russ Allbery. # Copyright relinquished 1999 by Russ Allbery # This code is in the public domain -=head2 Does Perl have a year 2000 problem? Is Perl Y2K compliant? +=head2 Does Perl have a Year 2000 problem? Is Perl Y2K compliant? Short answer: No, Perl does not have a Year 2000 problem. Yes, Perl is Y2K compliant (whatever that means). The programmers you've hired to @@ -361,7 +370,7 @@ Perl is just as Y2K compliant as your pencil--no more, and no less. Can you use your pencil to write a non-Y2K-compliant memo? Of course you can. Is that the pencil's fault? Of course it isn't. -The date and time functions supplied with perl (gmtime and localtime) +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 for 32-bit machines). The year returned by these functions when used in an array context is the year minus 1900. @@ -441,7 +450,7 @@ If you are serious about writing a parser, there are a number of modules or oddities that will make your life a lot easier. There is the CPAN module Parse::RecDescent, the standard module Text::Balanced, the byacc program, the CPAN module Parse::Yapp, and Mark-Jason -Dominus's excellent I tool at http://www.plover.com/~mjd/perl/py/ +Dominus's excellent I tool at http://www.plover.com/%7Emjd/perl/py/ . One simple destructive, inside-out approach that you might try is to @@ -479,7 +488,7 @@ You can do it yourself: 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 +Or you can just use the Text::Tabs module (part of the standard Perl distribution). use Text::Tabs; @@ -487,7 +496,7 @@ distribution). =head2 How do I reformat a paragraph? -Use Text::Wrap (part of the standard perl distribution): +Use Text::Wrap (part of the standard Perl distribution): use Text::Wrap; print wrap("\t", ' ', @paragraphs); @@ -570,8 +579,8 @@ To make the first letter of each word upper case: $line =~ s/\b(\w)/\U$1/g; This has the strange effect of turning "C" into "C". Sometimes you might want this, instead (Suggested by Brian -Foy): +Do It>". Sometimes you might want this, instead (Suggested by brian d. +foy): $string =~ s/ ( (^\w) #at the beginning of the line @@ -627,7 +636,7 @@ quotation-mark-delimited field, escape them with backslashes (eg, C<"like \"this\"">. Unescaping them is a task addressed earlier in this section. -Alternatively, the Text::ParseWords module (part of the standard perl +Alternatively, the Text::ParseWords module (part of the standard Perl distribution) lets you say: use Text::ParseWords; @@ -735,7 +744,7 @@ you can use this kind of thing: =head2 How do I find the soundex value of a string? -Use the standard Text::Soundex module distributed with perl. +Use the standard Text::Soundex module distributed with Perl. But before you do so, you may want to determine whether `soundex' is in fact what you think it is. Knuth's soundex algorithm compresses words into a small space, and so it does not necessarily distinguish between @@ -952,7 +961,7 @@ ordered and whether you wish to preserve the ordering. This is nice in that it doesn't use much extra memory, simulating uniq(1)'s behavior of removing only adjacent duplicates. It's less nice in that it won't work with false values like undef, 0, or ""; -"0 but true" is ok, though. +"0 but true" is OK, though. =item b) If you don't know whether @in is sorted: @@ -973,7 +982,7 @@ nice in that it won't work with false values like undef, 0, or ""; undef @ary; @ary[@in] = @in; - @out = @ary; + @out = grep {defined} @ary; =back @@ -1121,7 +1130,7 @@ Now C<$found_index> has what you want. 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. Both pop and shift are both O(1) operations on perl's +arbitrary points. Both pop and shift are both O(1) operations on Perl's dynamic arrays. In the absence of shifts and pops, push in general needs to reallocate on the order every log(N) times, and unshift will need to copy pointers each time. @@ -1427,10 +1436,10 @@ sorting the keys as shown in an earlier question. Don't do that. :-) [lwall] In Perl 4, you were not allowed to modify a hash at all while -interating over it. In Perl 5 you can delete from it, but you still +iterating over it. In Perl 5 you can delete from it, but you still can't add to it, because that might cause a doubling of the hash table, in which half the entries get copied up to the new top half of the -table, at which point you've totally bamboozled the interator code. +table, at which point you've totally bamboozled the iterator code. Even if the table doesn't double, there's no telling whether your new entry will be inserted before or after the current iterator position. @@ -1527,7 +1536,7 @@ And these conditions hold $ary{'d'} is false defined $ary{'d'} is true defined $ary{'a'} is true - exists $ary{'a'} is true (perl5 only) + exists $ary{'a'} is true (Perl5 only) grep ($_ eq 'a', keys %ary) is true If you now say @@ -1551,7 +1560,7 @@ and these conditions now hold; changes in caps: $ary{'d'} is false defined $ary{'d'} is true defined $ary{'a'} is FALSE - exists $ary{'a'} is true (perl5 only) + 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! @@ -1575,7 +1584,7 @@ and these conditions now hold; changes in caps: $ary{'d'} is false defined $ary{'d'} is true defined $ary{'a'} is false - exists $ary{'a'} is FALSE (perl5 only) + exists $ary{'a'} is FALSE (Perl5 only) grep ($_ eq 'a', keys %ary) is FALSE See, the whole entry is gone! @@ -1651,7 +1660,7 @@ 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. +This has been fixed as of Perl5.004. Normally, merely accessing a key's value for a nonexistent key does I cause that key to be forever there. This is different than @@ -1678,7 +1687,7 @@ in L. =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. +module distributed with Perl. =head1 Data: Misc diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod index 1e8252b..3869ff3 100644 --- a/pod/perlfaq5.pod +++ b/pod/perlfaq5.pod @@ -554,7 +554,7 @@ be an atomic operation over NFS. That is, two processes might both successful create or unlink the same file! Therefore O_EXCL isn't so exclusive as you might wish. -See also the new L if you have it (new for 5.006). +See also the new L if you have it (new for 5.6). =head2 Why do I sometimes get an "Argument list too long" when I use E*E? @@ -606,7 +606,7 @@ It would be a lot clearer to use sysopen(), though: or die "can't open $badpath: $!"; For more information, see also the new L if you have it -(new for 5.006). +(new for 5.6). =head2 How can I reliably rename a file? @@ -672,7 +672,7 @@ Slavish adherence to portability concerns shouldn't get in the way of your getting your job done.) For more information on file locking, see also L if you have it (new for 5.006). +Locking"> if you have it (new for 5.6). =back @@ -855,11 +855,10 @@ you'd get a list of all the lines: @lines = `cat $file`; -This tiny but expedient solution is neat, clean, and portable to all -systems that you've bothered to install decent tools on, even if you are -a Prisoner of Bill. For those die-hards PoBs who've paid their billtax -and refuse to use the toolbox, or who like writing complicated code for -job security, you can of course read the file manually. +This tiny but expedient solution is neat, clean, and portable to +all systems on which decent tools have been installed. For those +who prefer not to use the toolbox, you can of course read the file +manually, although this makes for more complicated code. { local(*INPUT, $/); @@ -1208,7 +1207,7 @@ of Perl or of its documentation (printed or otherwise), this works is covered under Perl's Artistic License. For separate distributions of all or part of this FAQ outside of that, see L. -Irrespective of its distribution, all code examples here are public +Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index ddf64d0..e7fdc78 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -1435,7 +1435,7 @@ defined C routines first, but these C routines may not themselves abort the exit. Likewise any object destructors that need to be called are called before the real exit. If this is a problem, you can call C to avoid END and destructor processing. -See L for details. +See L for details. =item exp EXPR @@ -4200,29 +4200,38 @@ a NAME, it's an anonymous function declaration, and does actually return a value: the CODE ref of the closure you just created. See L and L for details. -=item substr EXPR,OFFSET,LEN,REPLACEMENT +=item substr EXPR,OFFSET,LENGTH,REPLACEMENT -=item substr EXPR,OFFSET,LEN +=item substr EXPR,OFFSET,LENGTH =item substr EXPR,OFFSET Extracts a substring out of EXPR and returns it. First character is at offset C<0>, or whatever you've set C<$[> to (but don't do that). If OFFSET is negative (or more precisely, less than C<$[>), starts -that far from the end of the string. If LEN is omitted, returns -everything to the end of the string. If LEN is negative, leaves that +that far from the end of the string. If LENGTH is omitted, returns +everything to the end of the string. If LENGTH is negative, leaves that many characters off the end of the string. -If you specify a substring that is partly outside the string, the part -within the string is returned. If the substring is totally outside -the string a warning is produced. - You can use the substr() function as an lvalue, in which case EXPR -must itself be an lvalue. If you assign something shorter than LEN, -the string will shrink, and if you assign something longer than LEN, +must itself be an lvalue. If you assign something shorter than LENGTH, +the string will shrink, and if you assign something longer than LENGTH, the string will grow to accommodate it. To keep the string the same length you may need to pad or chop your value using C. +If OFFSET and LENGTH specify a substring that is partly outside the +string, only the part within the string is returned. If the substring +is beyond either end of the string, substr() returns the undefined +value and produces a warning. When used as an lvalue, specifying a +substring that is entirely outside the string is a fatal error. +Here's an example showing the behavior for boundary cases: + + my $name = 'fred'; + substr($name, 4) = 'dy'; # $name is now 'freddy' + my $null = substr $name, 6, 2; # returns '' (no warning) + my $oops = substr $name, 7; # returns undef, with warning + substr($name, 7) = 'gap'; # fatal error + An alternative to using substr() as an lvalue is to specify the replacement string as the 4th argument. This allows you to replace parts of the EXPR and return what was there before in one operation, diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 2c6d3a2..f297560 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -366,9 +366,9 @@ The hash algorithm is defined in the C macro: hash = 0; while (klen--) hash = (hash * 33) + *key++; - hash = hash + (hash >> 5); /* after 5.006 */ + hash = hash + (hash >> 5); /* after 5.6 */ -The last step was added in version 5.006 to improve distribution of +The last step was added in version 5.6 to improve distribution of lower bits in the resulting hash value. See L for more diff --git a/pod/perlhist.pod b/pod/perlhist.pod index 7ba4429..ec6f3f2 100644 --- a/pod/perlhist.pod +++ b/pod/perlhist.pod @@ -314,7 +314,7 @@ the strings?). 5.005_03-MT5 1999-Jan-28 5.005_03 1999-Mar-28 - Sarathy 5.005_50 1998-Jul-26 The 5.006 development track. + Sarathy 5.005_50 1998-Jul-26 The 5.6 development track. 5.005_51 1998-Aug-10 5.005_52 1998-Sep-25 5.005_53 1998-Oct-31 diff --git a/pod/perlop.pod b/pod/perlop.pod index 0f8117c..3234131 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -620,9 +620,7 @@ function as operators, providing various kinds of interpolating and pattern matching capabilities. Perl provides customary quote characters for these behaviors, but also provides a way for you to choose your quote character for any of them. In the following table, a C<{}> represents -any pair of delimiters you choose. Non-bracketing delimiters use -the same character fore and aft, but the 4 sorts of brackets -(round, angle, square, curly) will all nest. +any pair of delimiters you choose. Customary Generic Meaning Interpolates '' q{} Literal no @@ -634,6 +632,23 @@ the same character fore and aft, but the 4 sorts of brackets s{}{} Substitution yes (unless '' is delimiter) tr{}{} Transliteration no (but see below) +Non-bracketing delimiters use the same character fore and aft, but the four +sorts of brackets (round, angle, square, curly) will all nest, which means +that + + q{foo{bar}baz} + +is the same as + + 'foo{bar}baz' + +Note, however, that this does not always work for quoting Perl code: + + $s = q{ if($a eq "}") ... }; # WRONG + +is a syntax error. The C module on CPAN is able to do this +properly. + There can be whitespace between the operator and the quoting characters, except when C<#> is being used as the quoting character. C is parsed as the string C, while C is the diff --git a/pod/perlport.pod b/pod/perlport.pod index 7c73cd2..6837b4c 100644 --- a/pod/perlport.pod +++ b/pod/perlport.pod @@ -705,7 +705,7 @@ may run a slightly modified version of MacPerl, using the Carbon interfaces. S and its Open Source version, Darwin, both run Unix perl natively (with a few patches). Full support for these -is slated for perl5.006. +is slated for perl 5.6. Also see: diff --git a/pod/perltodo.pod b/pod/perltodo.pod index 5962fc8..4b2ed48 100644 --- a/pod/perltodo.pod +++ b/pod/perltodo.pod @@ -714,7 +714,7 @@ criticized for being of questionable value. =head2 Making my() work on "package" variables Being able to say my($Foo::Bar), something that sounds ludicrous and -the 5.006 pumpking has mocked. +the 5.6 pumpking has mocked. =head2 "or" testing defined not truth diff --git a/pod/perltoot.pod b/pod/perltoot.pod index c77a971..89e5cbe 100644 --- a/pod/perltoot.pod +++ b/pod/perltoot.pod @@ -329,7 +329,7 @@ do more than fetch or set one particular field. sub exclaim { my $self = shift; return sprintf "Hi, I'm %s, age %d, working with %s", - $self->{NAME}, $self->{AGE}, join(", ", $self->{PEERS}); + $self->{NAME}, $self->{AGE}, join(", ", @{$self->{PEERS}}); } Or maybe even one like this: diff --git a/pod/perltootc.pod b/pod/perltootc.pod index f7157e8..85ae6fb 100644 --- a/pod/perltootc.pod +++ b/pod/perltootc.pod @@ -111,12 +111,12 @@ hard-coded in so many places. Both these problems can be easily fixed. Just add the C pragma, then pre-declare your package variables. (The C operator -will be new in 5.006, and will work for package globals just like C +will be new in 5.6, and will work for package globals just like C works for scoped lexicals.) package Some_Class; use strict; - our($CData1, $CData2); # our() is new to perl5.006 + our($CData1, $CData2); # our() is new to perl5.6 sub CData1 { shift; # XXX: ignore calling class/object $CData1 = shift if @_; @@ -148,7 +148,7 @@ Here's what to do. First, make just one hash to hold all class attributes. package Some_Class; use strict; - our %ClassData = ( # our() is new to perl5.006 + our %ClassData = ( # our() is new to perl5.6 CData1 => "", CData2 => "", ); @@ -287,7 +287,7 @@ used to implement the class. use strict; # create class meta-object using that most perfect of names - our %Some_Class = ( # our() is new to perl5.006 + our %Some_Class = ( # our() is new to perl5.6 CData1 => "", CData2 => "", ); @@ -339,7 +339,7 @@ class the object belongs to. package Some_Class; use strict; - our %Some_Class = ( # our() is new to perl5.006 + our %Some_Class = ( # our() is new to perl5.6 CData1 => "", CData2 => "", ); @@ -373,7 +373,7 @@ L, but there may be variations in the example below that you haven't thought of before. package Some_Class; - our($CData1, $CData2); # our() is new to perl5.006 + our($CData1, $CData2); # our() is new to perl5.6 sub new { my $obclass = shift; @@ -424,7 +424,7 @@ proper package's data. package Some_Class; use strict; - our %Some_Class = ( # our() is new to perl5.006 + our %Some_Class = ( # our() is new to perl5.6 CData1 => "", CData2 => "", ); @@ -738,7 +738,7 @@ these attributes similar to the way process attributes like environment variables, user and group IDs, or the current working directory are treated across a fork(). You can change only yourself, but you will see those changes reflected in your unspawned children. Changes to one object -will propagate enither up to the parent nor down to any existing child objects. +will propagate neither up to the parent nor down to any existing child objects. Those objects made later, however, will see the changes. If you have an object with an actual attribute value, and you want to @@ -757,7 +757,7 @@ Here's a complete implementation of Vermin as described above. # so the latter can be used for both initialization # and translucency. - our %Vermin = ( # our() is new to perl5.006 + our %Vermin = ( # our() is new to perl5.6 PopCount => 0, # capital for class attributes color => "beige", # small for instance attributes ); @@ -1125,7 +1125,7 @@ Here's one way: No one--absolutely no one--is allowed to read or write the class attributes without the mediation of the managing accessor method, since only that method has access to the lexical variable it's managing. -This use of mediated access to class attributes is a form privacy far +This use of mediated access to class attributes is a form of privacy far stronger than most OO languages provide. The repetition of code used to create per-datum accessor methods chafes @@ -1157,8 +1157,8 @@ the &UNIVERSAL::can method and SUPER as shown previously. =head2 Translucency Revisited -The Vermin class used to demonstrate translucency used an eponymously -named package variable, %Vermin, as its meta-object. If you prefer to +The Vermin class demonstrates translucency using a package variable, +eponymously named %Vermin, as its meta-object. If you prefer to use absolutely no package variables beyond those necessary to appease inheritance or possibly the Exporter, this strategy is closed to you. That's too bad, because translucent attributes are an appealing @@ -1287,7 +1287,7 @@ better approach. We use the hypothetical our() syntax for package variables. It works like C, but looks like my(). It should be in this summer's -major release (5.006) of perl--we hope. +major release (5.6) of perl--we hope. You can't use file-scoped lexicals in conjunction with the SelfLoader or the AutoLoader, because they alter the lexical scope in which the diff --git a/pod/perlvar.pod b/pod/perlvar.pod index c13c417..3a38f55 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -45,9 +45,7 @@ you try to assign to this variable, either directly or indirectly through a reference, you'll raise a run-time exception. The following list is ordered by scalar variables first, then the -arrays, then the hashes (except $^M was added in the wrong place). -This is somewhat obscured because %ENV and %SIG are listed as -$ENV{expr} and $SIG{expr}. +arrays, then the hashes. =over 8 @@ -868,7 +866,7 @@ The hash %INC contains entries for each filename included via the C, C, or C operators. The key is the filename you specified (with module names converted to pathnames), and the value is the location of the file found. The C -operator uses this array to determine whether a particular file has +operator uses this hash to determine whether a particular file has already been included. =item %ENV @@ -1047,7 +1045,7 @@ C) is the scalar variable whose name is the single character control-C. This is better than typing a literal control-C into your program. -Finally, new in Perl 5.006, Perl variable names may be alphanumeric +Finally, new in Perl 5.6, Perl variable names may be alphanumeric strings that begin with control characters (or better yet, a caret). These variables must be written in the form C<${^Foo}>; the braces are not optional. C<${^Foo}> denotes the scalar variable whose