From 68dc074516a6859e3424b48d1647bcb08b1a1a7d Mon Sep 17 00:00:00 2001 From: Perl 5 Porters Date: Sun, 9 Mar 1997 11:57:19 +1200 Subject: [inseparable changes from match from perl-5.003_93 to perl-5.003_94] BUILD PROCESS Subject: Don't use db 2.x, we're not yet ready for it From: Paul Marquess Files: Configure Subject: Warn if #! command is longer than 32 chars From: Chip Salzenberg Files: Configure Subject: patches re perl -wc install{perl,man} Date: Tue, 11 Mar 97 13:13:16 GMT From: Robin Barker Files: installman installperl I got the new installhtml from CPAN (TOMC/scripts/pod2html-v2.0beta.shar.gz) I had problems getting the system call to splitpod at line 376 to work. 1. splitroot was not being found 2. splitroot was not finding its library 3. I changed htmlroot to podroot at line 175 to match the documentation. p5p-msgid: 3180.9703270906@tempest.cise.npl.co.uk private-msgid: 21544.9703111313@tempest.cise.npl.co.uk Subject: 3_93 doesn't install pods Date: Sun, 16 Mar 1997 02:21:35 -0500 From: Spider Boardman Files: installperl Msg-ID: 199703160721.CAA08339@Orb.Nashua.NH.US (applied based on p5p patch as commit 43506a616735d616e03d277d64fbae1e864024bf) Subject: When installing, use File::Copy instead of `cp` From: Chip Salzenberg Files: installperl Subject: Make hint files' warnings more visible Date: Thu, 20 Mar 1997 23:18:03 +0100 (MET) From: Hallvard B Furuseth Files: hints/3b1.sh hints/apollo.sh hints/cxux.sh hints/dcosx.sh hints/dgux.sh hints/esix4.sh hints/freebsd.sh hints/hpux.sh hints/irix_4.sh hints/mips.sh hints/next_3_0.sh hints/os2.sh hints/qnx.sh hints/sco_2_3_3.sh hints/sco_2_3_4.sh hints/solaris_2.sh hints/ultrix_4.sh hints/utekv.sh private-msgid: 199703202218.XAA09041@bombur2.uio.no CORE LANGUAGE CHANGES Subject: Defer creation of array and hash elements as parameters From: Chip Salzenberg Files: dump.c global.sym mg.c op.c op.h perl.h pp.c pp_hot.c proto.h sv.c Subject: New special literal: __PACKAGE__ From: Chip Salzenberg Files: keywords.pl pod/perldata.pod toke.c Subject: Abort compilation at C or C after errors From: Chip Salzenberg Files: op.c pod/perldiag.pod t/pragma/subs.t Subject: allow C Date: Mon, 10 Mar 1997 15:55:44 -0800 From: David Dyck Files: pp.c Msg-ID: 97Mar10.155517pst.35716-2@gateway.fluke.com (applied based on p5p patch as commit 77f720bf92f3d0100352416caeedd57936807ff2) Subject: Regularize C, esp. when y is negative From: Chip Salzenberg Files: pp.c Subject: Flush before C From: Chip Salzenberg Files: pod/perldelta.pod pod/perlfunc.pod pp_sys.c Subject: Close loopholes in prototype mismatch warning From: Chip Salzenberg Files: op.c sv.c toke.c Subject: Warn on C From: Chip Salzenberg Files: op.c pod/perldiag.pod Subject: Don't warn on C From: Chip Salzenberg Files: toke.c CORE PORTABILITY Subject: Don't say 'static var = 1' Date: Sun, 9 Mar 1997 15:19:57 +0200 (EET) From: Jarkko Hietaniemi Files: malloc.c private-msgid: 199703091319.PAA24714@alpha.hut.fi Subject: HP/UX hint comments Date: Fri, 21 Mar 1997 15:43:07 -0500 (EST) From: Andy Dougherty Files: hints/hpux.sh private-msgid: Pine.SOL.3.95q.970321153918.28770B-100000@fractal.lafayette. Subject: VMS update Date: Tue, 11 Mar 1997 22:00:55 -0500 (EST) From: Charles Bailey Files: lib/ExtUtils/MM_VMS.pm lib/Test/Harness.pm t/op/taint.t utils/perlbug.PL vms/descrip.mms Msg-ID: 1997Mar11.220056.1873182@hmivax.humgen.upenn.edu (applied based on p5p patch as commit 2b5725676da60b49978f38b85bb7f8ee20b4cb55) Subject: vmsish.t and related patches Date: Fri, 21 Mar 1997 01:32:47 -0500 (EST) From: Charles Bailey Files: MANIFEST perl.h vms/descrip.mms vms/ext/vmsish.t vms/vms.c private-msgid: 01IGQW3IP1KK005VFB@hmivax.humgen.upenn.edu Subject: Win32 update (four patches) From: Gurusamy Sarathy Files: MANIFEST README.win32 lib/AutoSplit.pm lib/Cwd.pm lib/ExtUtils/Command.pm lib/ExtUtils/Install.pm lib/ExtUtils/MM_OS2.pm lib/ExtUtils/MM_Unix.pm lib/ExtUtils/MM_Win32.pm lib/ExtUtils/MakeMaker.pm lib/ExtUtils/Mksymlists.pm lib/File/Basename.pm lib/File/Path.pm mg.c t/comp/cpp.t t/comp/script.t t/harness t/io/argv.t t/io/dup.t t/io/fs.t t/io/inplace.t t/lib/filehand.t t/lib/io_dup.t t/lib/io_sel.t t/lib/io_taint.t t/op/closure.t t/op/exec.t t/op/glob.t t/op/goto.t t/op/magic.t t/op/misc.t t/op/rand.t t/op/split.t t/op/stat.t t/op/sysio.t t/op/taint.t t/pragma/strict.t t/pragma/subs.t t/pragma/warning.t util.c win32/* DOCUMENTATION Subject: perlfaq.pod Date: Mon, 17 Mar 1997 16:01:40 -0700 From: Tom Christiansen Files: MANIFEST pod/Makefile pod/buildtoc pod/perl.pod pod/perlfaq*.pod pod/roffitall private-msgid: 199703172301.QAA12566@jhereg.perl.com Subject: *.pod changes based on the FAQ Date: Mon, 17 Mar 1997 09:50:14 -0700 (MST) From: Nat Torkington Files: pod/perldata.pod pod/perlfunc.pod pod/perlipc.pod pod/perlop.pod pod/perlre.pod pod/perlrun.pod pod/perlsec.pod pod/perlvar.pod Msg-ID: 199703171650.JAA02655@elara.frii.com (applied based on p5p patch as commit 3c10ad8e31f7d77e71c048b1746912f41cb540f0) Subject: Document that $. is not reset on implicit open From: Chip Salzenberg Files: pod/perldelta.pod Subject: Re: Embedding success with _93 Date: Tue, 11 Mar 1997 17:55:05 -0500 From: Doug MacEachern Files: pod/perldelta.pod Msg-ID: 199703112255.RAA22775@postman.osf.org (applied based on p5p patch as commit 63a6ff3a1dc8d86edb4d8a7ec1548205e32a7114) Subject: Patch to document illegal characters Date: Fri, 14 Mar 1997 09:08:10 -0800 (PST) From: Tom Phoenix Files: pod/perldiag.pod pod/perltrap.pod private-msgid: Pine.GSO.3.96.970314090558.15346J-100000@kelly.teleport.com Subject: Document trap with //o and closures Date: Mon, 10 Mar 1997 18:08:08 -0500 (EST) From: Charles Bailey Files: pod/perltrap.pod Msg-ID: 01IGCHWRNSEU00661G@hmivax.humgen.upenn.edu (applied based on p5p patch as commit a54cb1465fdb400848f23705a6f130bb5c34ab70) Subject: Illegal character in input Date: Mon, 10 Mar 1997 15:21:21 -0800 (PST) From: Tom Phoenix Files: pod/perldiag.pod private-msgid: Pine.GSO.3.95q.970310151512.22489a-100000@kelly.teleport.com Subject: Patch for docs Re: Lost backslash Date: Wed, 19 Mar 1997 07:28:57 -0800 (PST) From: Tom Phoenix Files: pod/perlop.pod private-msgid: Pine.GSO.3.96.970319071438.24834G-100000@kelly.teleport.com Subject: XSUB's doc fix Date: Mon, 10 Mar 1997 11:42:06 -0500 From: Roderick Schertler Files: pod/perlcall.pod pod/perlguts.pod pod/perlxstut.pod Msg-ID: 28804.858012126@eeyore.ibcinc.com (applied based on p5p patch as commit 5f43237038ea7a4151d3bf65aeeecd56ceb78a6a) Subject: Document return from do FILE Date: Tue, 18 Mar 1997 14:50:10 +0000 From: "M.J.T. Guy" Files: pod/perlfunc.pod Msg-ID: E0w70DK-0001yJ-00@ursa.cus.cam.ac.uk (applied based on p5p patch as commit ba8d5fb439878113de8abc9b52d2af237d30fb3c) Subject: Document $^M in perlvar Date: Thu, 20 Mar 97 21:08:33 GMT From: Robin Barker Files: pod/perlvar.pod private-msgid: 6153.9703202108@tempest.cise.npl.co.uk Subject: typos in pods of 5.003_93 Date: 19 Mar 1997 10:39:38 -0600 From: Jim Meyering Files: pod/perlfunc.pod pod/perlguts.pod pod/perlre.pod pod/perltoot.pod pod/perlxs.pod Msg-ID: wpgendbzvhx.fsf@asic.sc.ti.com (applied based on p5p patch as commit 76a9873e006cf8f48f57062b2a0dd40b5ed45a95) Subject: Re: Updates to pod punctuations Date: Fri, 14 Mar 1997 17:00:12 -0500 From: Larry W. Virden Files: pod/*.pod private-msgid: 9703141700.AA22911@cas.org Subject: clarify example in perlfunc Date: Thu, 20 Mar 1997 19:46:01 +0200 (EET) From: Jarkko Hietaniemi Files: pod/perlfunc.pod private-msgid: 199703201746.TAA25195@alpha.hut.fi Subject: Regularize headings in DB_File documentation From: Chip Salzenberg Files: ext/DB_File/DB_File.pm LIBRARY AND EXTENSIONS Subject: New module: autouse.pm Date: Thu, 20 Mar 1997 19:34:30 -0500 (EST) From: Ilya Zakharevich Files: MANIFEST lib/autouse.pm Msg-ID: 199703210034.TAA13469@monk.mps.ohio-state.edu (applied based on p5p patch as commit 6757905eccb6dd0440ef65e8128a277a20f7d943) Subject: Refresh DB_File to 1.12 Date: Wed, 12 Mar 97 15:51:14 GMT From: Paul Marquess Files: ext/DB_File/DB_File.pm ext/DB_File/DB_File.xs Msg-ID: 9703121551.AA07435@claudius.bfsec.bt.co.uk (applied based on p5p patch as commit b3deed9189f963e9994815307931f9084f60d1d9) Subject: In File::Path, some systems can't remove read-only files From: Chip Salzenberg Files: lib/File/Path.pm Subject: Fix bugs revealed by prototype warnings From: Chip Salzenberg Files: ext/Opcode/Opcode.pm lib/ExtUtils/MakeMaker.pm lib/Getopt/Long.pm Subject: Problems with SKIP in makemaker Date: Thu, 20 Mar 1997 23:13:31 -0500 (EST) From: Ilya Zakharevich Files: lib/ExtUtils/MM_Unix.pm Msg-ID: 199703210413.XAA21601@monk.mps.ohio-state.edu (applied based on p5p patch as commit 970322a2e8024294ada6e8d1a027cb98f1f48ee3) Subject: In Exporter, don't C at file scope From: Chip Salzenberg Files: lib/Exporter.pm Subject: fix for Exporter's $SIG{__WARN__} handler Date: Thu, 13 Mar 1997 18:40:51 -0500 From: Roderick Schertler Files: lib/Exporter.pm Msg-ID: 2282.858296451@eeyore.ibcinc.com (applied based on p5p patch as commit 2768ea1aeef34f42d096f198fbe629c8374ca429) Subject: Don't try to substr() refs in Carp From: Chip Salzenberg Files: lib/Carp.pm Subject: Re: NUL in die and other messages Date: Fri, 21 Mar 1997 09:58:17 +0000 From: "M.J.T. Guy" Files: lib/Carp.pm Msg-ID: E0w815V-0005xs-00@ursa.cus.cam.ac.uk (applied based on p5p patch as commit 52a267c574cb66c4bc35601dcf148a1d7a3bc557) OTHER CORE CHANGES Subject: Guard against buffer overflow in yyerror() and related funcs From: Chip Salzenberg Files: toke.c Subject: For bin compat, rename calllist() and he_{,delay}free From: Chip Salzenberg Files: global.sym hv.c op.c perl.c pod/perlguts.pod proto.h Subject: Fix C on tied default handle From: Chip Salzenberg Files: pp_hot.c Subject: Fix C From: Chip Salzenberg Files: op.c Subject: Improve diagnostic on C<@a++>, C<--%a>, @a =~ s/a/b/ From: Chip Salzenberg Files: pp.c pp_hot.c Subject: Don't warn on C<$x{y} .= "z"> when %x is tied From: Chip Salzenberg Files: pp_hot.c Subject: Eliminate 'unreachable code' warnings From: Chip Salzenberg Files: ext/POSIX/POSIX.xs mg.c pp_ctl.c toke.c Subject: printf format corrections for -DDEBUGGING Date: Wed, 19 Mar 1997 12:42:50 -0500 From: Roderick Schertler Files: doop.c malloc.c op.c pp_ctl.c regexec.c sv.c x2p/str.c x2p/util.c Msg-ID: 26592.858793370@eeyore.ibcinc.com (applied based on p5p patch as commit e125f273e351a19a92b69d6244af55abbbf0a26d) Subject: Warn about missing -DMULTIPLICITY if likely a problem Date: Wed, 19 Mar 1997 18:45:53 -0500 From: Doug MacEachern Files: perl.c Msg-ID: 199703192345.SAA15070@postman.osf.org (applied based on p5p patch as commit 71aeea1753924e6e19c2461e241e3f7d8a570e90) --- pod/Makefile | 40 ++ pod/buildtoc | 12 +- pod/perl.pod | 3 +- pod/perlcall.pod | 4 +- pod/perldata.pod | 33 +- pod/perldebug.pod | 8 +- pod/perldelta.pod | 26 +- pod/perldiag.pod | 65 ++-- pod/perldsc.pod | 2 +- pod/perlfaq.pod | 138 +++++++ pod/perlfaq1.pod | 248 +++++++++++++ pod/perlfaq2.pod | 419 +++++++++++++++++++++ pod/perlfaq3.pod | 503 +++++++++++++++++++++++++ pod/perlfaq4.pod | 1034 ++++++++++++++++++++++++++++++++++++++++++++++++++++ pod/perlfaq5.pod | 788 +++++++++++++++++++++++++++++++++++++++ pod/perlfaq6.pod | 580 +++++++++++++++++++++++++++++ pod/perlfaq7.pod | 675 ++++++++++++++++++++++++++++++++++ pod/perlfaq8.pod | 749 +++++++++++++++++++++++++++++++++++++ pod/perlfaq9.pod | 277 ++++++++++++++ pod/perlform.pod | 8 +- pod/perlfunc.pod | 51 +-- pod/perlguts.pod | 51 +-- pod/perlipc.pod | 59 +++ pod/perllocale.pod | 4 +- pod/perlobj.pod | 2 +- pod/perlop.pod | 28 +- pod/perlre.pod | 22 +- pod/perlrun.pod | 78 ++++ pod/perlsec.pod | 35 ++ pod/perltoc.pod | 859 ++++++++++++++++++++++++++++++++++++++++++- pod/perltoot.pod | 10 +- pod/perltrap.pod | 38 +- pod/perlvar.pod | 17 + pod/perlxs.pod | 2 +- pod/perlxstut.pod | 2 +- pod/roffitall | 10 + 36 files changed, 6740 insertions(+), 140 deletions(-) create mode 100644 pod/perlfaq.pod create mode 100644 pod/perlfaq1.pod create mode 100644 pod/perlfaq2.pod create mode 100644 pod/perlfaq3.pod create mode 100644 pod/perlfaq4.pod create mode 100644 pod/perlfaq5.pod create mode 100644 pod/perlfaq6.pod create mode 100644 pod/perlfaq7.pod create mode 100644 pod/perlfaq8.pod create mode 100644 pod/perlfaq9.pod (limited to 'pod') 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 enough hype. +Okay, that's I 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 for details +See the L 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 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 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 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 and +L 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). -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 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 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 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 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. =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 command might +Here's an example of what a stack backtrace via C 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 -or B, the stack back-trace will not show the original values. +or B, 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 +reset when an already-open file handle is re-opened with no intervening +call to C. Due to a bug, perl versions 5.000 through 5.0003 +I 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) =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 returns I if its object is blessed into a sub-class of C +C returns I if its object is blessed into a subclass of C C 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). 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. +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. Trappable errors may be trapped using the eval operator. See L. @@ -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 subroutine (or a C directive, which +implies a C) after one or more compilation errors had +already occurred. Since the intended environment for the C +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. CEEOF;>). Note that Perl always -opens scripts in text mode, so this error should only occur in C. +here documents (e.g., CEEOF;>). + +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 operator). + +In either case, the Perl code in question will probably need to be +converted with something like C 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 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 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. =item Substitution pattern not terminated @@ -2490,13 +2511,13 @@ L for more on this. (W) A copy of the object returned from C (or C) was still valid when C 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 , <*> (glob), or -C 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 operator. +(W) In a conditional expression, you used , <*> (glob), C, +or C 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 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 command which is nearly the same. +There's also a lowercase B 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: General Questions About Perl + +Very general, high-level information about Perl. + +=item L: Obtaining and Learning about Perl + +Where to find source and documentation to Perl, support and training, +and related matters. + +=item L: Programming Tools + +Programmer tools and programming support. + +=item L: Data Manipulation + +Manipulating numbers, dates, strings, arrays, hashes, and +miscellaneous data issues. + +=item L: Files and Formats + +I/O and the "f" issues: filehandles, flushing, formats and footers. + +=item L: Regexps + +Pattern matching and regular expressions. + +=item L: General Perl Language Issues + +General Perl language issues that don't clearly fit into any of the +other sections. + +=item L: System Interaction + +Interprocess communication (IPC), control over the user-interface +(keyboard, screen and pointing devices). + +=item L: 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. + +=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 has been compiled to physical +machine code once, and can then be be run multiple times, whereas a +I