diff options
| author | Perl 5 Porters <perl5-porters@africa.nicoh.com> | 1997-03-26 07:04:34 +1200 |
|---|---|---|
| committer | Chip Salzenberg <chip@atlantic.net> | 1997-03-26 07:04:34 +1200 |
| commit | 54310121b442974721115f93666234a200f5c7e4 (patch) | |
| tree | 99b5953030ddf062d77206ac0cf8ac967e7cbd93 /pod | |
| parent | d03407ef6d8e534a414e9ce92c6c5c8dab664a40 (diff) | |
| download | perl-54310121b442974721115f93666234a200f5c7e4.tar.gz | |
[inseperable changes from patch from perl-5.003_95 to perl-5.003_86]
[editor's note: this commit was prepared manually so may differ in
minor ways to other inseperable changes commits]
CORE LANGUAGE CHANGES
Title: "Support $ENV{PERL5OPT}"
From: Chip Salzenberg
Files: perl.c pod/perldiag.pod pod/perldelta.pod pod/perlrun.pod
Title: "Implement void context, in which C<wantarray> is undef"
From: Chip Salzenberg
Files: cop.h doop.c dump.c global.sym gv.c op.c op.h perl.c
pod/perlcall.pod pod/perldelta.pod pod/perlfunc.pod
pod/perlguts.pod pod/perlsub.pod pp.c pp_ctl.c pp_hot.c
pp_sys.c proto.h
Title: "Don't look up &AUTOLOAD in @ISA when calling plain function"
From: Chip Salzenberg
Files: global.sym gv.c lib/Text/ParseWords.pm pod/perldelta.pod
pp_hot.c proto.h t/op/method.t
Title: "Allow closures to be constant subroutines"
From: Chip Salzenberg
Files: op.c
Title: "Make C<scalar(reverse)> mean C<scalar(reverse $_)>"
From: Chip Salzenberg
Files: pp.c
Title: "Fix lexical suicide from C<my $x = $x> in sub"
From: Chip Salzenberg
Files: op.c
Title: "Make "Unrecog. char." fatal, and update its doc"
From: Chip Salzenberg
Files: pod/perldiag.pod toke.c
CORE PORTABILITY
Title: "safefree() mismatch"
From: Roderick Schertler
Msg-ID: <21338.859653381@eeyore.ibcinc.com>
Date: Sat, 29 Mar 1997 11:36:21 -0500
Files: util.c
(applied based on p5p patch as commit id 9b9b466fb02dc96c81439bafbb3b2da55238cfd2)
Title: "Win32 update (seven patches)"
From: Gurusamy Sarathy and Nick Ing-Simmons
Files: EXTERN.h MANIFEST win32/Makefile win32/perl.mak
win32/perl.rc win32/perldll.mak win32/makedef.pl
win32/modules.mak win32/win32io.c win32/bin/pl2bat.bat
OTHER CORE CHANGES
Title: "Report PERL* environment variables in -V and perlbug"
From: Chip Salzenberg
Files: perl.c utils/perlbug.PL
Title: "Typo in perl.c: Printing NO_EMBED for perl -V"
From: Gisle Aas
Msg-ID: <199703301922.VAA13509@furubotn.sn.no>
Date: Sun, 30 Mar 1997 21:22:11 +0200
Files: perl.c
(applied based on p5p patch as commit id b6c639e4b1912ad03b9b10ba9518d96bd0a6cfaf)
Title: "Don't let C<$var = $var> untaint $var"
From: Chip Salzenberg
Files: pp_hot.c pp_sys.c sv.h t/op/taint.t
Title: "Fix autoviv bug in C<my $x; ++$x->{KEY}>"
From: Chip Salzenberg
Files: pp_hot.c
Title: "Re: 5.004's new srand() default seed"
From: Hallvard B Furuseth
Msg-ID: <199703302219.AAA20998@bombur2.uio.no>
Date: Mon, 31 Mar 1997 00:19:13 +0200 (MET DST)
Files: pp.c
(applied based on p5p patch as commit id d7d933a26349f945f93b2f0dbf85b773d8ca3219)
Title: "Re: embedded perl and top_env problem "
From: Gurusamy Sarathy
Msg-ID: <199703280031.TAA05711@aatma.engin.umich.edu>
Date: Thu, 27 Mar 1997 19:31:42 -0500
Files: gv.c interp.sym perl.c perl.h pp_ctl.c pp_sys.c scope.h util.c
(applied based on p5p patch as commit id f289f7d2518e7a8a82114282e774adf50fa6ce85)
Title: "Define and use new macro: boolSV()"
From: Tim Bunce
Files: gv.c lib/ExtUtils/typemap os2/os2.c pp.c pp_hot.c pp_sys.c
sv.c sv.h universal.c vms/vms.c
Title: "Re: strict @F"
From: Hallvard B Furuseth
Msg-ID: <199703252110.WAA16038@bombur2.uio.no>
Date: Tue, 25 Mar 1997 22:10:33 +0100 (MET)
Files: toke.c
(applied based on p5p patch as commit id dfd44a5c8c8dd4c001c595debfe73d011a96d844)
Title: "Try harder to identify errors at EOF"
From: Chip Salzenberg
Files: toke.c
Title: "Minor string change in toke.c: 'bareword'"
From: lvirden@cas.org
Msg-ID: <1997Mar27.130247.1911552@hmivax.humgen.upenn.edu>
Date: Thu, 27 Mar 1997 13:02:46 -0500 (EST)
Files: toke.c
(applied based on p5p patch as commit id 9b56c8f8085a9e773ad87c6b3c1d0b5e39dbc348)
Title: "Improve diagnostic on \r in program text"
From: Chip Salzenberg
Files: pod/perldiag.pod toke.c
Title: "Make Sock_size_t typedef work right"
From: Chip Salzenberg
Files: perl.h pp_sys.c
LIBRARY AND EXTENSIONS
Title: "New module constant.pm"
From: Tom Phoenix
Files: MANIFEST lib/constant.pm op.c pp.c t/pragma/constant.t
Title: "Remove chat2"
From: Chip Salzenberg
Files: MANIFEST lib/chat2.inter lib/chat2.pl
Title: "Include CGI.pm 2.32"
From: Chip Salzenberg
Files: MANIFEST eg/cgi/* lib/CGI.pm lib/CGI/Apache.pm
lib/CGI/Carp.pm lib/CGI/Fast.pm lib/CGI/Push.pm
lib/CGI/Switch.pm
UTILITIES
Title: "Tom C's Pod::Html and html tools, as of 30 March 97"
From: Chip Salzenberg
Files: MANIFEST installhtml lib/Pod/Html.pm pod/pod2html.PL
Title: "Fix path bugs in installhtml"
From: Robin Barker <rmb1@cise.npl.co.uk>
Msg-ID: <3180.9703270906@tempest.cise.npl.co.uk>
Date: Thu, 27 Mar 97 09:06:14 GMT
Files: installhtml
Title: "Make perlbug say that it's only for core Perl bugs"
From: Chip Salzenberg
Files: utils/perlbug.PL
DOCUMENTATION
Title: "Document autouse and constant; update diagnostics"
From: Chip Salzenberg
Files: pod/perldelta.pod
Title: "Suggest to upgraders that they try '-w' again"
From: Hallvard B Furuseth
Msg-ID: <199703251901.UAA15982@bombur2.uio.no>
Date: Tue, 25 Mar 1997 20:01:26 +0100 (MET)
Files: pod/perldelta.pod
(applied based on p5p patch as commit id 4176c059b9ba6b022e99c44270434a5c3e415b73)
Title: "Improve and update documentation of constant subs"
From: Tom Phoenix <rootbeer@teleport.com>
Msg-ID: <Pine.GSO.3.96.970331122546.14185C-100000@kelly.teleport.com>
Date: Mon, 31 Mar 1997 13:05:54 -0800 (PST)
Files: pod/perlsub.pod
Title: "Improve documentation of C<return>"
From: Chip Salzenberg
Files: pod/perlfunc.pod pod/perlsub.pod
Title: "perlfunc.pod patch"
From: Gisle Aas
Msg-ID: <199703262159.WAA17531@furubotn.sn.no>
Date: Wed, 26 Mar 1997 22:59:23 +0100
Files: pod/perlfunc.pod
(applied based on p5p patch as commit id 35a731fcbcd7860eb497d6598f3f77b8746319c4)
Title: "Use 'while (defined($x = <>)) {}', per <gnat@frii.com>"
From: Chip Salzenberg
Files: configpm lib/Term/Cap.pm perlsh pod/perlipc.pod pod/perlop.pod
pod/perlsub.pod pod/perlsyn.pod pod/perltrap.pod
pod/perlvar.pod win32/bin/search.bat
Title: "Document and test C<%> behavior with negative operands"
From: Chip Salzenberg
Files: pod/perlop.pod t/op/arith.t
Title: "Update docs on $]"
From: Chip Salzenberg
Files: pod/perlvar.pod
Title: "perlvar.pod patch"
From: Gisle Aas
Msg-ID: <199703261254.NAA10237@bergen.sn.no>
Date: Wed, 26 Mar 1997 13:54:00 +0100
Files: pod/perlvar.pod
(applied based on p5p patch as commit id 0aa182cb0caa3829032904b9754807b1b7418509)
Title: "Fix example of C<or> vs. C<||>"
From: Chip Salzenberg
Files: pod/perlsyn.pod
Title: "Pod usage and spelling patch"
From: Larry W. Virden
Files: pod/*.pod
Title: "Pod updates"
From: "Cary D. Renzema" <caryr@mxim.com>
Msg-ID: <199703262353.PAA01819@macs.mxim.com>
Date: Wed, 26 Mar 1997 15:53:22 -0800 (PST)
Files: pod/*.pod
(applied based on p5p patch as commit id 5695b28edc67a3f45e8a0f25755d07afef3660ac)
Diffstat (limited to 'pod')
43 files changed, 2000 insertions, 2007 deletions
diff --git a/pod/perlapio.pod b/pod/perlapio.pod index 2a2a99fc60..d88e44509c 100644 --- a/pod/perlapio.pod +++ b/pod/perlapio.pod @@ -7,16 +7,16 @@ perlapio - perl's IO abstraction interface. PerlIO *PerlIO_stdin(void); PerlIO *PerlIO_stdout(void); PerlIO *PerlIO_stderr(void); - + PerlIO *PerlIO_open(const char *,const char *); int PerlIO_close(PerlIO *); int PerlIO_stdoutf(const char *,...) int PerlIO_puts(PerlIO *,const char *); int PerlIO_putc(PerlIO *,int); - int PerlIO_write(PerlIO *,const void *,size_t); + int PerlIO_write(PerlIO *,const void *,size_t); int PerlIO_printf(PerlIO *, const char *,...); - int PerlIO_vprintf(PerlIO *, const char *, va_list); + int PerlIO_vprintf(PerlIO *, const char *, va_list); int PerlIO_flush(PerlIO *); int PerlIO_eof(PerlIO *); @@ -25,7 +25,7 @@ perlapio - perl's IO abstraction interface. int PerlIO_getc(PerlIO *); int PerlIO_ungetc(PerlIO *,int); - int PerlIO_read(PerlIO *,void *,size_t); + int PerlIO_read(PerlIO *,void *,size_t); int PerlIO_fileno(PerlIO *); PerlIO *PerlIO_fdopen(int, const char *); @@ -34,30 +34,30 @@ perlapio - perl's IO abstraction interface. FILE *PerlIO_findFILE(PerlIO *); void PerlIO_releaseFILE(PerlIO *,FILE *); - void PerlIO_setlinebuf(PerlIO *); + void PerlIO_setlinebuf(PerlIO *); long PerlIO_tell(PerlIO *); int PerlIO_seek(PerlIO *,off_t,int); - int PerlIO_getpos(PerlIO *,Fpos_t *) - int PerlIO_setpos(PerlIO *,Fpos_t *) + int PerlIO_getpos(PerlIO *,Fpos_t *) + int PerlIO_setpos(PerlIO *,Fpos_t *) void PerlIO_rewind(PerlIO *); - - int PerlIO_has_base(PerlIO *); - int PerlIO_has_cntptr(PerlIO *); - int PerlIO_fast_gets(PerlIO *); - int PerlIO_canset_cnt(PerlIO *); - - char *PerlIO_get_ptr(PerlIO *); - int PerlIO_get_cnt(PerlIO *); - void PerlIO_set_cnt(PerlIO *,int); - void PerlIO_set_ptrcnt(PerlIO *,char *,int); - char *PerlIO_get_base(PerlIO *); - int PerlIO_get_bufsiz(PerlIO *); + + int PerlIO_has_base(PerlIO *); + int PerlIO_has_cntptr(PerlIO *); + int PerlIO_fast_gets(PerlIO *); + int PerlIO_canset_cnt(PerlIO *); + + char *PerlIO_get_ptr(PerlIO *); + int PerlIO_get_cnt(PerlIO *); + void PerlIO_set_cnt(PerlIO *,int); + void PerlIO_set_ptrcnt(PerlIO *,char *,int); + char *PerlIO_get_base(PerlIO *); + int PerlIO_get_bufsiz(PerlIO *); =head1 DESCRIPTION Perl's source code should use the above functions instead of those -defined in ANSI C's I<stdio.h>, I<perlio.h> will the C<#define> them to +defined in ANSI C's I<stdio.h>, I<perlio.h> will the C<#define> them to the I/O mechanism selected at Configure time. The functions are modeled on those in I<stdio.h>, but parameter order @@ -67,15 +67,15 @@ has been "tidied up a little". =item B<PerlIO *> -This takes the place of FILE *. Unlike FILE * it should be treated as +This takes the place of FILE *. Unlike FILE * it should be treated as opaque (it is probably safe to assume it is a pointer to something). =item B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()> Use these rather than C<stdin>, C<stdout>, C<stderr>. They are written to look like "function calls" rather than variables because this makes -it easier to I<make them> function calls if platform cannot export data -to loaded modules, or if (say) different "threads" might have different +it easier to I<make them> function calls if platform cannot export data +to loaded modules, or if (say) different "threads" might have different values. =item B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)> @@ -93,7 +93,7 @@ so it is (currently) legal to use C<printf(fmt,...)> in perl sources. =item B<PerlIO_read(f,buf,count)>, B<PerlIO_write(f,buf,count)> -These correspond to fread() and fwrite(). Note that arguments +These correspond to fread() and fwrite(). Note that arguments are different, there is only one "count" and order has "file" first. @@ -101,7 +101,7 @@ are different, there is only one "count" and order has =item B<PerlIO_puts(s,f)>, B<PerlIO_putc(c,f)> -These correspond to fputs() and fputc(). +These correspond to fputs() and fputc(). Note that arguments have been revised to have "file" first. =item B<PerlIO_ungetc(c,f)> @@ -123,8 +123,8 @@ This corresponds to ferror(). =item B<PerlIO_fileno(f)> -This corresponds to fileno(), note that on some platforms, -the meaning of "fileno" may not match UNIX. +This corresponds to fileno(), note that on some platforms, +the meaning of "fileno" may not match Unix. =item B<PerlIO_clearerr(f)> @@ -145,7 +145,7 @@ This corresponds to fseek(). =item B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)> -These correspond to fgetpos() and fsetpos(). If platform does not +These correspond to fgetpos() and fsetpos(). If platform does not have the stdio calls then they are implemented in terms of PerlIO_tell() and PerlIO_seek(). @@ -159,14 +159,14 @@ in terms of PerlIO_seek() at some point. This corresponds to tmpfile(), i.e., returns an anonymous PerlIO which will automatically be deleted when closed. -=back +=back =head2 Co-existence with stdio There is outline support for co-existence of PerlIO with stdio. -Obviously if PerlIO is implemented in terms of stdio there is +Obviously if PerlIO is implemented in terms of stdio there is no problem. However if perlio is implemented on top of (say) sfio -then mechanisms must exist to create a FILE * which can be passed +then mechanisms must exist to create a FILE * which can be passed to library code which is going to use stdio calls. =over 4 @@ -179,12 +179,12 @@ May need additional arguments, interface under review. =item B<PerlIO_exportFILE(f,flags)> Given an PerlIO * return a 'native' FILE * suitable for -passing to code expecting to be compiled and linked with +passing to code expecting to be compiled and linked with ANSI C I<stdio.h>. The fact that such a FILE * has been 'exported' is recorded, -and may affect future PerlIO operations on the original -PerlIO *. +and may affect future PerlIO operations on the original +PerlIO *. =item B<PerlIO_findFILE(f)> @@ -195,7 +195,7 @@ Place holder until interface is fully defined. Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is complete. It is removed from list of 'exported' -FILE *s, and associated PerlIO * should revert to original +FILE *s, and associated PerlIO * should revert to original behaviour. =item B<PerlIO_setlinebuf(f)> @@ -230,21 +230,21 @@ Return count of readable bytes in the buffer. =item B<PerlIO_canset_cnt(f)> -Implementation can adjust its idea of number of +Implementation can adjust its idea of number of bytes in the buffer. =item B<PerlIO_fast_gets(f)> -Implementation has all the interfaces required to +Implementation has all the interfaces required to allow perl's fast code to handle <FILE> mechanism. - PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \ + PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \ PerlIO_canset_cnt(f) && \ `Can set pointer into buffer' =item B<PerlIO_set_ptrcnt(f,p,c)> -Set pointer into buffer, and a count of bytes still in the +Set pointer into buffer, and a count of bytes still in the buffer. Should be used only to set pointer to within range implied by previous calls to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>. @@ -255,7 +255,7 @@ Obscure - set count of bytes in the buffer. Deprecated. Currently used in only doio.c to force count < -1 to -1. Perhaps should be PerlIO_set_empty or similar. This call may actually do nothing if "count" is deduced from pointer -and a "limit". +and a "limit". =item B<PerlIO_has_base(f)> @@ -271,4 +271,4 @@ Return I<start> of buffer. Return I<total size> of buffer. -=back +=back diff --git a/pod/perlbot.pod b/pod/perlbot.pod index 30d00558b4..bc4e4da1f7 100644 --- a/pod/perlbot.pod +++ b/pod/perlbot.pod @@ -265,7 +265,7 @@ This example demonstrates an interface for the SDBM class. This creates a $ref->FETCH(@_); } sub STORE { - my $self = shift; + my $self = shift; if (defined $_[0]){ my $ref = $self->{'dbm'}; $ref->STORE(@_); @@ -420,7 +420,7 @@ method where that data is located. sub enter { my $self = shift; - + # Don't try to guess if we should use %Bar::fizzle # or %Foo::fizzle. The object already knows which # we should use, so just ask it. diff --git a/pod/perlcall.pod b/pod/perlcall.pod index 8236102f80..b69c539420 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -126,6 +126,31 @@ which can consist of any combination of the symbols defined below, OR'ed together. +=head2 G_VOID + +Calls the Perl subroutine in a void context. + +This flag has 2 effects: + +=over 5 + +=item 1. + +It indicates to the subroutine being called that it is executing in +a void context (if it executes I<wantarray> the result will be the +undefined value). + +=item 2. + +It ensures that nothing is actually returned from the subroutine. + +=back + +The value returned by the I<perl_call_*> function indicates how many +items have been returned by the Perl subroutine - in this case it will +be 0. + + =head2 G_SCALAR Calls the Perl subroutine in a scalar context. This is the default @@ -140,7 +165,6 @@ This flag has 2 effects: It indicates to the subroutine being called that it is executing in a scalar context (if it executes I<wantarray> the result will be false). - =item 2. It ensures that only a scalar is actually returned from the subroutine. @@ -164,7 +188,7 @@ accessible from the stack - think of the case where only one value is returned as being a list with only one element. Any other items that were returned will not exist by the time control returns from the I<perl_call_*> function. The section I<Returning a list in a scalar -context> shows an example of this behaviour. +context> shows an example of this behavior. =head2 G_ARRAY @@ -251,7 +275,7 @@ What has happened is that C<fred> accesses the C<@_> array which belongs to C<joe>. -=head2 G_EVAL +=head2 G_EVAL It is possible for the Perl subroutine you are calling to terminate abnormally, e.g., by calling I<die> explicitly or by not actually @@ -293,7 +317,7 @@ from the stack. =back -See I<Using G_EVAL> for details of using G_EVAL. +See I<Using G_EVAL> for details on using G_EVAL. =head2 G_KEEPERR @@ -326,14 +350,17 @@ The G_KEEPERR flag was introduced in Perl version 5.002. See I<Using G_KEEPERR> for an example of a situation that warrants the use of this flag. -=head2 Determining the Context +=head2 Determining the Context As mentioned above, you can determine the context of the currently -executing subroutine in Perl with I<wantarray>. The equivalent test can -be made in C by using the C<GIMME> macro. This will return C<G_SCALAR> -if you have been called in a scalar context and C<G_ARRAY> if in an -array context. An example of using the C<GIMME> macro is shown in -section I<Using GIMME>. +executing subroutine in Perl with I<wantarray>. The equivalent test +can be made in C by using the C<GIMME_V> macro, which returns +C<G_ARRAY> if you have been called in an array context, C<G_SCALAR> if +in a a scalar context, or C<G_VOID> if in a void context (i.e. the +return value will not be used). An older version of this macro is +called C<GIMME>; in a void context it returns C<G_SCALAR> instead of +C<G_VOID>. An example of using the C<GIMME_V> macro is shown in +section I<Using GIMME_V>. =head1 KNOWN PROBLEMS @@ -368,7 +395,7 @@ For example, say you want to call this Perl sub sub fred { eval { die "Fatal Error" ; } - print "Trapped error: $@\n" + print "Trapped error: $@\n" if $@ ; } @@ -565,7 +592,7 @@ Next, we come to XPUSHs. This is where the parameters actually get pushed onto the stack. In this case we are pushing a string and an integer. -See the L<perlguts/"XSUBs and the Argument Stack"> for details +See L<perlguts/"XSUBs and the Argument Stack"> for details on how the XPUSH macros work. =item 6. @@ -626,7 +653,7 @@ Points to note this time are =over 5 -=item 1. +=item 1. The only flag specified this time was G_SCALAR. That means the C<@_> array will be created and that the value returned by I<Adder> will @@ -654,7 +681,7 @@ temporaries we create. This means that the temporaries we get rid of will be limited to those which were created after these calls. The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by -the Perl subroutine, plus it will also dump the mortal SV's we have +the Perl subroutine, plus it will also dump the mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the beginning of the code makes sure that no other mortals are destroyed. @@ -672,7 +699,7 @@ allocated to the Perl stack has been reallocated whilst in the I<perl_call_pv> call. If you are making use of the Perl stack pointer in your code you must -always refresh the your local copy using SPAGAIN whenever you make use +always refresh the local copy using SPAGAIN whenever you make use of the I<perl_call_*> functions or any other Perl internal function. =item 4. @@ -834,7 +861,7 @@ then the output will be Value 1 = 3 In this case the main point to note is that only the last item in the -list returned from the subroutine, I<Adder> actually made it back to +list is returned from the subroutine, I<AddSubtract> actually made it back to I<call_AddSubScalar>. @@ -977,7 +1004,7 @@ I<Subtract>. =item 2. -The code +The code if (SvTRUE(GvSV(errgv))) { @@ -1012,7 +1039,7 @@ version of the call_Subtract example above inside a destructor: package Foo; sub new { bless {}, $_[0] } - sub Subtract { + sub Subtract { my($a,$b) = @_; die "death can be fatal" if $a < $b ; $a - $b; @@ -1063,7 +1090,7 @@ Here is a snippet of XSUB which defines I<CallSubPV>. PUSHMARK(sp) ; perl_call_pv(name, G_DISCARD|G_NOARGS) ; -That is fine as far as it goes. The thing is, the Perl subroutine +That is fine as far as it goes. The thing is, the Perl subroutine can be specified as only a string. For Perl 4 this was adequate, but Perl 5 allows references to subroutines and anonymous subroutines. This is where I<perl_call_sv> is useful. @@ -1121,22 +1148,22 @@ particularly true for these cases CallSavedSub1() ; By the time each of the C<SaveSub1> statements above have been executed, -the SV*'s which corresponded to the parameters will no longer exist. +the SV*s which corresponded to the parameters will no longer exist. Expect an error message from Perl of the form Can't use an undefined value as a subroutine reference at ... for each of the C<CallSavedSub1> lines. -Similarly, with this code +Similarly, with this code $ref = \&fred ; SaveSub1($ref) ; $ref = 47 ; CallSavedSub1() ; -you can expect one of these messages (which you actually get is dependent on -the version of Perl you are using) +you can expect one of these messages (which you actually get is dependent on +the version of Perl you are using) Not a CODE reference at ... Undefined subroutine &main::47 called ... @@ -1159,7 +1186,7 @@ A similar but more subtle problem is illustrated with this code CallSavedSub1() ; This time whenever C<CallSavedSub1> get called it will execute the Perl -subroutine C<joe> (assuming it exists) rather than C<fred> as was +subroutine C<joe> (assuming it exists) rather than C<fred> as was originally requested in the call to C<SaveSub1>. To get around these problems it is necessary to take a full copy of the @@ -1260,7 +1287,7 @@ single element of the array. Here is an all Perl example of using it. will print 1: green - This is Class Mine version 1.0 + This is Class Mine version 1.0 Calling a Perl method from C is fairly straightforward. The following things are required @@ -1320,26 +1347,31 @@ The only thing to note is that in both the static and virtual methods, the method name is not passed via the stack - it is used as the first parameter to I<perl_call_method>. -=head2 Using GIMME +=head2 Using GIMME_V -Here is a trivial XSUB which prints the context in which it is +Here is a trivial XSUB which prints the context in which it is currently executing. void PrintContext() CODE: - if (GIMME == G_SCALAR) + I32 gimme = GIMME_V; + if (gimme == G_VOID) + printf ("Context is Void\n") ; + else if (gimme == G_SCALAR) printf ("Context is Scalar\n") ; else printf ("Context is Array\n") ; and here is some Perl to test it + PrintContext ; $a = PrintContext ; @a = PrintContext ; The output from that will be + Context is Void Context is Scalar Context is Array @@ -1418,26 +1450,26 @@ will be more like this perl --> XSUB --> event handler ... - event handler --> perl_call --> perl + event handler --> perl_call --> perl | - event handler <-- perl_call --<--+ + event handler <-- perl_call <----+ ... - event handler --> perl_call --> perl + event handler --> perl_call --> perl | - event handler <-- perl_call --<--+ + event handler <-- perl_call <----+ ... - event handler --> perl_call --> perl + event handler --> perl_call --> perl | - event handler <-- perl_call --<--+ + event handler <-- perl_call <----+ In this case the flow of control can consist of only the repeated sequence event handler --> perl_call --> perl -for the practically the complete duration of the program. This means -that control may I<never> drop back to the surrounding scope in Perl at -the extreme left. +for practically the complete duration of the program. This means that +control may I<never> drop back to the surrounding scope in Perl at the +extreme left. So what is the big problem? Well, if you are expecting Perl to tidy up those temporaries for you, you might be in for a long wait. For Perl @@ -1553,7 +1585,7 @@ This may expect the C I<ProcessRead> function of this form int fh ; char * buffer ; { - ... + ... } To provide a Perl interface to this library we need to be able to map @@ -1646,7 +1678,7 @@ the C<buffer> parameter like this Without the file handle there is no straightforward way to map from the C callback to the Perl subroutine. -In this case a possible way around this problem is to pre-define a +In this case a possible way around this problem is to predefine a series of C functions to act as the interface to Perl, thus #define MAX_CB 3 @@ -1763,7 +1795,7 @@ series of C functions to act as the interface to Perl, thus In this case the functions C<fn1>, C<fn2>, and C<fn3> are used to remember the Perl subroutine to be called. Each of the functions holds -a separate hard-wired index which is used in the function C<Pcb> to +a separate hardwired index which is used in the function C<Pcb> to access the C<Map> array and actually call the Perl subroutine. There are some obvious disadvantages with this technique. @@ -1771,10 +1803,10 @@ There are some obvious disadvantages with this technique. Firstly, the code is considerably more complex than with the previous example. -Secondly, there is a hard-wired limit (in this case 3) to the number of +Secondly, there is a hardwired limit (in this case 3) to the number of callbacks that can exist simultaneously. The only way to increase the limit is by modifying the code to add more functions and then -re-compiling. None the less, as long as the number of functions is +recompiling. None the less, as long as the number of functions is chosen with some care, it is still a workable solution and in some cases is the only one available. @@ -1878,7 +1910,7 @@ sets the stack up so that we can use the C<ST> macro. Unlike the original coding of this example, the returned values are not accessed in reverse order. So C<ST(0)> refers to the -first value returned by the Perl subroutine and C<ST(count-1)> +first value returned by the Perl subroutine and C<ST(count-1)> refers to the last. =back diff --git a/pod/perldata.pod b/pod/perldata.pod index b69e77e3d7..2a43319b51 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -145,12 +145,12 @@ type "filehandle", or anything else. Perl is a contextually polymorphic language whose scalars can be strings, numbers, or references (which includes objects). While strings and numbers are considered pretty much the same thing for nearly all purposes, references are strongly-typed -uncastable pointers with built-in reference-counting and destructor +uncastable pointers with builtin reference-counting and destructor invocation. A scalar value is interpreted as TRUE in the Boolean sense if it is not the null string or the number 0 (or its string equivalent, "0"). The -Boolean context is just a special kind of scalar context. +Boolean context is just a special kind of scalar context. There are actually two varieties of null scalars: defined and undefined. Undefined null scalars are returned when there is no real @@ -160,14 +160,14 @@ array. An undefined null scalar may become defined the first time you use it as if it were defined, but prior to that you can use the defined() operator to determine whether the value is defined or not. -To find out whether a given string is a valid non-zero number, it's usually +To find out whether a given string is a valid nonzero number, it's usually enough to test it against both numeric 0 and also lexical "0" (although this will cause B<-w> noises). That's because strings that aren't numbers count as 0, just as they do in B<awk>: if ($str == 0 && $str ne "0") { warn "That doesn't look like a number"; - } + } That's usually preferable because otherwise you won't treat IEEE notations like C<NaN> or C<Infinity> properly. At other times you might prefer to @@ -176,9 +176,9 @@ for details on regular expressions. warn "has nondigits" if /\D/; warn "not a whole number" unless /^\d+$/; - warn "not an integer" unless /^[+-]?\d+$/ - warn "not a decimal number" unless /^[+-]?\d+\.?\d*$/ - warn "not a C float" + warn "not an integer" unless /^[+-]?\d+$/ + warn "not a decimal number" unless /^[+-]?\d+\.?\d*$/ + warn "not a C float" unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/; The length of an array is a scalar value. You may find the length of @@ -310,7 +310,7 @@ say then any bareword that would NOT be interpreted as a subroutine call produces a compile-time error instead. The restriction lasts to the -end of the enclosing block. An inner block may countermand this +end of the enclosing block. An inner block may countermand this by saying C<no strict 'subs'>. Array variables are interpolated into double-quoted strings by joining all @@ -346,7 +346,7 @@ identifier, which is valid, and matches the first empty line.) The terminating string must appear by itself (unquoted and with no surrounding whitespace) on the terminating line. - print <<EOF; + print <<EOF; The price is $Price. EOF @@ -369,11 +369,11 @@ surrounding whitespace) on the terminating line. Here's a line or two. THIS - and here another. + and here's another. THAT -Just don't forget that you have to put a semicolon on the end -to finish the statement, as Perl doesn't know you're not going to +Just don't forget that you have to put a semicolon on the end +to finish the statement, as Perl doesn't know you're not going to try to do this: print <<ABC @@ -401,12 +401,12 @@ assigns the entire list value to array foo, but assigns the value of variable bar to variable foo. Note that the value of an actual array in a scalar context is the length of the array; the -following assigns to $foo the value 3: +following assigns the value 3 to $foo: @foo = ('cc', '-E', $bar); $foo = @foo; # $foo gets 3 -You may have an optional comma before the closing parenthesis of an +You may have an optional comma before the closing parenthesis of a list literal, so that you can say: @foo = ( @@ -434,7 +434,7 @@ interpolating an array with no elements is the same as if no array had been interpolated at that point. A list value may also be subscripted like a normal array. You must -put the list in parentheses to avoid ambiguity. Examples: +put the list in parentheses to avoid ambiguity. For example: # Stat returns list value. $time = (stat($file))[8]; @@ -514,7 +514,7 @@ or for initializing hash references to be used as records: or for using call-by-named-parameter to complicated functions: - $field = $query->radio_group( + $field = $query->radio_group( name => 'group_name', values => ['eenie','meenie','minie'], default => 'meenie', @@ -530,7 +530,7 @@ of how to arrange for an output ordering. Perl uses an internal type called a I<typeglob> to hold an entire symbol table entry. The type prefix of a typeglob is a C<*>, because -it represents all types. This used to be the preferred way to +it represents all types. This used to be the preferred way to pass arrays and hashes by reference into a function, but now that we have real references, this is seldom needed. It also used to be the preferred way to pass filehandles into a function, but now diff --git a/pod/perldebug.pod b/pod/perldebug.pod index 61263b6664..25abfd6b3c 100644 --- a/pod/perldebug.pod +++ b/pod/perldebug.pod @@ -13,7 +13,7 @@ Perl source debugger. This works like an interactive Perl environment, prompting for debugger commands that let you examine 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 +the debugger all by itself just to test out Perl constructs interactively to see what they do. For example: perl -d -e 42 @@ -23,7 +23,7 @@ typical compiled environment. Instead, the B<-d> flag tells the compiler to insert source information into the parse trees it's about to hand off to the interpreter. That means your code must first compile correctly for the debugger to work on it. Then when the interpreter starts up, it -pre-loads a Perl library file containing the debugger itself. +preloads a Perl library file containing the debugger itself. The program will halt I<right before> the first run-time executable statement (but see below regarding compile-time statements) and ask you @@ -47,7 +47,7 @@ The debugger understands the following commands: =item h [command] -Prints out a help message. +Prints out a help message. If you supply another debugger command as an argument to the C<h> command, it prints out the description for just that command. The special @@ -73,7 +73,7 @@ where STDOUT may be redirected to. =item x expr -Evaluates its expression in list context and dumps out the result +Evaluates its expression in list context and dumps out the result in a pretty-printed fashion. Nested data structures are printed out recursively, unlike the C<print> function. @@ -308,7 +308,7 @@ Run Tk while prompting (with ReadLine). Level of verbosity. By default the debugger is in a sane verbose mode, thus it will print backtraces on all the warnings and die-messages which are going to be printed out, and will print a message when -interesting uncaught signals arrive. +interesting uncaught signals arrive. To disable this behaviour, set these values to 0. If C<dieLevel> is 2, then the messages which will be caught by surrounding C<eval> are also @@ -328,11 +328,11 @@ C<|visual_perl_db>), then a short, "emacs like" message is used. If 0, allows I<stepping off> the end of the script. -=item C<PrintRet> +=item C<PrintRet> affects printing of return value after C<r> command. -=item C<frame> +=item C<frame> affects printing messages on entry and exit from subroutines. If C<frame & 2> is false, messages are printed on entry only. (Printing @@ -383,7 +383,7 @@ can enable either double-quotish dump, or single-quotish by setting it to C<"> or C<'>. By default, characters with high bit set are printed I<as is>. -=item C<UsageOnly> +=item C<UsageOnly> I<very> rudimentally per-package memory usage dump. Calculates total size of strings in variables in the package. @@ -429,7 +429,7 @@ ReadLine applications. =item C<NonStop> -If set, debugger goes into non-interactive mode until interrupted, or +If set, debugger goes into noninteractive mode until interrupted, or programmatically by setting $DB::signal or $DB::single. =back @@ -449,7 +449,7 @@ Other examples may include $ PERLDB_OPTS="N f A L=listing" perl -d myprogram -- runs script non-interactively, printing info on each entry into a +- runs script noninteractively, printing info on each entry into a subroutine and each executed line into the file F<listing>. (If you interrupt it, you would better reset C<LineInfo> to something "interactive"!) @@ -468,37 +468,37 @@ See L<"Debugger Internals"> below for more details. =item E<lt> [ command ] Set an action (Perl command) to happen before every debugger prompt. -A multi-line command may be entered by backslashing the newlines. If +A multiline command may be entered by backslashing the newlines. If C<command> is missing, resets the list of actions. =item E<lt>E<lt> command Add an action (Perl command) to happen before every debugger prompt. -A multi-line command may be entered by backslashing the newlines. +A multiline command may be entered by backslashing the newlines. =item E<gt> command Set an action (Perl command) to happen after the prompt when you've -just given a command to return to executing the script. A multi-line +just given a command to return to executing the script. A multiline command may be entered by backslashing the newlines. If C<command> is missing, resets the list of actions. =item E<gt>E<gt> command Adds an action (Perl command) to happen after the prompt when you've -just given a command to return to executing the script. A multi-line +just given a command to return to executing the script. A multiline command may be entered by backslashing the newlines. =item { [ command ] Set an action (debugger command) to happen before every debugger prompt. -A multi-line command may be entered by backslashing the newlines. If +A multiline command may be entered by backslashing the newlines. If C<command> is missing, resets the list of actions. =item {{ command Add an action (debugger command) to happen before every debugger prompt. -A multi-line command may be entered by backslashing the newlines. +A multiline command may be entered by backslashing the newlines. =item ! number @@ -539,7 +539,7 @@ your history across this, but internal settings and command line options may be lost. Currently the following setting are preserved: history, breakpoints, -actions, debugger C<O>ptions, and the following command-line +actions, debugger C<O>ptions, and the following command line options: B<-w>, B<-I>, and B<-e>. =item |dbcmd @@ -593,16 +593,16 @@ or even DB<<17>> where that number is the command number, which you'd use to access with -the built-in B<csh>-like history mechanism, e.g., C<!17> would repeat +the builtin B<csh>-like history mechanism, e.g., C<!17> would repeat command number 17. The number of angle brackets indicates the depth of the debugger. You could get more than one set of brackets, for example, if you'd already at a breakpoint and then printed out the result of a function call that itself also has a breakpoint, or you step into an expression via C<s/n/t expression> command. -=item Multi-line commands +=item Multiline commands -If you want to enter a multi-line command, such as a subroutine +If you want to enter a multiline command, such as a subroutine definition with several statements, or a format, you may escape the newline that would normally end the debugger command with a backslash. Here's an example: @@ -667,7 +667,7 @@ next executed line is marked by C<==E<gt>>. When C<frame> option is set, debugger would print entered (and optionally exited) subroutines in different styles. -What follows is the start of the listing of +What follows is the start of the listing of env "PERLDB_OPTS=f=1 N" perl -d -V @@ -795,7 +795,7 @@ is printed with proper indentation. If you have any compile-time executable statements (code within a BEGIN block or a C<use> statement), these will C<NOT> be stopped by debugger, although C<require>s will (and compile-time statements can be traced -with C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl +with C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl code, however, you can transfer control back to the debugger using the following statement, which is harmless if the debugger is not running: @@ -859,7 +859,7 @@ the Term::ReadKey and Term::ReadLine modules from CPAN, you will have full editing capabilities much like GNU I<readline>(3) provides. Look for these in the F<modules/by-module/Term> directory on CPAN. -A rudimentary command-line completion is also available. +A rudimentary command line completion is also available. Unfortunately, the names of lexical variables are not available for completion. @@ -901,7 +901,7 @@ in that profile. When you call the B<caller> function (see L<perlfunc/caller>) from the package DB, Perl sets the array @DB::args to contain the arguments the -corresponding stack frame was called with. +corresponding stack frame was called with. If perl is run with B<-d> option, the following additional features are enabled: @@ -1007,9 +1007,9 @@ statement, and would wait for your C<CR> to continue. The following debugger is quite functional: - { - package DB; - sub DB {} + { + package DB; + sub DB {} sub sub {print ++$i, " $sub\n"; &$sub} } @@ -1020,7 +1020,7 @@ package C<DB>. =head2 Debugger Internals At the start, the debugger reads your rc file (F<./.perldb> or -F<~/.perldb> under UNIX), which can set important options. This file may +F<~/.perldb> under Unix), which can set important options. This file may define a subroutine C<&afterinit> to be executed after the debugger is initialized. @@ -1042,7 +1042,7 @@ C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about eval), C<args> (C<undef> or a reference to an array), C<file>, and C<line>. -The function C<DB::print_trace(FH, skip[, count[, short]])> prints +The function C<DB::print_trace(FH, skip[, count[, short]])> prints formatted info about caller frames. The last two functions may be convenient as arguments to C<E<lt>>, C<E<lt>E<lt>> commands. diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 46bd59b04f..ddd29c46d6 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -18,7 +18,7 @@ QNX, and AmigaOS. Most importantly, many bugs were fixed. See the F<Changes> file in the distribution for details. -=head2 Compilation Option: Binary Compatibility With 5.003 +=head2 Compilation option: Binary compatibility with 5.003 There is a new Configure question that asks if you want to maintain binary compatibility with Perl 5.003. If you choose binary @@ -27,6 +27,22 @@ 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 $PERL5OPT environment variable + +You may now put Perl options in the $PERL5OPT environment variable. +Unless Perl is running with taint checks, it will interpret this +variable as if its contents had appeared on a "#!perl" line at the +beginning of your script, except that hyphens are optional. PERL5OPT +may only be used to set the following switches: B<-[DIMUdmw]>. + +=head2 More precise warnings + +If you removed the -w option from your Perl 5.003 scripts because it +made Perl too verbose, we recommend that you try putting it back when +you upgrade to Perl 5.004. Each new perl version tends to remove some +undesirable warnings, while adding new warnings that may catch bugs in +your scripts. + =head2 Subroutine arguments created only when they're modified In Perl 5.004, nonexistent array and hash elements used as subroutine @@ -51,7 +67,20 @@ After this code executes in Perl 5.004, $a{b} exists but $a[2] does not. In Perl 5.002 and 5.003, both $a{b} and $a[2] would have existed (but $a[2]'s value would have been undefined). -=head2 Fixed Parsing of $$<digit>, &$<digit>, etc. +=head2 Simple functions' C<AUTOLOAD> not looked up as method + +Before Perl 5.004, C<AUTOLOAD> functions were looked up as methods +(using the C<@ISA> hierarchy), even when the function to be autoloaded +was called as a plain function (e.g. C<Foo::bar()>), not a method. +Perl 5.004 no longer uses method lookup for C<AUTOLOAD>s of plain +functions. + +The simple rule is: Inheritance does not work when autoloading plain +functions. The simple fix for old code is: In any module that used to +depend on inheriting C<AUTOLOAD> from a base class named C<BaseClass>, +execute C<*AUTOLOAD = *BaseClass::AUTOLOAD>. + +=head2 Fixed parsing of $$<digit>, &$<digit>, etc. A bug in previous versions of Perl 5.0 prevented proper parsing of numeric special variables as symbolic references. That bug has been @@ -59,14 +88,22 @@ 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 +=head2 No resetting of $. on implicit close The documentation for Perl 5.0 has always stated that C<$.> is I<not> -reset when an already-open file handle is re-opened with no intervening -call to C<close>. Due to a bug, perl versions 5.000 through 5.0003 +reset when an already-open file handle is reopened with no intervening +call to C<close>. Due to a bug, perl versions 5.000 through 5.003 I<did> reset C<$.> under that circumstance; Perl 5.004 does not. -=head2 Changes to Tainting Checks +=head2 C<wantarray> may return undef + +The C<wantarray> operator returns true if a subroutine is expected to +return a list, and false otherwise. In Perl 5.004, C<wantarray> can +also return the undefined value if a subroutine's return value will +not be used at all, which allows subroutines to avoid a time-consuming +calculation of a return value if it isn't going to be used. + +=head2 Changes to tainting checks A bug in previous versions may have failed to detect some insecure conditions when taint checks are turned on. (Taint checks are used @@ -76,14 +113,14 @@ previously-working script to now fail -- which should be construed as a blessing, since that indicates a potentially-serious security hole was just plugged. -=head2 New Opcode Module and Revised Safe Module +=head2 New Opcode module and revised Safe module A new Opcode module supports the creation, manipulation and 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 +=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 @@ -92,7 +129,7 @@ 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 +=head2 Internal change: FileHandle class based on IO::* classes File handles are now stored internally as type IO::Handle. The FileHandle module is still supported for backwards compatibility, but @@ -103,13 +140,13 @@ require, that you use the IO::* modules in new code. In harmony with this change, C<*GLOB{FILEHANDLE}> is now a backward-compatible synonym for C<*STDOUT{IO}>. -=head2 Internal Change: PerlIO internal IO abstraction interface +=head2 Internal change: PerlIO abstraction interface It is now possible to build Perl with AT&T's sfio IO package instead of stdio. See L<perlapio> for more details, and the F<INSTALL> file for how to use it. -=head2 New and Changed Built-in Variables +=head2 New and changed builtin variables =over @@ -142,7 +179,7 @@ there is no C<use English> long name for this variable. =back -=head2 New and Changed Built-in Functions +=head2 New and changed builtin functions =over @@ -225,7 +262,7 @@ number instead of a module name. If the version of the Perl interpreter is less than VERSION, then an error message is printed and Perl exits immediately. Because C<use> occurs at compile time, this check happens immediately during the compilation process, unlike C<require VERSION>, -which waits until run-time for the check. This is often useful if you +which waits until runtime for the check. This is often useful if you need to check the current Perl version before C<use>ing library modules which have changed in incompatible ways from older versions of Perl. (We try not to do this more than we have to.) @@ -283,7 +320,7 @@ zero-width assertion. See L<perlop> and L<perlre>. The C<m//x> construct has always been intended to ignore all unescaped whitespace. However, before Perl 5.004, whitespace had the effect of -esacping repeat modifier like "*" or "?". For example, C</a *b/x> was +escaping repeat modifiers like "*" or "?"; for example, C</a *b/x> was (mis)interpreted as C</a\*b/x>. This bug has been fixed in 5.004. =item nested C<sub{}> closures work now @@ -309,7 +346,7 @@ before, and is fine now: =back -=head2 New Built-in Methods +=head2 New builtin methods The C<UNIVERSAL> package automatically contains the following methods that are inherited by all other classes: @@ -359,7 +396,7 @@ You do not need to C<use UNIVERSAL> in order to make these methods available to your program. This is necessary only if you wish to have C<isa> available as a plain subroutine in the current package. -=head2 TIEHANDLE Now Supported +=head2 TIEHANDLE now supported See L<perltie> for other kinds of tie()s. @@ -428,7 +465,7 @@ possibly for cleaning up. =back -=head2 Malloc Enhancements +=head2 Malloc enhancements Four new compilation flags are recognized by malloc.c. (They have no effect if perl is compiled with system malloc().) @@ -487,7 +524,7 @@ negligible. =back -=head2 Miscellaneous Efficiency Enhancements +=head2 Miscellaneous efficiency enhancements Functions that have an empty prototype and that do nothing but return a fixed value are now inlined (e.g. C<sub PI () { 3.14159 }>). @@ -498,10 +535,16 @@ same hash, the hash keys never have to be reallocated. =head1 Pragmata -Four new pragmatic modules exist: +Six new pragmatic modules exist: =over +=item use autouse MODULE => qw(sub1 sub2 sub3) + +Defers C<require MODULE> until someone calls one of the specified +subroutines (which must be exported by MODULE). This pragma should be +used with caution, and only when necessary. + =item use blib =item use blib 'dir' @@ -513,10 +556,15 @@ parent directories. Intended for use on command line with B<-M> option as a way of testing arbitrary scripts against an uninstalled version of a package. +=item use constant NAME => VALUE + +Provides a convenient interface for creating compile-time constants, +See L<perlsub/"Constant Functions">. + =item use locale Tells the compiler to enable (or disable) the use of POSIX locales for -built-in operations. +builtin operations. When C<use locale> is in effect, the current LC_CTYPE locale is used for regular expressions and case mapping; LC_COLLATE for string @@ -548,7 +596,7 @@ relative to the local time zone, in the VMS tradition. =head1 Modules -=head2 Installation Directories +=head2 Installation directories The I<installperl> script now places the Perl source files for extensions in the architecture-specific library directory, which is @@ -558,31 +606,7 @@ library directory unchanged from a previous version, without running the risk of binary incompatibility between extensions' Perl source and shared libraries. -=head2 Fcntl - -New constants in the existing Fcntl modules are now supported, -provided that your operating system happens to support them: - - F_GETOWN F_SETOWN - O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC - O_EXLOCK O_SHLOCK - -These constants are intended for use with the Perl operators sysopen() -and fcntl() and the basic database modules like SDBM_File. For the -exact meaning of these and other Fcntl constants please refer to your -operating system's documentation for fcntl() and open(). - -In addition, the Fcntl module now provides these constants for use -with the Perl operator flock(): - - LOCK_SH LOCK_EX LOCK_NB LOCK_UN - -These constants are defined in all environments (because where there is -no flock() system call, Perl emulates it). However, for historical -reasons, these constants are not exported unless they are explicitly -requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>). - -=head2 Module Information Summary +=head2 Module information summary Brand new modules, arranged by topic rather than strictly alphabetically: @@ -622,6 +646,30 @@ alphabetically: UNIVERSAL.pm Base class for *ALL* classes +=head2 Fcntl + +New constants in the existing Fcntl modules are now supported, +provided that your operating system happens to support them: + + F_GETOWN F_SETOWN + O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC + O_EXLOCK O_SHLOCK + +These constants are intended for use with the Perl operators sysopen() +and fcntl() and the basic database modules like SDBM_File. For the +exact meaning of these and other Fcntl constants please refer to your +operating system's documentation for fcntl() and open(). + +In addition, the Fcntl module now provides these constants for use +with the Perl operator flock(): + + LOCK_SH LOCK_EX LOCK_NB LOCK_UN + +These constants are defined in all environments (because where there is +no flock() system call, Perl emulates it). However, for historical +reasons, these constants are not exported unless they are explicitly +requested with the ":flock" tag (e.g. C<use Fcntl ':flock'>). + =head2 IO The IO module provides a simple mechanism to load all of the IO modules at one @@ -697,9 +745,9 @@ changes. Everything after DB_File 1.01 has been added since 5.003. Major rewrite - support added for both udp echo and real icmp pings. -=head2 Overridden Built-ins +=head2 Object-oriented overrides for builtin operators -Many of the Perl built-ins returning lists now have +Many of the Perl builtins returning lists now have object-oriented overrides. These are: File::stat @@ -768,7 +816,7 @@ on the first call). Internal handling of hash keys has changed. The old hashtable API is still fully supported, and will likely remain so. The additions to the API allow passing keys as C<SV*>s, so that C<tied> hashes can be given -real scalars as keys rather than plain strings (non-tied hashes still +real scalars as keys rather than plain strings (nontied hashes still can only use strings as keys). New extensions must use the new hash access functions and macros if they wish to use C<SV*> keys. These additions also make it feasible to manipulate C<HE*>s (hash entries), @@ -822,7 +870,7 @@ increasing order of desperation): (S) A severe warning (mandatory). (F) A fatal error (trappable). (P) An internal error you should never see (trappable). - (X) A very fatal error (non-trappable). + (X) A very fatal error (nontrappable). (A) An alien error message (not generated by Perl). =over @@ -849,13 +897,22 @@ or a hash slice, such as =item Allocation too large: %lx -(X) You can't allocate more than 64K on an MSDOS machine. +(X) You can't allocate more than 64K on an MS-DOS machine. =item Allocation too large (F) You can't allocate more than 2^31+"small amount" bytes. -=item Attempt to free non-existent shared string +=item Applying %s to %s will act on scalar(%s) + +(W) The pattern match (//), substitution (s///), and translation (tr///) +operators work on scalar values. If you apply one of them to an array +or a hash, it will convert the array or hash to a scalar value -- the +length of an array, or the population info of a hash -- and then work on +that scalar value. This is probably not what you meant to do. See +L<perlfunc/grep> and L<perlfunc/map> for alternatives. + +=item Attempt to free nonexistent shared string (P) Perl maintains a reference counted internal table of strings to optimize the storage and access of hash keys and other strings. This @@ -868,39 +925,54 @@ that can no longer be found in the table. as an lvalue, which is pretty strange. Perhaps you forgot to dereference it first. See L<perlfunc/substr>. -=item Unsupported function fork - -(F) Your version of executable does not support forking. - -Note that under some systems, like OS/2, there may be different flavors of -Perl executables, some of which may support fork, some not. Try changing -the name you call Perl by to C<perl_>, C<perl__>, and so on. - -=item Ill-formed logical name |%s| in prime_env_iter - -(W) A warning peculiar to VMS. A logical name was encountered when preparing -to iterate over %ENV which violates the syntactic rules governing logical -names. Since it cannot be translated normally, it is skipped, and will not -appear in %ENV. This may be a benign occurrence, as some software packages -might directly modify logical name tables and introduce non-standard names, -or it may indicate that a logical name table has been corrupted. - =item Can't use bareword ("%s") as %s ref while "strict refs" in use (F) Only hard references are allowed by "strict refs". Symbolic references are disallowed. See L<perlref>. +=item Cannot resolve method `%s' overloading `%s' in package `%s' + +(P) Internal error trying to resolve overloading specified by a method +name (as opposed to a subroutine reference). + =item Constant subroutine %s redefined (S) You redefined a subroutine which had previously been eligible for +inlining. See L<perlsub/"Constant Functions"for commentary and +workarounds. + +=item Constant subroutine %s undefined + +(S) You undefined a subroutine which had previously been eligible for inlining. See L<perlsub/"Constant Functions"> for commentary and workarounds. +=item Copy method did not return a reference + +(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>. + =item Died (F) You passed die() an empty string (the equivalent of C<die "">) or you called it with no args and both C<$@> and C<$_> were empty. +=item Exiting pseudo-block via %s + +(W) You are exiting a rather special block construct (like a sort block or +subroutine) by unconventional means, such as a goto, or a loop control +statement. See L<perlfunc/sort>. + +=item Illegal character %s (carriage return) + +(F) A carriage return character was found in the input. This is an +error, and not a warning, because carriage return characters can break +multi-line strings, including here documents (e.g., C<print E<lt>E<lt>EOF;>). + +=item Illegal switch in PERL5OPT: %s + +(X) The PERL5OPT environment variable may only be used to set the +following switches: B<-[DIMUdmw]>. + =item Integer overflow in hex number (S) The literal hex number you have specified is too big for your @@ -933,17 +1005,6 @@ pointing outside the buffer. This is difficult to imagine. The sole exception to this is that C<sysread()>ing past the buffer will extend the buffer and zero pad the new area. -=item Stub found while resolving method `%s' overloading `%s' in package `%s' - -(P) Overloading resolution over @ISA tree may be broken by importing stubs. -Stubs should never be implicitely created, but explicit calls to C<can> -may break this. - -=item Cannot resolve method `%s' overloading `%s' in package `s' - -(P) Internal error trying to resolve overloading specified by a method -name (as opposed to a subroutine reference). - =item Out of memory! (X|F) The malloc() function returned 0, indicating there was insufficient @@ -1017,18 +1078,46 @@ assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves like a list when you assign to it, and provides a list context to its subscript, which can do weird things if you're expecting only one subscript. +=item Stub found while resolving method `%s' overloading `%s' in package `%s' + +(P) Overloading resolution over @ISA tree may be broken by importing stubs. +Stubs should never be implicitely created, but explicit calls to C<can> +may break this. + +=item Too late for "B<-T>" option + +(X) The #! line (or local equivalent) in a Perl script contains the +B<-T> option, but Perl was not invoked with B<-T> in its argument +list. This is an error because, by the time Perl discovers a B<-T> in +a script, it's too late to properly taint everything from the +environment. So Perl gives up. + =item untie attempted while %d inner references still exist (W) A copy of the object returned from C<tie> (or C<tied>) was still valid when C<untie> was called. -=item Value of %s construct can be "0"; test with defined() +=item Unrecognized character %s + +(F) The Perl parser has no idea what to do with the specified character +in your Perl script (or eval). Perhaps you tried to run a compressed +script, a binary program, or a directory as a Perl program. + +=item Unsupported function fork + +(F) Your version of executable does not support forking. + +Note that under some systems, like OS/2, there may be different flavors of +Perl executables, some of which may support fork, some not. Try changing +the name you call Perl by to C<perl_>, C<perl__>, and so on. + +=item Value of %s can be "0"; test with defined() -(W) In a conditional expression, you used <HANDLE>, <*> (glob), or -C<readdir> as a boolean value. Each of these constructs can return a -value of "0"; that would make the conditional expression false, which -is probably not what you intended. When using these constructs in -conditional expressions, test their values with the C<defined> operator. +(W) In a conditional expression, you used <HANDLE>, <*> (glob), C<each()>, +or C<readdir()> as a boolean value. Each of these constructs can return a +value of "0"; that would make the conditional expression false, which is +probably not what you intended. When using these constructs in conditional +expressions, test their values with the C<defined> operator. =item Variable "%s" may be unavailable @@ -1071,7 +1160,7 @@ will I<never> share the given variable. This problem can usually be solved by making the inner subroutine anonymous, using the C<sub {}> syntax. When inner anonymous subs that reference variables in outer subroutines are called or referenced, -they are automatically re-bound to the current values of such +they are automatically rebound to the current values of such variables. =item Warning: something's wrong @@ -1079,6 +1168,15 @@ variables. (W) You passed warn() an empty string (the equivalent of C<warn "">) or you called it with no args and C<$_> was empty. +=item Ill-formed logical name |%s| in prime_env_iter + +(W) A warning peculiar to VMS. A logical name was encountered when preparing +to iterate over %ENV which violates the syntactic rules governing logical +names. Since it cannot be translated normally, it is skipped, and will not +appear in %ENV. This may be a benign occurrence, as some software packages +might directly modify logical name tables and introduce nonstandard names, +or it may indicate that a logical name table has been corrupted. + =item Got an error from DosAllocMem (P) An error peculiar to OS/2. Most probably you're using an obsolete @@ -1094,7 +1192,7 @@ or prefix1 prefix2 -with non-empty prefix1 and prefix2. If C<prefix1> is indeed a prefix of +with nonempty prefix1 and prefix2. If C<prefix1> is indeed a prefix of a builtin library search path, prefix2 is substituted. The error may appear if components are not found, or are too long. See L<perlos2/"PERLLIB_PREFIX">. diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 90b811f691..a138bc6645 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -12,7 +12,7 @@ desperation): (S) A severe warning (mandatory). (F) A fatal error (trappable). (P) An internal error you should never see (trappable). - (X) A very fatal error (non-trappable). + (X) A very fatal error (nontrappable). (A) An alien error message (not generated by Perl). Optional warnings are enabled by using the B<-w> switch. Warnings may @@ -174,7 +174,7 @@ the return value of your socket() call? See L<perlfunc/accept>. =item Allocation too large: %lx -(X) You can't allocate more than 64K on an MSDOS machine. +(X) You can't allocate more than 64K on an MS-DOS machine. =item Allocation too large @@ -237,7 +237,7 @@ know which context to supply to the right side. be garbage collected on exit. An SV was discovered to be outside any of those arenas. -=item Attempt to free non-existent shared string +=item Attempt to free nonexistent shared string (P) Perl maintains a reference counted internal table of strings to optimize the storage and access of hash keys and other strings. This @@ -338,7 +338,7 @@ Perl yourself. (F) With "strict subs" in use, a bareword is only allowed as a subroutine identifier, in curly braces or to the left of the "=>" symbol. -Perhaps you need to pre-declare a subroutine? +Perhaps you need to predeclare a subroutine? =item BEGIN failed--compilation aborted @@ -389,7 +389,7 @@ will be considered a block that loops once. See L<perlfunc/last>. there isn't a current block. Note that an "if" or "else" block doesn't count as a "loopish" block, as doesn't a block given to sort(). You can usually double the curlies to get the same effect though, because the inner -curlies will be considered a block that loops once. See L<perlfunc/last>. +curlies will be considered a block that loops once. See L<perlfunc/next>. =item Can't "redo" outside a block @@ -397,7 +397,7 @@ curlies will be considered a block that loops once. See L<perlfunc/last>. there isn't a current block. Note that an "if" or "else" block doesn't count as a "loopish" block, as doesn't a block given to sort(). You can usually double the curlies to get the same effect though, because the inner -curlies will be considered a block that loops once. See L<perlfunc/last>. +curlies will be considered a block that loops once. See L<perlfunc/redo>. =item Can't bless non-reference value @@ -406,7 +406,7 @@ encapsulation of objects. See L<perlobj>. =item Can't break at that line -(S) A warning intended for while running within the debugger, indicating +(S) A warning intended to only be printed while running within the debugger, indicating the line number specified wasn't the location of a statement that could be stopped at. @@ -418,7 +418,7 @@ in it, let alone methods. See L<perlobj>. =item Can't call method "%s" on unblessed reference -(F) A method call must know what package it's supposed to run in. It +(F) A method call must know in what package it's supposed to run. It ordinarily finds this out from the object reference you supply, but you didn't supply an object reference in this case. A reference isn't an object reference until it has been blessed. See L<perlobj>. @@ -478,9 +478,9 @@ They must have ordinary identifiers as names. (S) The creation of the new file failed for the indicated reason. -=item Can't do in-place edit without backup +=item Can't do inplace edit without backup -(F) You're on a system such as MSDOS that gets confused if you try reading +(F) You're on a system such as MS-DOS that gets confused if you try reading from a deleted (but still opened) file. You have to say C<-i.bak>, or some such. @@ -563,14 +563,6 @@ levels, the following is missing its final parenthesis: (F) A fatal error occurred while trying to fork while opening a pipeline. -=item Unsupported function fork - -(F) Your version of executable does not support forking. - -Note that under some systems, like OS/2, there may be different flavors of -Perl executables, some of which may support fork, some not. Try changing -the name you call Perl by to C<perl_>, C<perl__>, and so on. - =item Can't get filespec - stale stat buffer? (S) A warning peculiar to VMS. This arises because of the difference between @@ -621,10 +613,10 @@ package name. =item Can't locate %s in @INC -(F) You said to do (or require, or use) a file that couldn't be found -in any of the libraries mentioned in @INC. Perhaps you need to set -the PERL5LIB environment variable to say where the extra library is, -or maybe the script needs to add the library name to @INC. Or maybe +(F) You said to do (or require, or use) a file that couldn't be found in +in any of the libraries mentioned in @INC. Perhaps you need to set the +PERL5LIB or PERL5OPT environment variable to say where the extra library +is, or maybe the script needs to add the library name to @INC. Or maybe you just misspelled the name of the file. See L<perlfunc/require>. =item Can't locate object method "%s" via package "%s" @@ -648,7 +640,7 @@ a B<-e> switch. Maybe your /tmp partition is full, or clobbered. (F) You aren't allowed to assign to the item indicated, or otherwise try to change it, such as with an auto-increment. -=item Can't modify non-existent substring +=item Can't modify nonexistent substring (P) The internal routine that does assignment to a substr() was handed a NULL. @@ -660,7 +652,7 @@ buffer. =item Can't open %s: %s -(S) An in-place edit couldn't open the original file for the indicated reason. +(S) An inplace 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 @@ -799,7 +791,7 @@ are disallowed. See L<perlref>. =item Can't use an undefined value as %s reference (F) A value used as either a hard reference or a symbolic reference must -be a defined value. This helps to de-lurk some insidious errors. +be a defined value. This helps to delurk some insidious errors. =item Can't use global %s in "my" @@ -906,7 +898,7 @@ On the other hand, maybe you just meant %hash and got carried away. (F) You passed die() an empty string (the equivalent of C<die "">) or you called it with no args and both C<$@> and C<$_> were empty. -=item Do you need to pre-declare %s? +=item Do you need to predeclare %s? (S) This is an educated guess made in conjunction with the message "%s found where operator expected". It often means a subroutine or module @@ -1106,18 +1098,18 @@ is now heavily deprecated. to iterate over %ENV which violates the syntactic rules governing logical names. Because it cannot be translated normally, it is skipped, and will not appear in %ENV. This may be a benign occurrence, as some software packages -might directly modify logical name tables and introduce non-standard names, +might directly modify logical name tables and introduce nonstandard names, or it may indicate that a logical name table has been corrupted. =item Illegal character %s (carriage return) (F) A carriage return character was found in the input. This is an error, and not a warning, because carriage return characters can break -here documents (e.g., C<print E<lt>E<lt>EOF;>). - -Under UNIX, this error is usually caused by executing Perl code -- +multi-line strings, including here documents (e.g., C<print E<lt>E<lt>EOF;>). + +Under Unix, this error is usually caused by executing Perl code -- either the main program, a module, or an eval'd string -- that was -transferred over a network connection from a non-UNIX system without +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 @@ -1147,6 +1139,11 @@ don't take to this kindly. (W) You may have tried to use an 8 or 9 in a octal number. Interpretation of the octal number stopped before the 8 or 9. +=item Illegal switch in PERL5OPT: %s + +(X) The PERL5OPT environment variable may only be used to set the +following switches: B<-[DIMUdmw]>. + =item In string, @%s now must be written as \@%s (F) It used to be that Perl would try to guess whether you wanted an @@ -1301,13 +1298,13 @@ catches that. But an easy way to do the same thing is: Another way is to assign to a substr() that's off the end of the string. -=item Modification of non-creatable array value attempted, subscript %d +=item Modification of noncreatable array value attempted, subscript %d (F) You tried to make an array value spring into existence, and the subscript was probably negative, even counting from end of the array backwards. -=item Modification of non-creatable hash value attempted, subscript "%s" +=item Modification of noncreatable hash value attempted, subscript "%s" (F) You tried to make a hash value spring into existence, and it couldn't be created for some peculiar reason. @@ -1382,7 +1379,7 @@ this error was triggered? =item No command into which to pipe on command line (F) An error peculiar to VMS. Perl handles its own command line redirection, -and found a '|' at the end of the command line, so it doesn't know whither you +and found a '|' at the end of the command line, so it doesn't know where you want to pipe the output from this command. =item No DB::DB routine defined @@ -1422,7 +1419,7 @@ from which to read data for stdin. (F) An error peculiar to VMS. Perl handles its own command line redirection, and found a lone 'E<gt>' at the end of the command line, so it doesn't know -whither you wanted to redirect stdout. +where you wanted to redirect stdout. =item No output file after E<gt> or E<gt>E<gt> on command line @@ -1596,7 +1593,7 @@ but realloc() wouldn't give it more memory, virtual or otherwise. =item Out of memory! (X|F) The malloc() function returned 0, indicating there was insufficient -remaining memory (or virtual memory) to satisfy the request. +remaining memory (or virtual memory) to satisfy the request. The request was judged to be small, so the possibility to trap it depends on the way perl was compiled. By default it is not trappable. @@ -1799,7 +1796,7 @@ used.) You probably wrote something like this: - @list = qw( + @list = qw( a # a comment b # another comment ); @@ -1807,8 +1804,8 @@ You probably wrote something like this: when you should have written this: @list = qw( - a - b + a + b ); If you really want comments, build your list the @@ -1826,7 +1823,7 @@ aren't needed to separate the items. (You may have used different delimiters than the parentheses shown here; braces are also frequently used.) -You probably wrote something like this: +You probably wrote something like this: qw! a, b, c !; @@ -1869,7 +1866,7 @@ Check your logic flow. =item Probable precedence problem on %s -(W) The compiler found a bare word where it expected a conditional, +(W) The compiler found a bareword where it expected a conditional, which often indicates that an || or && was parsed as part of the last argument of the previous construct, for example: @@ -1887,7 +1884,7 @@ Check your logic flow. =item Reallocation too large: %lx -(F) You can't allocate more than 64K on an MSDOS machine. +(F) You can't allocate more than 64K on an MS-DOS machine. =item Recompile perl with B<-D>DEBUGGING to use B<-D> switch @@ -1965,8 +1962,8 @@ L<perlref>. =item Script is not setuid/setgid in suidperl -(F) Oddly, the suidperl program was invoked on a script with its setuid -or setgid bit not set. This doesn't make much sense. +(F) Oddly, the suidperl program was invoked on a script without a setuid +or setgid bit set. This doesn't make much sense. =item Search pattern not terminated @@ -1976,7 +1973,7 @@ construct. Remember that bracketing delimiters count nesting level. =item seek() on unopened file (W) You tried to use the seek() function on a filehandle that was either -never opened or has been closed since. +never opened or has since been closed. =item select not implemented @@ -2102,7 +2099,7 @@ See L<perlfunc/split>. =item Stat on unopened file E<lt>%sE<gt> (W) You tried to use the stat() function (or an equivalent file test) -on a filehandle that was either never opened or has been closed since. +on a filehandle that was either never opened or has since been closed. =item Statement unlikely to be reached @@ -2195,7 +2192,7 @@ Check your logic flow. =item tell() on unopened file (W) You tried to use the tell() function on a filehandle that was either -never opened or has been closed since. +never opened or has since been closed. =item Test on unopened file E<lt>%sE<gt> @@ -2394,14 +2391,15 @@ See L<perlre>. =item Unquoted string "%s" may clash with future reserved word -(W) You used a bare word that might someday be claimed as a reserved word. +(W) You used a bareword that might someday be claimed as a reserved word. It's best to put such a word in quotes, or capitalize it somehow, or insert an underbar into it. You might also declare it as a subroutine. -=item Unrecognized character \%03o ignored +=item Unrecognized character %s -(S) A garbage character was found in the input, and ignored, in case it's -a weird control character on an EBCDIC machine, or some such. +(F) The Perl parser has no idea what to do with the specified character +in your Perl script (or eval). Perhaps you tried to run a compressed +script, a binary program, or a directory as a Perl program. =item Unrecognized signal name "%s" @@ -2418,12 +2416,20 @@ supplying the bad switch on your behalf.) (W) A file operation was attempted on a filename, and that operation failed, PROBABLY because the filename contained a newline, PROBABLY -because you forgot to chop() or chomp() it off. See L<perlfunc/chop>. +because you forgot to chop() or chomp() it off. See L<perlfunc/chomp>. =item Unsupported directory function "%s" called (F) Your machine doesn't support opendir() and readdir(). +=item Unsupported function fork + +(F) Your version of executable does not support forking. + +Note that under some systems, like OS/2, there may be different flavors of +Perl executables, some of which may support fork, some not. Try changing +the name you call Perl by to C<perl_>, C<perl__>, and so on. + =item Unsupported function %s (F) This machines doesn't implement the indicated function, apparently. @@ -2448,7 +2454,7 @@ Use an explicit printf() or sprintf() instead. =item Use of $* is deprecated -(D) This variable magically turned on multi-line pattern matching, both for +(D) This variable magically turned on multiline pattern matching, both for you and for any luckless subroutine that you happen to call. You should use the new C<//m> and C<//s> modifiers now to do that without the dangerous action-at-a-distance effects of C<$*>. @@ -2574,7 +2580,7 @@ will I<never> share the given variable. This problem can usually be solved by making the inner subroutine anonymous, using the C<sub {}> syntax. When inner anonymous subs that reference variables in outer subroutines are called or referenced, -they are automatically re-bound to the current values of such +they are automatically rebound to the current values of such variables. =item Variable syntax @@ -2705,13 +2711,13 @@ or prefix1 prefix2 -with non-empty prefix1 and prefix2. If C<prefix1> is indeed a prefix of +with nonempty prefix1 and prefix2. If C<prefix1> is indeed a prefix of a builtin library search path, prefix2 is substituted. The error may appear if components are not found, or are too long. See L<perlos2/"PERLLIB_PREFIX">. =item PERL_SH_DIR too long -(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the +(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the C<sh>-shell in. See L<perlos2/"PERL_SH_DIR">. =item Process terminated by SIG%s diff --git a/pod/perldsc.pod b/pod/perldsc.pod index 61c45b970c..e2b82df796 100644 --- a/pod/perldsc.pod +++ b/pod/perldsc.pod @@ -134,7 +134,7 @@ might do well to consider being a tad more explicit about it, like this: for $i (1..10) { @list = somefunc($i); - $counts[$i] = scalar @list; + $counts[$i] = scalar @list; } Here's the case of taking a reference to the same memory location @@ -328,7 +328,7 @@ There's also a lowercase B<x> command which is nearly the same. =head1 CODE EXAMPLES -Presented with little comment (these will get their own man pages someday) +Presented with little comment (these will get their own manpages someday) here are short code examples illustrating access of various types of data structures. @@ -457,7 +457,7 @@ types of data structures. } # print the whole thing sorted by number of members and name - foreach $family ( sort { + foreach $family ( sort { @{$HoL{$b}} <=> @{$HoL{$a}} || $a cmp $b diff --git a/pod/perlembed.pod b/pod/perlembed.pod index 7752156026..9111be1253 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -14,7 +14,7 @@ Do you want to: Read L<perlcall> and L<perlxs>. -=item B<Use a UNIX program from Perl?> +=item B<Use a Unix program from Perl?> Read about back-quotes and about C<system> and C<exec> in L<perlfunc>. @@ -96,29 +96,29 @@ Execute this statement for a hint about where to find CORE: perl -MConfig -e 'print $Config{archlib}' -Here's how you'd compile the example in the next section, +Here's how you'd compile the example in the next section, L<Adding a Perl interpreter to your C program>, on my Linux box: - % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include + % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include -I/usr/local/lib/perl5/i586-linux/5.003/CORE - -L/usr/local/lib/perl5/i586-linux/5.003/CORE + -L/usr/local/lib/perl5/i586-linux/5.003/CORE -o interp interp.c -lperl -lm -(That's all one line.) On my DEC Alpha running 5.00305, the incantation +(That's all one line.) On my DEC Alpha running 5.003_05, the incantation is a bit different: - % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include - -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE - -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib + % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include + -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE + -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm How can you figure out what to add? Assuming your Perl is post-5.001, execute a C<perl -V> command and pay special attention to the "cc" and -"ccflags" information. +"ccflags" information. -You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for +You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for your machine: C<perl -MConfig -e 'print $Config{cc}'> will tell you what -to use. +to use. You'll also have to choose the appropriate library directory (I</usr/local/lib/...>) for your machine. If your compiler complains @@ -132,7 +132,7 @@ Perhaps those printed by perl -MConfig -e 'print $Config{libs}' -Provided your perl binary was properly configured and installed the +Provided your perl binary was properly configured and installed the B<ExtUtils::Embed> module will determine all of this information for you: @@ -145,14 +145,14 @@ this documentation came from your Perl distribution, then you're running 5.004 or better and you already have it.) The B<ExtUtils::Embed> kit on CPAN also contains all source code for -the examples in this document, tests, additional examples and other +the examples in this document, tests, additional examples and other information you may find useful. =head2 Adding a Perl interpreter to your C program In a sense, perl (the C program) is a good example of embedding Perl (the language), so I'll demonstrate embedding with I<miniperlmain.c>, -from the source distribution. Here's a bastardized, non-portable +from the source distribution. Here's a bastardized, nonportable version of I<miniperlmain.c> containing the essentials of embedding: #include <EXTERN.h> /* from the Perl distribution */ @@ -200,7 +200,7 @@ calling I<perl_run()>. =head2 Calling a Perl subroutine from your C program To call individual Perl subroutines, you can use any of the B<perl_call_*> -functions documented in the L<perlcall> man page. +functions documented in the L<perlcall> manpage. In this example we'll use I<perl_call_argv>. That's shown below, in a program I'll call I<showtime.c>. @@ -493,7 +493,7 @@ which produces the output (again, long lines have been wrapped here) match: with substitute: s/[aeiou]//gi...139 substitutions made. - Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts, + Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts, Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs @@ -519,7 +519,7 @@ described in L<perlcall>. Once you've understood those, embedding Perl in C is easy. -Because C has no built-in function for integer exponentiation, let's +Because C has no builtin function for integer exponentiation, let's make Perl's ** operator available to it (this is less useful than it sounds, because Perl implements ** with C's I<pow()> function). First I'll create a stub exponentiation function in I<power.pl>: @@ -592,7 +592,7 @@ When developing interactive and/or potentially long-running applications, it's a good idea to maintain a persistent interpreter rather than allocating and constructing a new interpreter multiple times. The major reason is speed: since Perl will only be loaded into -memory once. +memory once. However, you have to be more cautious with namespace and variable scoping when using a persistent interpreter. In previous examples @@ -627,47 +627,47 @@ itself after a certain number of requests, to ensure that memory consumption is minimized. You'll also want to scope your variables with L<perlfunc/my> whenever possible. - + package Embed::Persistent; #persistent.pl - + use strict; use vars '%Cache'; - + sub valid_package_name { my($string) = @_; $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg; # second pass only for words starting with a digit $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg; - + # Dress it up as a real package name $string =~ s|/|::|g; return "Embed" . $string; } - + #borrowed from Safe.pm sub delete_package { my $pkg = shift; my ($stem, $leaf); - + no strict 'refs'; $pkg = "main::$pkg\::"; # expand to full symbol table name ($stem, $leaf) = $pkg =~ m/(.*::)(\w+::)$/; - + my $stem_symtab = *{$stem}{HASH}; - + delete $stem_symtab->{$leaf}; } - + sub eval_file { my($filename, $delete) = @_; my $package = valid_package_name($filename); my $mtime = -M $filename; if(defined $Cache{$package}{mtime} && - $Cache{$package}{mtime} <= $mtime) + $Cache{$package}{mtime} <= $mtime) { - # we have compiled this subroutine already, + # we have compiled this subroutine already, # it has not been updated on disk, nothing left to do print STDERR "already compiled $package->handler\n"; } @@ -677,7 +677,7 @@ with L<perlfunc/my> whenever possible. local($/) = undef; my $sub = <FH>; close FH; - + #wrap the code into a subroutine inside our unique package my $eval = qq{package $package; sub handler { $sub; }}; { @@ -686,35 +686,35 @@ with L<perlfunc/my> whenever possible. eval $eval; } die $@ if $@; - + #cache it unless we're cleaning out each time $Cache{$package}{mtime} = $mtime unless $delete; } - + eval {$package->handler;}; die $@ if $@; - + delete_package($package) if $delete; - + #take a look if you want #print Devel::Symdump->rnew($package)->as_string, $/; } - + 1; - + __END__ /* persistent.c */ - #include <EXTERN.h> - #include <perl.h> - + #include <EXTERN.h> + #include <perl.h> + /* 1 = clean out filename's symbol table after each request, 0 = don't */ #ifndef DO_CLEAN #define DO_CLEAN 0 #endif - + static PerlInterpreter *perl = NULL; - + int main(int argc, char **argv, char **env) { @@ -722,41 +722,40 @@ with L<perlfunc/my> whenever possible. char *args[] = { "", DO_CLEAN, NULL }; char filename [1024]; int exitstatus = 0; - + if((perl = perl_alloc()) == NULL) { fprintf(stderr, "no memory!"); exit(1); } - perl_construct(perl); - + perl_construct(perl); + exitstatus = perl_parse(perl, NULL, 2, embedding, NULL); - - if(!exitstatus) { + + if(!exitstatus) { exitstatus = perl_run(perl); - + while(printf("Enter file name: ") && gets(filename)) { - + /* call the subroutine, passing it the filename as an argument */ args[0] = filename; - perl_call_argv("Embed::Persistent::eval_file", + perl_call_argv("Embed::Persistent::eval_file", G_DISCARD | G_EVAL, args); - + /* check $@ */ - if(SvTRUE(GvSV(errgv))) + if(SvTRUE(GvSV(errgv))) fprintf(stderr, "eval error: %s\n", SvPV(GvSV(errgv),na)); } } - + perl_destruct_level = 0; - perl_destruct(perl); - perl_free(perl); + perl_destruct(perl); + perl_free(perl); exit(exitstatus); } - Now compile: - % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts` + % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts` Here's a example script file: @@ -782,7 +781,7 @@ Now run: Some rare applications will need to create more than one interpreter during a session. Such an application might sporadically decide to -release any resources associated with the interpreter. +release any resources associated with the interpreter. The program must take care to ensure that this takes place I<before> the next interpreter is constructed. By default, the global variable @@ -791,22 +790,22 @@ needed when a program has only one interpreter. Setting C<perl_destruct_level> to C<1> makes everything squeaky clean: - perl_destruct_level = 1; + perl_destruct_level = 1; while(1) { ... /* reset global variables here with perl_destruct_level = 1 */ - perl_construct(my_perl); + perl_construct(my_perl); ... /* clean and reset _everything_ during perl_destruct */ - perl_destruct(my_perl); - perl_free(my_perl); + perl_destruct(my_perl); + perl_free(my_perl); ... /* let's go do it again! */ } -When I<perl_destruct()> is called, the interpreter's syntax parse tree -and symbol tables are cleaned up, and global variables are reset. +When I<perl_destruct()> is called, the interpreter's syntax parse tree +and symbol tables are cleaned up, and global variables are reset. Now suppose we have more than one interpreter instance running at the same time. This is feasible, but only if you used the @@ -826,9 +825,9 @@ Let's give it a try: int main(int argc, char **argv, char **env) { - PerlInterpreter + PerlInterpreter *one_perl = perl_alloc(), - *two_perl = perl_alloc(); + *two_perl = perl_alloc(); char *one_args[] = { "one_perl", SAY_HELLO }; char *two_args[] = { "two_perl", SAY_HELLO }; diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod index 8cbb343e7b..99aeae953d 100644 --- a/pod/perlfaq.pod +++ b/pod/perlfaq.pod @@ -91,7 +91,7 @@ Perl Porters. Copyright (c) 1997 Tom Christiansen and Nathan Torkington. All rights reserved. -=head2 Non-commercial Reproduction +=head2 Noncommercial 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 diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod index ad7c68a124..5d45c819c5 100644 --- a/pod/perlfaq1.pod +++ b/pod/perlfaq1.pod @@ -168,7 +168,7 @@ 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 +statically typed one. You certainly won't be chastised 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. :-) @@ -193,7 +193,7 @@ programs, however, are usually neither strictly compiled nor strictly interpreted. They can be compiled to a bytecode form (something of a Perl virtual machine) or to completely different languages, like C or assembly language. You can't tell just by looking whether the source is destined -for a pure interpreter, a parse-tree interpreter, a byte-code interpreter, +for a pure interpreter, a parse-tree interpreter, a byte code interpreter, or a native-code compiler, so it's hard to give a definitive answer here. =head2 What is a JAPH? diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod index 7fa34d9c27..95d542d566 100644 --- a/pod/perlfaq2.pod +++ b/pod/perlfaq2.pod @@ -62,7 +62,7 @@ eventually live on, and then type C<make install>. Most other approaches are doomed to failure. One simple way to check that things are in the right place is to print out -the hard-coded @INC which perl is looking for. +the hardcoded @INC which perl is looking for. perl -e 'print join("\n",@INC)' @@ -76,7 +76,7 @@ module/library directory?">. =head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? Read the F<INSTALL> file, which is part of the source distribution. -It describes in detail how to cope with most idiosyncracies that the +It describes in detail how to cope with most idiosyncrasies that the Configure script can't work around for any given system or architecture. @@ -84,7 +84,7 @@ architecture. CPAN stands for Comprehensive Perl Archive Network, a huge archive replicated on dozens of machines all over the world. CPAN contains -source code, non-native ports, documentation, scripts, and many +source code, nonnative ports, documentation, scripts, and many third-party modules and extensions, designed for everything from commercial database interfaces to keyboard/screen control to web walking and CGI scripts. The master machine for CPAN is @@ -191,7 +191,7 @@ before you buy! What follows is a list of the books that the FAQ authors found personally useful. Your mileage may (but, we hope, probably won't) vary. -If you're already a hard-core systems programmer, then the Camel Book +If you're already a hardcore systems programmer, then the Camel Book just might suffice for you to learn Perl from. But if you're not, check out the "Llama Book". It currently doesn't cover perl5, but the 2nd edition is nearly done and should be out by summer 97: @@ -279,7 +279,7 @@ There is a mailing list for discussing Macintosh Perl. Contact "mac-perl-request@iis.ee.ethz.ch". Also see Matthias Neeracher's (the creator and maintainer of MacPerl) -webpage at http://www.iis.ee.ethz.ch/~neeri/macintosh/perl.html for +web page at http://www.iis.ee.ethz.ch/~neeri/macintosh/perl.html for many links to interesting MacPerl sites, and the applications/MPW tools, precompiled. @@ -405,19 +405,19 @@ If you are reporting a bug in the perl interpreter or the modules shipped with perl, use the perlbug program in the perl distribution or email your report to perlbug@perl.com. -If you are posting a bug with a non-standard port (see the answer to +If you are posting a bug with a nonstandard port (see the answer to "What platforms is Perl available for?"), a binary distribution, or a -non-standard module (such as Tk, CGI, etc), then please see the +nonstandard module (such as Tk, CGI, etc), then please see the documentation that came with it to determine the correct place to post bugs. -Read the perlbug man page (perl5.004 or later) for more information. +Read the perlbug manpage (perl5.004 or later) for more information. =head2 What is perl.com? perl.org? The Perl Institute? perl.org is the official vehicle for The Perl Institute. The motto of TPI is "helping people help Perl help people" (or something like -that). It's a non-profit organization supporting development, +that). It's a nonprofit organization supporting development, documentation, and dissemination of perl. Current directors of TPI include Larry Wall, Tom Christiansen, and Randal Schwartz, whom you may have heard of somewhere else around here. @@ -425,8 +425,8 @@ may have heard of somewhere else around here. The perl.com domain is Tom Christiansen's domain. He created it as a public service long before perl.org came about. It's the original PBS of the Perl world, a clearinghouse for information about all things -Perlian, accepting no paid advertisements, glossy gifs, or (gasp!) -java applets on its pages. +Perlian, accepting no paid advertisements, glossy GIFs, or (gasp!) +Java applets on its pages. =head2 How do I learn about object-oriented Perl programming? diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod index 64dec98234..af7e53b8fe 100644 --- a/pod/perlfaq3.pod +++ b/pod/perlfaq3.pod @@ -11,7 +11,7 @@ and programming support. Have you looked at CPAN (see L<perlfaq2>)? The chances are that someone has already written a module that can solve your problem. -Have you read the appropriate man pages? Here's a brief index: +Have you read the appropriate manpages? Here's a brief index: Objects perlref, perlmod, perlobj, perltie Data Structures perlref, perllol, perldsc @@ -22,12 +22,12 @@ 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<perltoc> provides a crude table of contents for the perl man page set. +L<perltoc> provides a crude table of contents for the perl manpage set. =head2 How can I use Perl interactively? The typical approach uses the Perl debugger, described in the -perldebug(1) man page, on an "empty" program, like this: +perldebug(1) manpage, on an "empty" program, like this: perl -de 42 @@ -200,7 +200,7 @@ structure. If you're working with specialist data structures less memory than equivalent Perl modules. Another thing to try is learning whether your Perl was compiled with -the system malloc or with Perl's built-in malloc. Whichever one it +the system malloc or with Perl's builtin malloc. Whichever one it is, try using the other one and see whether this makes a difference. Information about malloc is in the F<INSTALL> file in the source distribution. You can find out whether you are using perl's malloc by @@ -235,7 +235,7 @@ use in other parts of your program. (NB: my() variables also execute about 10% faster than globals.) A global variable, of course, never goes out of scope, so you can't get its space automatically reclaimed, although undef()ing and/or delete()ing it will achieve the same effect. -In general, memory allocation and de-allocation isn't something you can +In general, memory allocation and deallocation isn't something you can or should be worrying about much in Perl, but even this capability (preallocation of data types) is in the works. @@ -244,15 +244,15 @@ or should be worrying about much in Perl, but even this capability Beyond the normal measures described to make general Perl programs faster or smaller, a CGI program has additional issues. It may be run several times per second. Given that each time it runs it will need -to be re-compiled and will often allocate a megabyte or more of system +to be recompiled and will often allocate a megabyte or more of system memory, this can be a killer. Compiling into C B<isn't going to help -you> because the process start-up overhead is where the bottleneck is. +you> because the process startup overhead is where the bottleneck is. There are at least two popular ways to avoid this overhead. One solution involves running the Apache HTTP server (available from http://www.apache.org/) with either of the mod_perl or mod_fastcgi plugin modules. With mod_perl and the Apache::* modules (from CPAN), -httpd will run with an embedded Perl interpreter which pre-compiles +httpd will run with an embedded Perl interpreter which precompiles your script and then executes it within the same address space without forking. The Apache extension also gives Perl access to the internal server API, so modules written in Perl can do just about anything a @@ -286,8 +286,8 @@ instead of fixing them, is little security indeed. You can try using encryption via source filters (Filter::* from CPAN). But crackers might be able to decrypt it. You can try using the -byte-code compiler and interpreter described below, but crackers might -be able to de-compile it. You can try using the native-code compiler +byte code compiler and interpreter described below, but crackers might +be able to decompile it. You can try using the native-code compiler described below, but crackers might be able to disassemble it. These pose varying degrees of difficulty to people wanting to get at your code, but none can definitively conceal it (this is true of every @@ -301,12 +301,12 @@ Your access to it does not give you permission to use it blah blah blah." We are not lawyers, of course, so you should see a lawyer if you want to be sure your licence's wording will stand up in court. -=head2 How can I compile my Perl program into byte-code or C? +=head2 How can I compile my Perl program into byte code or C? Malcolm Beattie has written a multifunction backend compiler, available from CPAN, that can do both these things. It is as of Feb-1997 in late alpha release, which means it's fun to play with if -you're a programmer but not really for people looking for turn-key +you're a programmer but not really for people looking for turnkey solutions. I<Please> understand that merely compiling into C does not in and of @@ -334,14 +334,14 @@ you link your main perl binary with this, it will make it miniscule. For example, on one author's system, /usr/bin/perl is only 11k in size! -=head2 How can I get '#!perl' to work on [MSDOS,NT,...]? +=head2 How can I get '#!perl' to work on [MS-DOS,Windows NT,...]? For OS/2 just use extproc perl -S -your_switches as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's -`extproc' handling). For DOS one should first invent a corresponding +`extproc' handling). For MS-DOS one should first invent a corresponding batch file, and codify it in C<ALTERNATIVE_SHEBANG> (see the F<INSTALL> file in the source distribution for more information). @@ -385,7 +385,7 @@ Yes. Read L<perlrun> for more information. Some examples follow. Ok, the last one was actually an obfuscated perl 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 MS-DOS/Macintosh/VMS system? The problem is usually that the command interpreters on those systems have rather different ideas about quoting than the Unix shells under @@ -398,10 +398,10 @@ For example: # Unix perl -e 'print "Hello world\n"' - # DOS, etc. + # MS-DOS, etc. perl -e "print \"Hello world\n\"" - # Mac + # Macintosh print "Hello world\n" (then Run "Myscript" or Shift-Command-R) @@ -409,15 +409,15 @@ For example: perl -e "print ""Hello world\n""" The problem is that none of this is reliable: it depends on the command -interpreter. Under Unix, the first two often work. Under DOS, it's +interpreter. Under Unix, the first two often work. Under MS-DOS, it's entirely possible neither works. If 4DOS was the command shell, I'd probably have better luck like this: perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" -Under the Mac, it depends which environment you are using. The MacPerl +Under the Macintosh, it depends which environment you are using. The MacPerl shell, or MPW, is much like Unix shells in its support for several -quoting variants, except that it makes free use of the Mac's non-ASCII +quoting variants, except that it makes free use of the Macintosh's non-ASCII characters as control characters. I'm afraid that there is no general solution to all of this. It is a @@ -470,7 +470,7 @@ my C program, what am I doing wrong? Download the ExtUtils::Embed kit from CPAN and run `make test'. If the tests pass, read the pods again and again and again. If they -fail, see L<perlbug> and send a bugreport with the output of +fail, see L<perlbug> and send a bug report with the output of C<make test TEST_VERBOSE=1> along with C<perl -V>. =head2 When I tried to run my script, I got this message. What does it diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod index 34b7e5b0f3..d3a7e8ccb9 100644 --- a/pod/perlfaq4.pod +++ b/pod/perlfaq4.pod @@ -271,7 +271,7 @@ C<tr///> function like so: $string = "ThisXlineXhasXsomeXx'sXinXit": $count = ($string =~ tr/X//); - print "There are $count X charcters in the string"; + print "There are $count X characters in the string"; This is fine if you are just looking for a single character. However, if you are trying to count multiple character substrings within a @@ -900,7 +900,7 @@ they end up doing is not what they do with ordinary hashes. Using C<keys %hash> in a scalar context returns the number of keys in the hash I<and> resets the iterator associated with the hash. You may need to do this if you use C<last> to exit a loop early so that when you -re-enter it, the hash iterator has been reset. +reenter it, the hash iterator has been reset. =head2 How can I get the unique keys from two hashes? @@ -955,7 +955,7 @@ Normally, merely accessing a key's value for a nonexistent key does I<not> cause that key to be forever there. This is different than awk's behavior. -=head2 How can I make the Perl equivalent of a C structure/C++ class/hash +=head2 How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays? Use references (documented in L<perlref>). Examples of complex data @@ -983,7 +983,7 @@ versus "binary" files. See L<perlfunc/"binmode">. If you're concerned about 8-bit ASCII data, then see L<perllocale>. -If you want to deal with multi-byte characters, however, there are +If you want to deal with multibyte characters, however, there are some gotchas. See the section on Regular Expressions. =head2 How do I determine whether a scalar is a number/whole/integer/float? @@ -994,7 +994,7 @@ Assuming that you don't care about IEEE notations like "NaN" or warn "has nondigits" if /\D/; warn "not a whole number" unless /^\d+$/; warn "not an integer" unless /^-?\d+$/; # reject +3 - warn "not an integer" unless /^[+-]?\d+$/; + warn "not an integer" unless /^[+-]?\d+$/; warn "not a decimal number" unless /^-?\d+\.?\d*$/; # rejects .2 warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/; warn "not a C float" diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod index 9c5e842793..47c6dead22 100644 --- a/pod/perlfaq5.pod +++ b/pod/perlfaq5.pod @@ -106,7 +106,7 @@ the changes you want, then copy that over the original. rename($new, $old) or die "can't rename $new to $old: $!"; Perl can do this sort of thing for you automatically with the C<-i> -command-line switch or the closely-related C<$^I> variable (see +command line switch or the closely-related C<$^I> variable (see L<perlrun> for more details). Note that C<-i> may require a suffix on some non-Unix systems; see the platform-specific documentation that came with your port. @@ -138,7 +138,7 @@ the last line of a file without making a copy or reading the whole file into memory: open (FH, "+< $file"); - while ( <FH> ) { $addr = tell(FH) unless eof(FH) } + while ( <FH> ) { $addr = tell(FH) unless eof(FH) } truncate(FH, $addr); Error checking is left as an exercise for the reader. @@ -233,7 +233,7 @@ one of its more specific derived classes. =head2 How can I set up a footer format to be used with write()? -There's no built-in way to do this, but L<perlform> has a couple of +There's no builtin way to do this, but L<perlform> has a couple of techniques to make it possible for the intrepid hacker. =head2 How can I write() into a string? @@ -358,7 +358,7 @@ permissions, timestamps, inode info, etc. =head2 How can I lock a file? -Perl's built-in flock() function (see L<perlfunc> for details) will call +Perl's builtin flock() function (see L<perlfunc> for details) will call flock(2) if that exists, fcntl(2) if it doesn't (on perl version 5.004 and later), and lockf(3) if neither of the two previous system calls exists. On some systems, it may even use a different form of native locking. @@ -409,10 +409,10 @@ over NFS, so this won't work (at least, not every time) over the net. Various schemes involving involving link() have been suggested, but these tend to involve busy-wait, which is also subdesirable. -=head2 I still don't get locking. I just want to increment the number +=head2 I still don't get locking. I just want to increment the number in the file. How can I do this? -Didn't anyone ever tell you web-page hit counters were useless? +Didn't anyone ever tell you web page hit counters were useless? Anyway, this is what to do: @@ -426,7 +426,7 @@ Anyway, this is what to do: # DO NOT UNLOCK THIS UNTIL YOU CLOSE close FH or die "can't close numfile: $!"; -Here's a much better web-page hit counter: +Here's a much better web page hit counter: $hits = int( (time() - 850_000_000) / rand(1_000) ); @@ -455,14 +455,14 @@ like this: Locking and error checking are left as an exercise for the reader. Don't forget them, or you'll be quite sorry. -Don't forget to set binmode() under DOS-like platforms when operating +Don't forget to set binmode() under MS-DOS-like platforms when operating on files that have anything other than straight text in them. See the docs on open() and on binmode() for more details. =head2 How do I get a file's timestamp in perl? If you want to retrieve the time at which the file was last read, -written, or had its meta-data (owner, etc) changed, you use the B<-M>, +written, or had its metadata (owner, etc) changed, you use the B<-M>, B<-A>, or B<-C> filetest operations as documented in L<perlfunc>. These retrieve the age of the file (measured against the start-time of your program) in days as a floating point number. To retrieve the "raw" @@ -602,7 +602,7 @@ The Term::ReadKey module from CPAN may be easier to use: printf "\nYou said %s, char number %03d\n", $key, ord $key; -For DOS systems, Dan Carson <dbc@tc.fluke.COM> reports the following: +For MS-DOS systems, Dan Carson <dbc@tc.fluke.COM> reports the following: To put the PC in "raw" mode, use ioctl with some magic numbers gleaned from msdos.c (Perl source file) and Ralf Brown's interrupt list (comes @@ -737,17 +737,17 @@ to, you may be able to do this: $rc = syscall(&SYS_close, $fd + 0); # must force numeric die "can't sysclose $fd: $!" unless $rc == -1; -=head2 Why can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` work? +=head2 Why can't I use "C:\temp\foo" in MS-DOS paths? What doesn't `C:\temp\foo.exe` work? Whoops! You just put a tab and a formfeed into that filename! Remember that within double quoted strings ("like\this"), the backslash is an escape character. The full list of these is in L<perlop/Quote and Quote-like Operators>. Unsurprisingly, you don't have a file called "c:(tab)emp(formfeed)oo" or -"c:(tab)emp(formfeed)oo.exe" on your DOS filesystem. +"c:(tab)emp(formfeed)oo.exe" on your MS-DOS filesystem. Either single-quote your strings, or (preferably) use forward slashes. -Since all DOS and Windows versions since something like MS-DOS 2.0 or so +Since all MS-DOS and Windows versions since something like MS-DOS 2.0 or so have treated C</> and C<\> the same in a path, you might as well use the one that doesn't clash with Perl -- or the POSIX shell, ANSI C and C++, awk, Tcl, Java, or Python, just to mention a few. @@ -755,7 +755,7 @@ awk, Tcl, Java, or Python, just to mention a few. =head2 Why doesn't glob("*.*") get all the files? Because even on non-Unix ports, Perl's glob function follows standard -Unix globbing semantics. You'll need C<glob("*")> to get all (non-hidden) +Unix globbing semantics. You'll need C<glob("*")> to get all (nonhidden) files. =head2 Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl? diff --git a/pod/perlfaq6.pod b/pod/perlfaq6.pod index 0adebd72fe..1cec15c669 100644 --- a/pod/perlfaq6.pod +++ b/pod/perlfaq6.pod @@ -11,7 +11,7 @@ with regular expressions, but those answers are found elsewhere in this document (in the section on Data and the Networking one on networking, to be precise). -=head2 How can I hope to use regular expressions without creating illegible and unmaintainable code? +=head2 How can I hope to use regular expressions without creating illegible and unmaintainable code? Three techniques can make regular expressions maintainable and understandable. @@ -96,8 +96,8 @@ record read in. while ( <> ) { while ( /\b(\w\S+)(\s+\1)+\b/gi ) { print "Duplicate $1 at paragraph $.\n"; - } - } + } + } Here's code that finds sentences that begin with "From " (which would be mangled by many mailers): @@ -138,7 +138,7 @@ on matching balanced text. $/ must be a string, not a regular expression. Awk has to be better for something. :-) -Actually, you could do this if you don't mind reading the whole file into +Actually, you could do this if you don't mind reading the whole file into undef $/; @records = split /your_pattern/, <FH>; @@ -217,10 +217,10 @@ See L<perllocale>. =head2 How can I match a locale-smart version of C</[a-zA-Z]/>? One alphabetic character would be C</[^\W\d_]/>, no matter what locale -you're in. Non-alphabetics would be C</[\W\d_]/> (assuming you don't +you're in. Non-alphabetics would be C</[\W\d_]/> (assuming you don't consider an underscore a letter). -=head2 How can I quote a variable to use in a regexp? +=head2 How can I quote a variable to use in a regexp? The Perl parser will expand $variable and @variable references in regular expressions unless the delimiter is a single quote. Remember, @@ -240,7 +240,7 @@ Without the \Q, the regexp would also spuriously match "di". =head2 What is C</o> really for? -Using a variable in a regular expression match forces a re-evaluation +Using a variable in a regular expression match forces a reevaluation (and perhaps recompilation) each time through. The C</o> modifier locks in the regexp the first time it's used. This always happens in a constant regular expression, and in fact, the pattern was compiled @@ -325,13 +325,13 @@ playing hot potato. Use the split function: while (<>) { - foreach $word ( split ) { + foreach $word ( split ) { # do something with $word here - } - } + } + } -Note that this isn't really a word in the English sense; it's just -chunks of consecutive non-whitespace characters. +Note that this isn't really a word in the English sense; it's just +chunks of consecutive non-whitespace characters. To work with only alphanumeric sequences, you might consider @@ -344,25 +344,25 @@ To work with only alphanumeric sequences, you might consider =head2 How can I print out a word-frequency or line-frequency summary? To do this, you have to parse out each word in the input stream. We'll -pretend that by word you mean chunk of alphabetics, hyphens, or -apostrophes, rather than the non-whitespace chunk idea of a word given +pretend that by word you mean chunk of alphabetics, hyphens, or +apostrophes, rather than the non-whitespace chunk idea of a word given in the previous question: while (<>) { while ( /(\b[^\W_\d][\w'-]+\b)/g ) { # misses "`sheep'" $seen{$1}++; - } - } + } + } while ( ($word, $count) = each %seen ) { print "$count $word\n"; - } + } If you wanted to do the same thing for lines, you wouldn't need a regular expression: - while (<>) { + while (<>) { $seen{$_}++; - } + } while ( ($line, $count) = each %seen ) { print "$count $line"; } @@ -495,7 +495,7 @@ Of course, that could have been written as while (<>) { chomp; PARSER: { - if ( /\G( \d+\b )/gx { + if ( /\G( \d+\b )/gx { print "number: $1\n"; redo PARSER; } @@ -520,7 +520,7 @@ But then you lose the vertical alignment of the regular expressions. While it's true that Perl's regular expressions resemble the DFAs (deterministic finite automata) of the egrep(1) program, they are in -fact implemented as NFAs (non-deterministic finite automata) to allow +fact implemented as NFAs (nondeterministic finite automata) to allow backtracking and backreferencing. And they aren't POSIX-style either, because those guarantee worst-case behavior for all cases. (It seems that some people prefer guarantees of consistency, even when what's @@ -538,7 +538,7 @@ side-effects, and side-effects can be mystifying. There's no void grep() that's not better written as a C<for> (well, C<foreach>, technically) loop. -=head2 How can I match strings with multi-byte characters? +=head2 How can I match strings with multibyte characters? This is hard, and there's no good way. Perl does not directly support wide characters. It pretends that a byte and a character are @@ -578,7 +578,7 @@ Or like this: Or like this: while ($martian =~ m/\G([A-Z][A-Z]|.)/gs) { # \G probably unneeded - print "found GX!\n", last if $1 eq 'GX'; + print "found GX!\n", last if $1 eq 'GX'; } Or like this: @@ -586,11 +586,11 @@ Or like this: die "sorry, Perl doesn't (yet) have Martian support )-:\n"; In addition, a sample program which converts half-width to full-width -katakana (in Shift-JIS or EUC encoding) is available from CPAN as +katakana (in Shift-JIS or EUC encoding) is available from CPAN as =for Tom make it so -There are many double- (and multi-) byte encodings commonly used these +There are many double (and multi) byte encodings commonly used these days. Some versions of these have 1-, 2-, 3-, and 4-byte characters, all mixed. diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod index 54380e62a4..c272c91e31 100644 --- a/pod/perlfaq7.pod +++ b/pod/perlfaq7.pod @@ -532,7 +532,7 @@ issue is the same here: my($foo) = <FILE>; # WRONG my $foo = <FILE>; # right -=head2 How do I redefine a built-in function, operator, or method? +=head2 How do I redefine a builtin function, operator, or method? Why do you want to do that? :-) @@ -576,7 +576,7 @@ how best to do this, so he left it out, even though it's been on the wish list since perl1. Here's a simple example of a switch based on pattern matching. We'll -do a multi-way conditional based on the type of reference stored in +do a multiway conditional based on the type of reference stored in $whatchamacallit: SWITCH: diff --git a/pod/perlfaq8.pod b/pod/perlfaq8.pod index 7250afbca5..bc8412bf6f 100644 --- a/pod/perlfaq8.pod +++ b/pod/perlfaq8.pod @@ -104,7 +104,7 @@ give the numeric values you want directly, using octal ("\015"), hex Even though with normal text files, a "\n" will do the trick, there is still no unified scheme for terminating a line that is portable -between Unix, DOS/Win, and Macintosh, except to terminate I<ALL> line +between Unix, MS-DOS/Windows, and Macintosh, except to terminate I<ALL> line ends with "\015\012", and strip what you don't need from the output. This applies especially to socket I/O and autoflushing, discussed next. @@ -208,7 +208,7 @@ You don't actually "trap" a control character. Instead, that character generates a signal, which you then trap. Signals are documented in L<perlipc/"Signals"> and chapter 6 of the Camel. -Be warned that very few C libraries are re-entrant. Therefore, if you +Be warned that very few C libraries are reentrant. Therefore, if you attempt to print() in a handler that got invoked during another stdio operation your internal structures will likely be in an inconsistent state, and your program will dump core. You can @@ -230,7 +230,7 @@ For example: However, because syscalls restart by default, you'll find that if you're in a "slow" call, such as E<lt>FHE<gt>, read(), connect(), or wait(), that the only way to terminate them is by "longjumping" out; -that is, by raising an exception. See the time-out handler for a +that is, by raising an exception. See the timeout handler for a blocking flock() in L<perlipc/"Signals"> or chapter 6 of the Camel. =head2 How do I modify the shadow password file on a Unix system? @@ -267,7 +267,7 @@ http://www.perl.com/CPAN/doc/misc/ancient/tutorial/eg/itimers.pl . =head2 How can I measure time under a second? In general, you may not be able to. The Time::HiRes module (available -from CPAN) provides this functionality for some systems. +from CPAN) provides this functionality for some systems. In general, you may not be able to. But if you system supports both the syscall() function in Perl as well as a system call like gettimeofday(2), @@ -311,7 +311,7 @@ END blocks you should also use Perl's exception-handling mechanism is its eval() operator. You can use eval() as setjmp and die() as longjmp. For details of this, see -the section on signals, especially the time-out handler for a blocking +the section on signals, especially the timeout handler for a blocking flock() in L<perlipc/"Signals"> and chapter 6 of the Camel. If exception handling is all you're interested in, try the @@ -352,7 +352,7 @@ Simple files like F<errno.h>, F<syscall.h>, and F<socket.h> were fine, but the hard ones like F<ioctl.h> nearly always need to hand-edited. Here's how to install the *.ph files: - 1. become super-user + 1. become superuser 2. cd /usr/include 3. h2ph *.h */*.h @@ -513,7 +513,7 @@ You have to do this: Just as with system(), no shell escapes happen when you exec() a list. -=head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MSDOS)? +=head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)? Because some stdio's set error and eof flags that need clearing. The POSIX module defines clearerr() that you can use. That is the @@ -552,7 +552,7 @@ Things that are awkward to do in the shell are easy to do in Perl, and this very awkwardness is what would make a shell->perl converter nigh-on impossible to write. By rewriting it, you'll think about what you're really trying to do, and hopefully will escape the shell's -pipeline datastream paradigm, which while convenient for some matters, +pipeline data stream paradigm, which while convenient for some matters, causes many inefficiencies. =head2 Can I use perl to run a telnet or ftp session? diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod index 2c9a3e063b..9e6355f816 100644 --- a/pod/perlfaq9.pod +++ b/pod/perlfaq9.pod @@ -51,7 +51,7 @@ http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/striphtml.gz =head2 How do I extract URLs? -A quick but imperfect approach is +A quick but imperfect approach is #!/usr/bin/perl -n00 # qxurl - tchrist@perl.com @@ -127,7 +127,7 @@ server, or perhaps check some of the other FAQs referenced above. The HTTPD::UserAdmin and HTTPD::GroupAdmin modules provide a consistent OO interface to these files, regardless of how they're -stored. Databases may be text, dbm, Berkley DB or any database with a +stored. Databases may be text, dbm, Berkeley DB or any database with a DBI compatible driver. HTTPD::UserAdmin supports files used by the `Basic' and `Digest' authentication schemes. Here's an example: @@ -224,8 +224,8 @@ Again, the best way is often just to ask the user. =head2 How do I send/read mail? Sending mail: the Mail::Mailer module from CPAN (part of the MailTools -package) is UNIX-centric, while Mail::Internet uses Net::SMTP which is -not UNIX-centric. Reading mail: use the Mail::Folder module from CPAN +package) is Unix-centric, while Mail::Internet uses Net::SMTP which is +not Unix-centric. Reading mail: use the Mail::Folder module from CPAN (part of the MailFolder package) or the Mail::Internet module from CPAN (also part of the MailTools package). diff --git a/pod/perlform.pod b/pod/perlform.pod index 4e55e02800..75351b6934 100644 --- a/pod/perlform.pod +++ b/pod/perlform.pod @@ -5,20 +5,20 @@ perlform - Perl formats =head1 DESCRIPTION Perl has a mechanism to help you generate simple reports and charts. To -facilitate this, Perl helps you code up your output page -close to how it will look when it's printed. It can keep -track of things like how many lines on a page, what page you're on, when to -print page headers, etc. Keywords are borrowed from FORTRAN: -format() to declare and write() to execute; see their entries in -L<perlfunc>. Fortunately, the layout is much more legible, more like -BASIC's PRINT USING statement. Think of it as a poor man's nroff(1). - -Formats, like packages and subroutines, are declared rather than executed, -so they may occur at any point in your program. (Usually it's best to -keep them all together though.) They have their own namespace apart from -all the other "types" in Perl. This means that if you have a function -named "Foo", it is not the same thing as having a format named "Foo". -However, the default name for the format associated with a given +facilitate this, Perl helps you code up your output page close to how it +will look when it's printed. It can keep track of things like how many +lines are on a page, what page you're on, when to print page headers, +etc. Keywords are borrowed from FORTRAN: format() to declare and write() +to execute; see their entries in L<perlfunc>. Fortunately, the layout is +much more legible, more like BASIC's PRINT USING statement. Think of it +as a poor man's nroff(1). + +Formats, like packages and subroutines, are declared rather than +executed, so they may occur at any point in your program. (Usually it's +best to keep them all together though.) They have their own namespace +apart from all the other "types" in Perl. This means that if you have a +function named "Foo", it is not the same thing as having a format named +"Foo". However, the default name for the format associated with a given filehandle is the same as the name of the filehandle. Thus, the default format for STDOUT is name "STDOUT", and the default format for filehandle TEMP is name "TEMP". They just look the same. They aren't. @@ -30,7 +30,7 @@ Output record formats are declared as follows: . If name is omitted, format "STDOUT" is defined. FORMLIST consists of -a sequence of lines, each of which may be of one of three types: +a sequence of lines, each of which may be one of three types: =over 4 @@ -53,7 +53,7 @@ that substitute values into the line. Each field in a picture line starts with either "@" (at) or "^" (caret). These lines do not undergo any kind of variable interpolation. The at field (not to be confused with the array marker @) is the normal kind of field; the other kind, caret fields, are used -to do rudimentary multi-line text block filling. The length of the field +to do rudimentary multiline text block filling. The length of the field is supplied by padding out the field with multiple "E<lt>", "E<gt>", or "|" characters to specify, respectively, left justification, right justification, or centering. If the variable would exceed the width @@ -63,8 +63,8 @@ As an alternate form of right justification, you may also use "#" characters (with an optional ".") to specify a numeric field. This way you can line up the decimal points. If any value supplied for these fields contains a newline, only the text up to the newline is printed. -Finally, the special field "@*" can be used for printing multi-line, -non-truncated values; it should appear by itself on a line. +Finally, the special field "@*" can be used for printing multiline, +nontruncated values; it should appear by itself on a line. The values are specified on the following line in the same order as the picture fields. The expressions providing the values should be @@ -105,7 +105,7 @@ first, the line will be repeated until all the fields on the line are exhausted. (If you use a field of the at variety, the expression you supply had better not give the same value every time forever!) -Top-of-form processing is by default handled by a format with the +Top-of-form processing is by default handled by a format with the same name as the current filehandle with "_TOP" concatenated to it. It's triggered at the top of each page. See L<perlfunc/write>. @@ -169,7 +169,7 @@ the first) is stored in C<$^L> (C<$FORMAT_FORMFEED>). These variables are set on a per-filehandle basis, so you'll need to select() into a different one to affect them: - select((select(OUTF), + select((select(OUTF), $~ = "My_Other_Format", $^ = "My_Top_Format" )[0]); @@ -205,25 +205,25 @@ Much better! =head1 NOTES -Because the values line may contain arbitrary expressions (for at fields, +Because the values line may contain arbitrary expressions (for at fields, not caret fields), you can farm out more sophisticated processing to other functions, like sprintf() or one of your own. For example: - format Ident = + format Ident = @<<<<<<<<<<<<<<< &commify($n) . To get a real at or caret into the field, do this: - format Ident = + format Ident = I have an @ here. "@" . To center a whole line of text, do something like this: - format Ident = + format Ident = @||||||||||||||||||||||||||||||||||||||||||||||| "Some text line" . @@ -240,12 +240,12 @@ on the current number of columns, and then eval() it: . '$entry' . "\n"; . ".\n"; print $format if $Debugging; - eval $format; + eval $format; die $@ if $@; Which would generate a format looking something like this: - format STDOUT = + format STDOUT = ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< $entry ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~ @@ -254,7 +254,7 @@ Which would generate a format looking something like this: Here's a little program that's somewhat like fmt(1): - format = + format = ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~ $_ @@ -264,7 +264,7 @@ Here's a little program that's somewhat like fmt(1): while (<>) { s/\s*\n\s*/ /g; write; - } + } =head2 Footers @@ -277,10 +277,10 @@ Here's one strategy: If you have a fixed-size footer, you can get footers by checking $FORMAT_LINES_LEFT before each write() and print the footer yourself if necessary. -Here's another strategy; open a pipe to yourself, using C<open(MESELF, "|-")> -(see L<perlfunc/open()>) and always write() to MESELF instead of -STDOUT. Have your child process massage its STDIN to rearrange -headers and footers however you like. Not very convenient, but doable. +Here's another strategy: Open a pipe to yourself, using C<open(MYSELF, "|-")> +(see L<perlfunc/open()>) and always write() to MYSELF instead of STDOUT. +Have your child process massage its STDIN to rearrange headers and footers +however you like. Not very convenient, but doable. =head2 Accessing Formatting Internals @@ -305,7 +305,7 @@ is to printf(), do this: $^A = ""; formline($format,@_); return $^A; - } + } $string = swrite(<<'END', 1, 2, 3); Check me out diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index c4de4a39ae..25c684af2e 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -48,7 +48,7 @@ example, the third line above produces: Useless use of integer addition in void context at - line 1. For functions that can be used in either a scalar or list context, -non-abortive failure is generally indicated in a scalar context by +nonabortive failure is generally indicated in a scalar context by returning the undefined value, and in a list context by returning the null list. @@ -126,7 +126,7 @@ stat, symlink, umask, unlink, utime caller, continue, die, do, dump, eval, exit, goto, last, next, redo, return, sub, wantarray -=item Keywords related to scoping +=item Keywords related to scoping caller, import, local, my, package, use @@ -225,7 +225,7 @@ operator may be any of: -e File exists. -z File has zero size. - -s File has non-zero size (returns size). + -s File has nonzero size (returns size). -f File is a plain file. -d File is a directory. @@ -275,7 +275,7 @@ are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file containing null in the first block is considered a binary file. If C<-T> or C<-B> is used on a filehandle, the current stdio buffer is examined rather than the first block. Both C<-T> and C<-B> return TRUE on a null -file, or a file at EOF when testing a filehandle. Because you have to +file, or a file at EOF when testing a filehandle. Because you have to read a file to do the C<-T> test, on most occasions you want to use a C<-f> against the file first, as in C<next unless -f $file && -T $file>. @@ -300,7 +300,7 @@ symbolic link, not the real file.) Example: =item abs VALUE -=item abs +=item abs Returns the absolute value of its argument. If VALUE is omitted, uses $_. @@ -313,7 +313,7 @@ See example in L<perlipc/"Sockets: Client/Server Communication">. =item alarm SECONDS -=item alarm +=item alarm Arranges to have a SIGALRM delivered to this process after the specified number of seconds have elapsed. If SECONDS is not specified, @@ -326,8 +326,8 @@ starting a new one. The returned value is the amount of time remaining on the previous timer. For delays of finer granularity than one second, you may use Perl's -syscall() interface to access setitimer(2) if your system supports it, -or else see L</select()> below. It is not advised to intermix alarm() +syscall() interface to access setitimer(2) if your system supports it, +or else see L</select()>. It is usually a mistake to intermix alarm() and sleep() calls. If you want to use alarm() to time out a system call you need to use an @@ -370,9 +370,9 @@ L<perlipc/"Sockets: Client/Server Communication">. Arranges for the file to be read or written in "binary" mode in operating systems that distinguish between binary and text files. Files that are not in binary mode have CR LF sequences translated to LF on input and LF -translated to CR LF on output. Binmode has no effect under Unix; in DOS +translated to CR LF on output. Binmode has no effect under Unix; in MS-DOS and similarly archaic systems, it may be imperative--otherwise your -DOS-damaged C library may mangle your file. The key distinction between +MS-DOS-damaged C library may mangle your file. The key distinction between systems that need binmode and those that don't is their text file formats. Systems like Unix and Plan9 that delimit lines with a single character, and that encode that character in C as '\n', do not need @@ -406,7 +406,7 @@ With EXPR, it returns some extra information that the debugger uses to print a stack trace. The value of EXPR indicates how many call frames to go back before the current one. - ($package, $filename, $line, $subroutine, + ($package, $filename, $line, $subroutine, $hasargs, $wantarray, $evaltext, $is_require) = caller($i); Here $subroutine may be C<"(eval)"> if the frame is not a subroutine @@ -420,7 +420,7 @@ an C<L<eval EXPR>>) frame. Furthermore, when called from within the DB package, caller returns more detailed information: it sets the list variable @DB::args to be the -arguments with which that subroutine was invoked. +arguments with which the subroutine was invoked. =item chdir EXPR @@ -509,7 +509,7 @@ Returns the number of files successfully changed. $cnt = chown $uid, $gid, 'foo', 'bar'; chown $uid, $gid, @filenames; -Here's an example that looks up non-numeric uids in the passwd file: +Here's an example that looks up nonnumeric uids in the passwd file: print "User: "; chop($user = <STDIN>); @@ -522,14 +522,14 @@ Here's an example that looks up non-numeric uids in the passwd file: @ary = <${pattern}>; # expand filenames chown $uid, $gid, @ary; -On most systems, you are not allowed to change the ownership of the +On most systems, you are not allowed to change the ownership of the file unless you're the superuser, although you should be able to change the group to any of your secondary groups. On insecure systems, these restrictions may be relaxed, but this is not a portable assumption. =item chr NUMBER -=item chr +=item chr Returns the character represented by that NUMBER in the character set. For example, C<chr(65)> is "A" in ASCII. For the reverse, use L<ord>. @@ -538,7 +538,7 @@ If NUMBER is omitted, uses $_. =item chroot FILENAME -=item chroot +=item chroot This function works as the system call by the same name: it makes the named directory the new root directory for all further pathnames that @@ -627,9 +627,9 @@ their own password: die "Sorry...\n"; } else { print "ok\n"; - } + } -Of course, typing in your own password to whomever asks you +Of course, typing in your own password to whomever asks you for it is unwise. =item dbmclose HASH @@ -675,7 +675,7 @@ rich implementation. =item defined EXPR -=item defined +=item defined Returns a Boolean value telling whether EXPR has a value other than the undefined value C<undef>. If EXPR is not present, C<$_> will be @@ -738,7 +738,7 @@ them as not defined anymore, but you shoudln't do that unless you don't plan to use them again, because it saves time when you load them up again to have memory already ready to be filled. -This counter-intuitive behaviour of defined() on aggregates may be +This counterintuitive behaviour of defined() on aggregates may be changed, fixed, or broken in a future release of Perl. See also L<undef>, L<exists>, L<ref>. @@ -773,7 +773,7 @@ hash element lookup or hash slice: Outside of an eval(), prints the value of LIST to C<STDERR> and exits with the current value of C<$!> (errno). If C<$!> is 0, exits with the value of -C<($? E<gt>E<gt> 8)> (back-tick `command` status). If C<($? E<gt>E<gt> 8)> +C<($? E<gt>E<gt> 8)> (backtick `command` status). If C<($? E<gt>E<gt> 8)> is 0, exits with 255. Inside an eval(), the error message is stuffed into C<$@>, and the eval() is terminated with the undefined value; this makes die() the way to raise an exception. @@ -781,7 +781,7 @@ die() the way to raise an exception. Equivalent examples: die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news'; - chdir '/usr/spool/news' or die "Can't cd to spool: $!\n" + chdir '/usr/spool/news' or die "Can't cd to spool: $!\n" If the value of EXPR does not end in a newline, the current script line number and input line number (if any) are also printed, and a newline @@ -832,7 +832,7 @@ except that it's more efficient, more concise, keeps track of the current filename for error messages, and searches all the B<-I> libraries if the file isn't in the current directory (see also the @INC array in L<perlvar/Predefined Names>). It's the same, however, in that it does -re-parse the file every time you call it, so you probably don't want to +reparse the file every time you call it, so you probably don't want to do this inside a loop. Note that inclusion of library modules is better done with the @@ -938,7 +938,7 @@ I<EACH> file in a while (E<lt>E<gt>) loop. Examples: } Practical hint: you almost never need to use C<eof> in Perl, because the -input operators return undef when they run out of data. +input operators return undef when they run out of data. =item eval EXPR @@ -971,7 +971,7 @@ form to trap run-time errors without incurring the penalty of recompiling each time. The error, if any, is still returned in C<$@>. Examples: - # make divide-by-zero non-fatal + # make divide-by-zero nonfatal eval { $answer = $a / $b; }; warn $@ if $@; # same thing, but less efficient @@ -1001,7 +1001,7 @@ die() again, which has the effect of changing their error messages: print $@ if $@; # prints "bar barfs here" } -With an eval(), you should be especially careful to remember what's +With an eval(), you should be especially careful to remember what's being looked at when: eval $x; # CASE 1 @@ -1020,7 +1020,7 @@ and 4 likewise behave in the same way: they run the code '$x', which does nothing but return the value of C<$x>. (Case 4 is preferred for purely visual reasons, but it also has the advantage of compiling at compile-time instead of at run-time.) Case 5 is a place where -normally you I<WOULD> like to use double quotes, except that in that +normally you I<WOULD> like to use double quotes, except that in this particular situation, you can just use symbolic references instead, as in case 6. @@ -1047,7 +1047,7 @@ If you don't really want to execute the first argument, but want to lie to the program you are executing about its own name, you can specify the program you actually want to run as an "indirect object" (without a comma) in front of the LIST. (This always forces interpretation of the -LIST as a multi-valued list, even if there is only a single scalar in +LIST as a multivalued list, even if there is only a single scalar in the list.) Example: $shell = '/bin/csh'; @@ -1085,7 +1085,7 @@ are called before exit.) Example: exit 0 if $ans =~ /^[Xx]/; See also die(). If EXPR is omitted, exits with 0 status. The only -univerally portable values for EXPR are 0 for success and 1 for error; +universally portable values for EXPR are 0 for success and 1 for error; all other values are subject to unpredictable interpretation depending on the environment in which the Perl program is running. @@ -1095,9 +1095,9 @@ which can be trapped by an eval(). =item exp EXPR -=item exp +=item exp -Returns I<e> (the natural logarithm base) to the power of EXPR. +Returns I<e> (the natural logarithm base) to the power of EXPR. If EXPR is omitted, gives C<exp($_)>. =item fcntl FILEHANDLE,FUNCTION,SCALAR @@ -1190,7 +1190,7 @@ zombies: $SIG{CHLD} = sub { wait }; -There's also the double-fork trick (error checking on +There's also the double-fork trick (error checking on fork() returns omitted); unless ($pid = fork) { @@ -1218,7 +1218,7 @@ you're done. You should reopen those to /dev/null if it's any issue. Declare a picture format with use by the write() function. For example: - format Something = + format Something = Test: @<<<<<<<< @||||| @>>>>> $str, $%, '$' . int($num) . @@ -1263,7 +1263,7 @@ single-characters, however. For that, try something more like: system "stty cbreak </dev/tty >/dev/tty 2>&1"; } else { - system "stty", '-icanon', 'eol', "\001"; + system "stty", '-icanon', 'eol', "\001"; } $key = getc(STDIN); @@ -1276,18 +1276,18 @@ single-characters, however. For that, try something more like: } print "\n"; -Determination of whether $BSD_STYLE should be set -is left as an exercise to the reader. +Determination of whether $BSD_STYLE should be set +is left as an exercise to the reader. The POSIX::getattr() function can do this more portably on systems alleging POSIX compliance. See also the C<Term::ReadKey> module from your nearest CPAN site; -details on CPAN can be found on L<perlmod/CPAN>. +details on CPAN can be found on L<perlmod/CPAN>. =item getlogin Returns the current login from F</etc/utmp>, if any. If null, use -getpwuid(). +getpwuid(). $login = getlogin || getpwuid($<) || "Kilroy"; @@ -1446,26 +1446,26 @@ L<perlop/"I/O Operators">. =item gmtime EXPR Converts a time as returned by the time function to a 9-element array -with the time localized for the standard Greenwich time zone. +with the time localized for the standard Greenwich time zone. Typically used as follows: - + # 0 1 2 3 4 5 6 7 8 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime(time); All array elements are numeric, and come straight out of a struct tm. In particular this means that $mon has the range 0..11 and $wday has -the range 0..6. Also, $year is the number of years since 1900, I<not> -simply the last two digits of the year. +the range 0..6 with sunday as day 0. Also, $year is the number of +years since 1900, I<not> simply the last two digits of the year. If EXPR is omitted, does C<gmtime(time())>. -In a scalar context, prints out the ctime(3) value: +In a scalar context, returns the ctime(3) value: $now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994" -Also see the F<timegm.pl> library, and the strftime(3) function available -via the POSIX module. +Also see the timegm() function provided by the Time::Local module, +and the strftime(3) function available via the POSIX module. =item goto LABEL @@ -1501,7 +1501,7 @@ will be able to tell that this routine was called first. =item grep EXPR,LIST -This is similar in spirit to, but not the same as, L<grep(1)> +This is similar in spirit to, but not the same as, grep(1) and its relatives. In particular, it is not limited to using regular expressions. @@ -1526,9 +1526,9 @@ actually modifies the element in the original list. =item hex EXPR -=item hex +=item hex -Interprets EXPR as a hex string and returns the corresponding +Interprets EXPR as a hex string and returns the corresponding value. (To convert strings that might start with either 0 or 0x see L<oct>.) If EXPR is omitted, uses $_. @@ -1537,10 +1537,10 @@ see L<oct>.) If EXPR is omitted, uses $_. =item import -There is no built-in import() function. It is merely an ordinary +There is no builtin import() function. It is merely an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The use() function calls the import() method -for the package used. See also L</use>, L<perlmod>, and L<Exporter>. +for the package used. See also L</use()>, L<perlmod>, and L<Exporter>. =item index STR,SUBSTR,POSITION @@ -1554,7 +1554,7 @@ one less than the base, ordinarily -1. =item int EXPR -=item int +=item int Returns the integer portion of EXPR. If EXPR is omitted, uses $_. @@ -1568,7 +1568,7 @@ first to get the correct function definitions. If F<ioctl.ph> doesn't exist or doesn't have the correct definitions you'll have to roll your own, based on your C header files such as F<E<lt>sys/ioctl.hE<gt>>. (There is a Perl script called B<h2ph> that comes with the Perl kit which -may help you in this, but it's non-trivial.) SCALAR will be read and/or +may help you in this, but it's nontrivial.) SCALAR will be read and/or written depending on the FUNCTION--a pointer to the string value of SCALAR will be passed as the third argument of the actual ioctl call. (If SCALAR has no string value but does have a numeric value, that value will be @@ -1605,7 +1605,7 @@ system: =item join EXPR,LIST -Joins the separate strings of LIST or ARRAY into a single string with +Joins the separate strings of LIST into a single string with fields separated by the value of EXPR, and returns the string. Example: @@ -1635,7 +1635,7 @@ or how about sorted by key: print $key, '=', $ENV{$key}, "\n"; } -To sort an array by value, you'll need to use a C<sort{}> function. +To sort an array by value, you'll need to use a C<sort> function. Here's a descending numeric sort of a hash by its values: foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) { @@ -1658,8 +1658,8 @@ as trying has no effect). =item kill LIST -Sends a signal to a list of processes. The first element of -the list must be the signal to send. Returns the number of +Sends a signal to a list of processes. The first element of +the list must be the signal to send. Returns the number of processes successfully signaled. $cnt = kill 1, $child1, $child2; @@ -1687,17 +1687,17 @@ C<continue> block, if any, is not executed: =item lc EXPR -=item lc +=item lc Returns an lowercased version of EXPR. This is the internal function -implementing the \L escape in double-quoted strings. +implementing the \L escape in double-quoted strings. Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>. If EXPR is omitted, uses $_. =item lcfirst EXPR -=item lcfirst +=item lcfirst Returns the value of EXPR with the first character lowercased. This is the internal function implementing the \l escape in double-quoted strings. @@ -1707,7 +1707,7 @@ If EXPR is omitted, uses $_. =item length EXPR -=item length +=item length Returns the length in characters of the value of EXPR. If EXPR is omitted, returns length of $_. @@ -1739,24 +1739,27 @@ Converts a time as returned by the time function to a 9-element array with the time analyzed for the local time zone. Typically used as follows: + # 0 1 2 3 4 5 6 7 8 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time); All array elements are numeric, and come straight out of a struct tm. In particular this means that $mon has the range 0..11 and $wday has -the range 0..6 and $year is year-1900, that is, $year is 123 in year -2023. If EXPR is omitted, uses the current time ("localtime(time)"). +the range 0..6 with sunday as day 0. Also, $year is the number of +years since 1900, that is, $year is 123 in year 2023. + +If EXPR is omitted, uses the current time (C<localtime(time)>). In a scalar context, returns the ctime(3) value: $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994" -Also see the Time::Local module, and the strftime(3) function available -via the POSIX module. +Also see the Time::Local module, and the strftime(3) and mktime(3) +function available via the POSIX module. =item log EXPR -=item log +=item log Returns logarithm (base I<e>) of EXPR. If EXPR is omitted, returns log of $_. @@ -1765,7 +1768,7 @@ of $_. =item lstat EXPR -=item lstat +=item lstat Does the same thing as the stat() function, but stats a symbolic link instead of the file the symbolic link points to. If symbolic links are @@ -1862,7 +1865,7 @@ See the "use" function, which "no" is the opposite of. =item oct EXPR -=item oct +=item oct Interprets EXPR as an octal string and returns the corresponding value. (If EXPR happens to start off with 0x, interprets it as @@ -1907,9 +1910,9 @@ L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication"> for alternatives.) Opening '-' opens STDIN and opening 'E<gt>-' opens STDOUT. Open returns -non-zero upon success, the undefined value otherwise. If the open +nonzero upon success, the undefined value otherwise. If the open involved a pipe, the return value happens to be the pid of the -subprocess. +subprocess. If you're unfortunate enough to be running Perl on a system that distinguishes between text files and binary files (modern operating @@ -2006,7 +2009,7 @@ In the child process the filehandle isn't opened--i/o happens from/to the new STDOUT or STDIN. Typically this is used like the normal piped open when you want to exercise more control over just how the pipe command gets executed, such as when you are running setuid, and -don't want to have to scan shell commands for metacharacters. +don't want to have to scan shell commands for metacharacters. The following pairs are more or less equivalent: open(FOO, "|tr '[a-z]' '[A-Z]'"); @@ -2072,7 +2075,7 @@ DIRHANDLEs have their own namespace separate from FILEHANDLEs. =item ord EXPR -=item ord +=item ord Returns the numeric ascii value of the first character of EXPR. If EXPR is omitted, uses $_. For the reverse, see L<chr>. @@ -2206,7 +2209,7 @@ for examples of such things. =item pop ARRAY -=item pop +=item pop Pops and returns the last value of the array, shortening the array by 1. Has a similar effect to @@ -2220,7 +2223,7 @@ like shift(). =item pos SCALAR -=item pos +=item pos Returns the offset of where the last C<m//g> search left off for the variable is in question ($_ is used when the variable is not specified). May be @@ -2300,7 +2303,7 @@ Generalized quotes. See L<perlop>. =item quotemeta EXPR -=item quotemeta +=item quotemeta Returns the value of EXPR with all non-alphanumeric characters backslashed. (That is, all characters not matching @@ -2316,7 +2319,7 @@ If EXPR is omitted, uses $_. =item rand Returns a random fractional number between 0 and the value of EXPR. -(EXPR should be positive.) If EXPR is omitted, returns a value between +(EXPR should be positive.) If EXPR is omitted, returns a value between 0 and 1. Automatically calls srand() unless srand() has already been called. See also srand(). @@ -2353,7 +2356,7 @@ chdir() there, it would have been testing the wrong file. =item readlink EXPR -=item readlink +=item readlink Returns the value of a symbolic link, if symbolic links are implemented. If not, gives a fatal error. If there is some system @@ -2367,7 +2370,7 @@ data into variable SCALAR from the specified SOCKET filehandle. Actually does a C recvfrom(), so that it can returns the address of the sender. Returns the undefined value if there's an error. SCALAR will be grown or shrunk to the length actually read. Takes the same flags -as the system call of the same name. +as the system call of the same name. See L<perlipc/"UDP: Message Passing"> for examples. =item redo LABEL @@ -2399,7 +2402,7 @@ themselves about what was just input: =item ref EXPR -=item ref +=item ref Returns a TRUE value if EXPR is a reference, FALSE otherwise. If EXPR is not specified, $_ will be used. The value returned depends on the @@ -2413,15 +2416,15 @@ Builtin types include: CODE GLOB -If the referenced object has been blessed into a package, then that package +If the referenced object has been blessed into a package, then that package name is returned instead. You can think of ref() as a typeof() operator. if (ref($r) eq "HASH") { print "r is a reference to a hash.\n"; - } + } if (!ref ($r) { print "r is not a reference at all.\n"; - } + } See also L<perlref>. @@ -2470,12 +2473,12 @@ end such a file with "1;" unless you're sure it'll return TRUE otherwise. But it's better just to put the "C<1;>", in case you add more statements. -If EXPR is a bare word, the require assumes a "F<.pm>" extension and +If EXPR is a bareword, the require assumes a "F<.pm>" extension and replaces "F<::>" with "F</>" in the filename for you, -to make it easy to load standard modules. This form of loading of +to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace. -For a yet-more-powerful import facility, see L</use> and +For a yet-more-powerful import facility, see L</use> and L<perlmod>. =item reset EXPR @@ -2500,9 +2503,17 @@ ARGV and ENV arrays. Resets only package variables--lexical variables are unaffected, but they clean themselves up on scope exit anyway, so you'll probably want to use them instead. See L</my>. -=item return LIST +=item return EXPR + +=item return + +Returns from a subroutine, eval(), or do FILE with the value of the +given EXPR. Evaluation of EXPR may be in a list, scalar, or void +context, depending on how the return value will be used, and the context +may vary from one execution to the next (see wantarray()). If no EXPR +is given, returns an empty list in a list context, an undefined value in +a scalar context, or nothing in a void context. -Returns from a subroutine, eval(), or do FILE with the value specified. (Note that in the absence of a return, a subroutine, eval, or do FILE will automatically return the value of the last expression evaluated.) @@ -2541,7 +2552,7 @@ last occurrence at or before that position. =item rmdir FILENAME -=item rmdir +=item rmdir Deletes the directory specified by FILENAME if it is empty. If it succeeds it returns 1, otherwise it returns 0 and sets C<$!> (errno). If @@ -2554,11 +2565,11 @@ The substitution operator. See L<perlop>. =item scalar EXPR Forces EXPR to be interpreted in a scalar context and returns the value -of EXPR. +of EXPR. @counts = ( scalar @a, scalar @b, scalar @c ); -There is no equivalent operator to force an expression to +There is no equivalent operator to force an expression to be interpolated in a list context because it's in practice never needed. If you really wanted to do so, however, you could use the construction C<@{[ (some expression) ]}>, but usually a simple @@ -2571,7 +2582,7 @@ call of stdio. FILEHANDLE may be an expression whose value gives the name of the filehandle. The values for WHENCE are 0 to set the file pointer to POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for -this from POSIX module. Returns 1 upon success, 0 otherwise. +this from the POSIX module. Returns 1 upon success, 0 otherwise. On some systems you have to do a seek whenever you switch between reading and writing. Amongst other things, this may have the effect of calling @@ -2661,7 +2672,7 @@ The usual idiom is: ($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout); -or to block until something becomes ready just do this +or to block until something becomes ready just do this $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); @@ -2781,12 +2792,12 @@ has the same interpretation as in the system call of the same name. =item sin EXPR -=item sin +=item sin Returns the sine of EXPR (expressed in radians). If EXPR is omitted, returns sine of $_. -For the inverse sine operation, you may use the POSIX::sin() +For the inverse sine operation, you may use the POSIX::asin() function, or use this relation: sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) } @@ -2805,8 +2816,8 @@ you requested, depending on how it counts seconds. Most modern systems always sleep the full amount. For delays of finer granularity than one second, you may use Perl's -syscall() interface to access setitimer(2) if your system supports it, -or else see L</select()> below. +syscall() interface to access setitimer(2) if your system supports it, +or else see L</select()> below. See also the POSIX module's sigpause() function. @@ -2862,7 +2873,7 @@ Examples: @articles = sort {$a cmp $b} @files; # now case-insensitively - @articles = sort { uc($a) cmp uc($b)} @files; + @articles = sort {uc($a) cmp uc($b)} @files; # same thing in reversed order @articles = sort {$b cmp $a} @files; @@ -2893,8 +2904,8 @@ Examples: print sort @george, 'to', @harry; # prints AbelAxedCainPunishedcatchaseddoggonetoxyz - # inefficiently sort by descending numeric compare using - # the first integer after the first = sign, or the + # inefficiently sort by descending numeric compare using + # the first integer after the first = sign, or the # whole record case-insensitively otherwise @new = sort { @@ -2907,10 +2918,10 @@ Examples: # we'll build auxiliary indices instead # for speed @nums = @caps = (); - for (@old) { + for (@old) { push @nums, /=(\d+)/; push @caps, uc($_); - } + } @new = @old[ sort { $nums[$b] <=> $nums[$a] @@ -3031,7 +3042,7 @@ produces the list value (1, '-', 10, ',', 20) -If you had the entire header of a normal Unix email message in $header, +If you had the entire header of a normal Unix email message in $header, you could split it up into fields and their values this way: $header =~ s/\n\s+/ /g; # fix continuation lines @@ -3053,12 +3064,12 @@ Example: open(passwd, '/etc/passwd'); while (<passwd>) { - ($login, $passwd, $uid, $gid, $gcos, + ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/); ... } -(Note that $shell above will still have a newline on it. See L</chop>, +(Note that $shell above will still have a newline on it. See L</chop>, L</chomp>, and L</join>.) =item sprintf FORMAT, LIST @@ -3075,7 +3086,7 @@ dump core when fed ludicrous arguments. =item sqrt EXPR -=item sqrt +=item sqrt Return the square root of EXPR. If EXPR is omitted, returns square root of $_. @@ -3113,11 +3124,11 @@ function is to "seed" the rand() function so that rand() can produce a different sequence each time you run your program. Just do it once at the top of your program, or you I<won't> get random numbers out of rand()! -Frequently called programs (like CGI scripts) that simply use +Frequently called programs (like CGI scripts) that simply use time ^ $$ -for a seed can fall prey to the mathematical property that +for a seed can fall prey to the mathematical property that a^b == (a+1)^(b+1) @@ -3127,7 +3138,7 @@ one-third of the time. So don't do that. =item stat EXPR -=item stat +=item stat Returns a 13-element array giving the status info for a file, either the file opened via FILEHANDLE, or named by EXPR. If EXPR is omitted, it @@ -3139,22 +3150,22 @@ follows: $atime,$mtime,$ctime,$blksize,$blocks) = stat($filename); -Not all fields are supported on all filesystem types. Here are the +Not all fields are supported on all filesystem types. Here are the meaning of the fields: - dev device number of filesystem - ino inode number - mode file mode (type and permissions) - nlink number of (hard) links to the file - uid numeric user ID of file's owner - gid numeric group ID of file's owner - rdev the device identifier (special files only) - size total size of file, in bytes - atime last access time since the epoch - mtime last modify time since the epoch - ctime inode change time (NOT creation time!) since the epoch - blksize preferred block size for file system I/O - blocks actual number of blocks allocated + 0 dev device number of filesystem + 1 ino inode number + 2 mode file mode (type and permissions) + 3 nlink number of (hard) links to the file + 4 uid numeric user ID of file's owner + 5 gid numeric group ID of file's owner + 6 rdev the device identifier (special files only) + 7 size total size of file, in bytes + 8 atime last access time since the epoch + 9 mtime last modify time since the epoch + 10 ctime inode change time (NOT creation time!) since the epoch + 11 blksize preferred block size for file system I/O + 12 blocks actual number of blocks allocated (The epoch was at 00:00 January 1, 1970 GMT.) @@ -3176,11 +3187,11 @@ Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of doing many pattern matches on the string before it is next modified. This may or may not save time, depending on the nature and number of patterns you are searching on, and on the distribution of character -frequencies in the string to be searched--you probably want to compare +frequencies in the string to be searched -- you probably want to compare run times with and without it to see which runs faster. Those loops which scan for many short constant strings (including the constant parts of more complex patterns) will benefit most. You may have only -one study active at a time--if you study a different scalar the first +one study active at a time -- if you study a different scalar the first is "unstudied". (The way study works is this: a linked list of every character in the string to be searched is made, so we know, for example, where all the 'k' characters are. From each search string, @@ -3264,7 +3275,7 @@ Returns 1 for success, 0 otherwise. On systems that don't support symbolic links, produces a fatal error at run time. To check for that, use eval: - $symlink_exists = (eval 'symlink("","");', $@ eq ''); + $symlink_exists = (eval {symlink("","")};, $@ eq ''); =item syscall LIST @@ -3334,41 +3345,41 @@ first, and the parent process waits for the child process to complete. Note that argument processing varies depending on the number of arguments. The return value is the exit status of the program as returned by the wait() call. To get the actual exit value divide by -256. See also L</exec>. This is I<NOT> what you want to use to capture -the output from a command, for that you should use merely back-ticks or +256. See also L</exec>. This is I<NOT> what you want to use to capture +the output from a command, for that you should use merely backticks or qx//, as described in L<perlop/"`STRING`">. -Because system() and back-ticks block SIGINT and SIGQUIT, killing the +Because system() and backticks block SIGINT and SIGQUIT, killing the program they're running doesn't actually interrupt your program. @args = ("command", "arg1", "arg2"); - system(@args) == 0 - or die "system @args failed: $?" + system(@args) == 0 + or die "system @args failed: $?" Here's a more elaborate example of analysing the return value from -system() on a UNIX system to check for all possibilities, including for -signals and coredumps. +system() on a Unix system to check for all possibilities, including for +signals and core dumps. $rc = 0xffff & system @args; printf "system(%s) returned %#04x: ", "@args", $rc; if ($rc == 0) { print "ran with normal exit\n"; - } + } elsif ($rc == 0xff00) { print "command failed: $!\n"; - } + } elsif ($rc > 0x80) { $rc >>= 8; print "ran with non-zero exit status $rc\n"; - } + } else { print "ran with "; if ($rc & 0x80) { $rc &= ~0x80; - print "coredump from "; - } + print "core dump from "; + } print "signal $rc\n" - } + } $ok = ($rc != 0); =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET @@ -3384,7 +3395,7 @@ is available will be written. An OFFSET may be specified to write the data from some part of the string other than the beginning. A negative OFFSET specifies writing -from that many bytes counting backwards from the end of the string. +that many bytes counting backwards from the end of the string. =item tell FILEHANDLE @@ -3448,7 +3459,7 @@ A class implementing a scalar should have the following methods: TIESCALAR classname, LIST DESTROY this - FETCH this, + FETCH this, STORE this, value Unlike dbmopen(), the tie() function will not use or require a module @@ -3478,7 +3489,7 @@ seconds, for this process and the children of this process. =item tr/// -The translation operator. See L<perlop>. +The translation operator. Same as y///. See L<perlop>. =item truncate FILEHANDLE,LENGTH @@ -3490,7 +3501,7 @@ on your system. =item uc EXPR -=item uc +=item uc Returns an uppercased version of EXPR. This is the internal function implementing the \U escape in double-quoted strings. @@ -3500,7 +3511,7 @@ If EXPR is omitted, uses $_. =item ucfirst EXPR -=item ucfirst +=item ucfirst Returns the value of EXPR with the first character uppercased. This is the internal function implementing the \u escape in double-quoted strings. @@ -3521,8 +3532,8 @@ digits. See also L<oct>, if all you have is a string. =item undef -Undefines the value of EXPR, which must be an lvalue. Use on only a -scalar value, an entire array or hash, or a subroutine name (using +Undefines the value of EXPR, which must be an lvalue. Use only on a +scalar value, an entire array, an entire hash, or a subroutine name (using "&"). (Using undef() will probably not do what you expect on most predefined variables or DBM list values, so don't do that.) Always returns the undefined value. You can omit the EXPR, in which case @@ -3535,13 +3546,13 @@ pass as a parameter. Examples: undef @ary; undef %hash; undef &mysub; - return (wantarray ? () : undef) if $they_blew_it; + return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it; select undef, undef, undef, 0.25; ($a, $b, undef, $c) = &foo; # Ignore third value returned =item unlink LIST -=item unlink +=item unlink Deletes a list of files. Returns the number of files successfully deleted. @@ -3618,7 +3629,7 @@ package. It is exactly equivalent to BEGIN { require Module; import Module LIST; } -except that Module I<must> be a bare word. +except that Module I<must> be a bareword. If the first argument to C<use> is a number, it is treated as a version number instead of a module name. If the version of the Perl interpreter @@ -3746,9 +3757,12 @@ not been harvested by the Perl script yet.) Returns TRUE if the context of the currently executing subroutine is looking for a list value. Returns FALSE if the context is looking -for a scalar. +for a scalar. Returns the undefined value if the context is looking +for no value (void context). - return wantarray ? () : undef; + return unless defined wantarray; # don't bother doing more + my @a = complex_calculation(); + return wantarray ? @a : "@a"; =item warn LIST @@ -3791,9 +3805,9 @@ examples. =item write -Writes a formatted record (possibly multi-line) to the specified file, +Writes a formatted record (possibly multiline) to the specified file, using the format associated with that file. By default the format for -a file is the one having the same name is the filehandle, but the +a file is the one having the same name as the filehandle, but the format for the current output channel (see the select() function) may be set explicitly by assigning the name of the format to the C<$~> variable. @@ -3817,6 +3831,6 @@ Note that write is I<NOT> the opposite of read. Unfortunately. =item y/// -The translation operator. See L<perlop>. +The translation operator. Same as tr///. See L<perlop>. =back diff --git a/pod/perlguts.pod b/pod/perlguts.pod index ff3d6cdc5d..c14e17d0bd 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -28,7 +28,7 @@ guaranteed to be large enough to hold a pointer (as well as an integer). Perl also uses two special typedefs, I32 and I16, which will always be at least 32-bits and 16-bits long, respectively. -=head2 Working with SV's +=head2 Working with SVs An SV can be created and loaded with one command. There are four types of values that can be loaded: an integer value (IV), a double (NV), a string, @@ -56,7 +56,7 @@ argument to C<newSVpv>. Be warned, though, that Perl will determine the string's length by using C<strlen>, which depends on the string terminating with a NUL character. -All SV's that will contain strings should, but need not, be terminated +All SVs that will contain strings should, but need not, be terminated with a NUL character. If it is not NUL-terminated there is a risk of core dumps and corruptions from code which passes the string to C functions or system calls which expect a NUL-terminated string. @@ -77,7 +77,7 @@ In the C<SvPV> macro, the length of the string returned is placed into the variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not care what the length of the data is, use the global variable C<na>. Remember, however, that Perl allows arbitrary strings of data that may both contain -NUL's and might not be terminated by a NUL. +NULs and might not be terminated by a NUL. If you want to know if the scalar value is TRUE, you can use: @@ -184,21 +184,21 @@ stored in your SV. The "p" stands for private. In general, though, it's best to use the C<Sv*V> macros. -=head2 Working with AV's +=head2 Working with AVs There are two ways to create and load an AV. The first method creates an empty AV: AV* newAV(); -The second method both creates the AV and initially populates it with SV's: +The second method both creates the AV and initially populates it with SVs: AV* av_make(I32 num, SV **ptr); The second argument points to an array containing C<num> C<SV*>'s. Once the -AV has been created, the SV's can be destroyed, if so desired. +AV has been created, the SVs can be destroyed, if so desired. -Once the AV has been created, the following operations are possible on AV's: +Once the AV has been created, the following operations are possible on AVs: void av_push(AV*, SV*); SV* av_pop(AV*); @@ -242,13 +242,13 @@ by using the following: This returns NULL if the variable does not exist. -=head2 Working with HV's +=head2 Working with HVs To create an HV, you use the following routine: HV* newHV(); -Once the HV has been created, the following operations are possible on HV's: +Once the HV has been created, the following operations are possible on HVs: SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash); SV** hv_fetch(HV*, char* key, U32 klen, I32 lval); @@ -256,7 +256,7 @@ Once the HV has been created, the following operations are possible on HV's: The C<klen> parameter is the length of the key being passed in (Note that you cannot pass 0 in as a value of C<klen> to tell Perl to measure the length of the key). The C<val> argument contains the SV pointer to the -scalar being stored, and C<hash> is the pre-computed hash value (zero if +scalar being stored, and C<hash> is the precomputed hash value (zero if you want C<hv_store> to calculate it for you). The C<lval> parameter indicates whether this fetch is actually a part of a store operation, in which case a new undefined value will be added to the HV with the supplied @@ -468,7 +468,7 @@ There are additional macros whose values may be bitwise OR'ed with the C<TRUE> argument to enable certain extra features. Those bits are: GV_ADDMULTI Marks the variable as multiply defined, thus preventing the - "Indentifier <varname> used only once: possible typo" warning. + "Name <varname> used only once: possible typo" warning. GV_ADDWARN Issues the warning "Had to create <varname> unexpectedly" if the variable did not exist before the function was called. @@ -477,8 +477,8 @@ package. =head2 Reference Counts and Mortality -Perl uses an reference count-driven garbage collection mechanism. SV's, -AV's, or HV's (xV for short in the following) start their life with a +Perl uses an reference count-driven garbage collection mechanism. SVs, +AVs, or HVs (xV for short in the following) start their life with a reference count of 1. If the reference count of an xV ever drops to 0, then it will be destroyed and its memory made available for reuse. @@ -514,11 +514,11 @@ the reference count of the SV will go to zero and it will be destroyed, stopping any memory leak. There are some convenience functions available that can help with the -destruction of xV's. These functions introduce the concept of "mortality". +destruction of xVs. These functions introduce the concept of "mortality". An xV that is mortal has had its reference count marked to be decremented, but not actually decremented, until "a short time later". Generally the term "short time later" means a single Perl statement, such as a call to -an XSUB function. The actual determinant for when mortal xV's have their +an XSUB function. The actual determinant for when mortal xVs have their reference count decremented depends on two macros, SAVETMPS and FREETMPS. See L<perlcall> and L<perlxs> for more details on these macros. @@ -540,7 +540,7 @@ The first call creates a mortal SV, the second converts an existing SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the third creates a mortal copy of an existing SV. -The mortal routines are not just for SV's -- AV's and HV's can be +The mortal routines are not just for SVs -- AVs and HVs can be made mortal by passing their address (type-casted to C<SV*>) to the C<sv_2mortal> or C<sv_mortalcopy> routines. @@ -601,7 +601,7 @@ as any other SV. For more information on references and blessings, consult L<perlref>. -=head2 Double-Typed SV's +=head2 Double-Typed SVs Scalar variables normally contain only one type of value, an integer, double, pointer, or reference. Perl will automatically convert the @@ -679,9 +679,9 @@ entry of the same type of magic is deleted. Note that this can be overridden, and multiple instances of the same type of magic can be associated with an SV. -The C<name> and C<namlem> arguments are used to associate a string with -the magic, typically the name of a variable. C<namlem> is stored in the -C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd +The C<name> and C<namlen> arguments are used to associate a string with +the magic, typically the name of a variable. C<namlen> is stored in the +C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd copy of the name is stored in C<mg_ptr> field. The sv_magic function uses C<how> to determine which, if any, predefined @@ -800,7 +800,7 @@ at the top of the private data area and check that. This routine returns a pointer to the C<MAGIC> structure stored in the SV. If the SV does not have that magical feature, C<NULL> is returned. Also, -if the SV is not of type SVt_PVMG, Perl may core-dump. +if the SV is not of type SVt_PVMG, Perl may core dump. int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen); @@ -836,7 +836,7 @@ where C<sp> is the stack pointer, and C<num> is the number of elements the stack should be extended by. Now that there is room on the stack, values can be pushed on it using the -macros to push IV's, doubles, strings, and SV pointers respectively: +macros to push IVs, doubles, strings, and SV pointers respectively: PUSHi(IV) PUSHn(double) @@ -979,20 +979,20 @@ others, which use it via C<(X)PUSH[pni]>. =head2 Scratchpads -The question remains on when the SV's which are I<target>s for opcodes +The question remains on when the SVs which are I<target>s for opcodes are created. The answer is that they are created when the current unit -- a subroutine or a file (for opcodes for statements outside of subroutines) -- is compiled. During this time a special anonymous Perl array is created, which is called a scratchpad for the current unit. -A scratchpad keeps SV's which are lexicals for the current unit and are +A scratchpad keeps SVs which are lexicals for the current unit and are targets for opcodes. One can deduce that an SV lives on a scratchpad by looking on its flags: lexicals have C<SVs_PADMY> set, and I<target>s have C<SVs_PADTMP> set. -The correspondence between OP's and I<target>s is not 1-to-1. Different -OP's in the compile tree of the unit can use the same target, if this +The correspondence between OPs and I<target>s is not 1-to-1. Different +OPs in the compile tree of the unit can use the same target, if this would not conflict with the expected life of the temporary. =head2 Scratchpads and recursion @@ -1343,7 +1343,7 @@ L<perlcall>. =item G_ARRAY -Used to indicate array context. See C<GIMME> and L<perlcall>. +Used to indicate array context. See C<GIMME_V>, C<GIMME> and L<perlcall>. =item G_DISCARD @@ -1356,8 +1356,14 @@ Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>. =item GIMME -The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_SCALAR> or -C<G_ARRAY> for scalar or array context. +A backward-compatible version of C<GIMME_V> which can only return +C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>. + +=item GIMME_V + +The XSUB-writer's equivalent to Perl's C<wantarray>. Returns +C<G_VOID>, C<G_SCALAR> or C<G_ARRAY> for void, scalar or array +context, respectively. =item G_NOARGS @@ -1365,7 +1371,11 @@ Indicates that no arguments are being sent to a callback. See L<perlcall>. =item G_SCALAR -Used to indicate scalar context. See C<GIMME> and L<perlcall>. +Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and L<perlcall>. + +=item G_VOID + +Used to indicate void context. See C<GIMME_V> and L<perlcall>. =item gv_fetchmeth @@ -1526,7 +1536,7 @@ returned. Deletes a key/value pair in the hash. The value SV is removed from the hash and returned to the caller. The C<flags> value will normally be zero; if set -to G_DISCARD then null will be returned. C<hash> can be a valid pre-computed +to G_DISCARD then null will be returned. C<hash> can be a valid precomputed hash value, or 0 to ask for it to be computed. SV* hv_delete_ent _((HV* tb, SV* key, I32 flags, U32 hash)); @@ -1541,7 +1551,7 @@ C<klen> is the length of the key. =item hv_exists_ent Returns a boolean indicating whether the specified hash key exists. C<hash> -can be a valid pre-computed hash value, or 0 to ask for it to be computed. +can be a valid precomputed hash value, or 0 to ask for it to be computed. bool hv_exists_ent _((HV* tb, SV* key, U32 hash)); @@ -1557,7 +1567,7 @@ dereferencing it to a C<SV*>. =item hv_fetch_ent Returns the hash entry which corresponds to the specified key in the hash. -C<hash> must be a valid pre-computed hash number for the given C<key>, or +C<hash> must be a valid precomputed hash number for the given C<key>, or 0 if you want the function to compute it. IF C<lval> is set then the fetch will be part of a store. Make sure the return value is non-null before accessing it. The return value when C<tb> is a tied hash @@ -1629,7 +1639,7 @@ Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>. =item hv_store Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is -the length of the key. The C<hash> parameter is the pre-computed hash +the length of the key. The C<hash> parameter is the precomputed hash value; if it is zero then Perl will compute it. The return value will be null if the operation failed, otherwise it can be dereferenced to get the original C<SV*>. @@ -1639,7 +1649,7 @@ original C<SV*>. =item hv_store_ent Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash> -parameter is the pre-computed hash value; if it is zero then Perl will +parameter is the precomputed hash value; if it is zero then Perl will compute it. The return value is the new hash entry so created. It will be null if the operation failed or if the entry was stored in a tied hash. Otherwise the contents of the return value can be accessed using the @@ -2118,7 +2128,7 @@ C<SPAGAIN>. =item SPAGAIN -Re-fetch the stack pointer. Used after a callback. See L<perlcall>. +Refetch the stack pointer. Used after a callback. See L<perlcall>. SPAGAIN; @@ -2910,4 +2920,4 @@ API Listing by Dean Roehrich <F<roehrich@cray.com>>. =head1 DATE -Version 31.3: 1997/3/14 +Version 31.4: 1997/3/30 diff --git a/pod/perlipc.pod b/pod/perlipc.pod index ab4a912bc6..7dc1c7a9b5 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -16,13 +16,13 @@ with an argument which is the name of the signal that triggered it. A signal may be generated intentionally from a particular keyboard sequence like control-C or control-Z, sent to you from another process, or triggered automatically by the kernel when special events transpire, like -a child process exiting, your process running out of stack space, or +a child process exiting, your process running out of stack space, or hitting file size limit. For example, to trap an interrupt signal, set up a handler like this. Notice how all we do is set a global variable and then raise an exception. That's because on most systems libraries are not -re-entrant, so calling any print() functions (or even anything that needs to +reentrant, so calling any print() functions (or even anything that needs to malloc(3) more memory) could in theory trigger a memory fault and subsequent core dump. @@ -30,7 +30,7 @@ and subsequent core dump. my $signame = shift; $shucks++; die "Somebody sent me a SIG$signame"; - } + } $SIG{INT} = 'catch_zap'; # could fail in modules $SIG{INT} = \&catch_zap; # best strategy @@ -45,14 +45,14 @@ indexed by name to get the number: $signo{$name} = $i; $signame[$i] = $name; $i++; - } + } So to check whether signal 17 and SIGALRM were the same, do just this: print "signal #17 = $signame[17]\n"; - if ($signo{ALRM}) { + if ($signo{ALRM}) { print "SIGALRM is $signo{ALRM}\n"; - } + } You may also choose to assign the strings C<'IGNORE'> or C<'DEFAULT'> as the handler, in which case Perl will try to discard the signal or do the @@ -65,10 +65,10 @@ values are "inherited" by functions called from within that block.) sub precious { local $SIG{INT} = 'IGNORE'; &more_functions; - } + } sub more_functions { # interrupts still ignored, for now... - } + } Sending a signal to a negative process ID means that you send the signal to the entire Unix process-group. This code send a hang-up signal to all @@ -83,11 +83,11 @@ itself: Another interesting signal to send is signal number zero. This doesn't actually affect another process, but instead checks whether it's alive -or has changed its UID. +or has changed its UID. unless (kill 0 => $kid_pid) { warn "something wicked happened to $kid_pid"; - } + } You might also want to employ anonymous functions for simple signal handlers: @@ -95,18 +95,18 @@ handlers: $SIG{INT} = sub { die "\nOutta here!\n" }; But that will be problematic for the more complicated handlers that need -to re-install themselves. Because Perl's signal mechanism is currently +to reinstall themselves. Because Perl's signal mechanism is currently based on the signal(3) function from the C library, you may sometimes be so misfortunate as to run on systems where that function is "broken", that is, it behaves in the old unreliable SysV way rather than the newer, more reasonable BSD and POSIX fashion. So you'll see defensive people writing signal handlers like this: - sub REAPER { + sub REAPER { $waitedpid = wait; # loathe sysV: it makes us not only reinstate # the handler, but place it after the wait - $SIG{CHLD} = \&REAPER; + $SIG{CHLD} = \&REAPER; } $SIG{CHLD} = \&REAPER; # now do something that forks... @@ -114,11 +114,11 @@ signal handlers like this: or even the more elaborate: use POSIX ":sys_wait_h"; - sub REAPER { + sub REAPER { my $child; while ($child = waitpid(-1,WNOHANG)) { $Kid_Status{$child} = $?; - } + } $SIG{CHLD} = \&REAPER; # still loathe sysV } $SIG{CHLD} = \&REAPER; @@ -134,11 +134,11 @@ using longjmp() or throw() in other languages. Here's an example: - eval { + eval { local $SIG{ALRM} = sub { die "alarm clock restart" }; - alarm 10; + alarm 10; flock(FH, 2); # blocking write lock - alarm 0; + alarm 0; }; if ($@ and $@ !~ /alarm clock restart/) { die } @@ -151,7 +151,7 @@ examples in it. A named pipe (often referred to as a FIFO) is an old Unix IPC mechanism for processes communicating on the same machine. It works -just like a regular, connected anonymous pipes, except that the +just like a regular, connected anonymous pipes, except that the processes rendezvous using a filename and don't have to be related. To create a named pipe, use the Unix command mknod(1) or on some @@ -160,16 +160,16 @@ systems, mkfifo(1). These may not be in your normal path. # system return val is backwards, so && not || # $ENV{PATH} .= ":/etc:/usr/etc"; - if ( system('mknod', $path, 'p') + if ( system('mknod', $path, 'p') && system('mkfifo', $path) ) { die "mk{nod,fifo} $path failed; - } + } A fifo is convenient when you want to connect a process to an unrelated one. When you open a fifo, the program will block until there's something -on the other end. +on the other end. For example, let's say you'd like to have your F<.signature> file be a named pipe that has a Perl program on the other end. Now every time any @@ -185,9 +185,9 @@ to find out whether anyone (or anything) has accidentally removed our fifo. while (1) { unless (-p $FIFO) { unlink $FIFO; - system('mknod', $FIFO, 'p') + system('mknod', $FIFO, 'p') && die "can't mknod $FIFO: $!"; - } + } # next line blocks until there's a reader open (FIFO, "> $FIFO") || die "can't write $FIFO: $!"; @@ -204,7 +204,7 @@ communication by either appending or prepending a pipe symbol to the second argument to open(). Here's how to start something up in a child process you intend to write to: - open(SPOOLER, "| cat -v | lpr -h 2>/dev/null") + open(SPOOLER, "| cat -v | lpr -h 2>/dev/null") || die "can't fork: $!"; local $SIG{PIPE} = sub { die "spooler pipe broke" }; print SPOOLER "stuff\n"; @@ -217,7 +217,7 @@ And here's how to start up a child process you intend to read from: while (<STATUS>) { next if /^(tcp|udp)/; print; - } + } close STATUS || die "bad netstat: $! $?"; If one can be sure that a particular program is a Perl script that is @@ -231,7 +231,7 @@ read from the file F<f1>, the process F<cmd1>, standard input (F<tmpfile> in this case), the F<f2> file, the F<cmd2> command, and finally the F<f3> file. Pretty nifty, eh? -You might notice that you could use back-ticks for much the +You might notice that you could use backticks for much the same effect as opening a pipe for reading: print grep { !/^(tcp|udp)/ } `netstat -an 2>&1`; @@ -325,13 +325,13 @@ you opened whatever your kid writes to his STDOUT. use English; my $sleep_count = 0; - do { + do { $pid = open(KID_TO_WRITE, "|-"); unless (defined $pid) { warn "cannot fork: $!"; die "bailing out" if $sleep_count++ > 6; sleep 10; - } + } } until defined $pid; if ($pid) { # parent @@ -339,21 +339,21 @@ you opened whatever your kid writes to his STDOUT. close(KID_TO_WRITE) || warn "kid exited $?"; } else { # child ($EUID, $EGID) = ($UID, $GID); # suid progs only - open (FILE, "> /safe/file") + open (FILE, "> /safe/file") || die "can't open /safe/file: $!"; while (<STDIN>) { print FILE; # child's STDIN is parent's KID - } + } exit; # don't forget this - } + } Another common use for this construct is when you need to execute something without the shell's interference. With system(), it's -straightforward, but you can't use a pipe open or back-ticks safely. +straightforward, but you can't use a pipe open or backticks safely. That's because there's no way to stop the shell from getting its hands on your arguments. Instead, use lower-level control to call exec() directly. -Here's a safe back-tick or pipe open for read: +Here's a safe backtick or pipe open for read: # add error processing as above $pid = open(KID_TO_READ, "-|"); @@ -361,7 +361,7 @@ Here's a safe back-tick or pipe open for read: if ($pid) { # parent while (<KID_TO_READ>) { # do something interesting - } + } close(KID_TO_READ) || warn "kid exited $?"; } else { # child @@ -369,7 +369,7 @@ Here's a safe back-tick or pipe open for read: exec($program, @options, @args) || die "can't exec program: $!"; # NOTREACHED - } + } And here's a safe pipe open for writing: @@ -381,7 +381,7 @@ And here's a safe pipe open for writing: if ($pid) { # parent for (@data) { print KID_TO_WRITE; - } + } close(KID_TO_WRITE) || warn "kid exited $?"; } else { # child @@ -389,11 +389,11 @@ And here's a safe pipe open for writing: exec($program, @options, @args) || die "can't exec program: $!"; # NOTREACHED - } + } Note that these operations are full Unix forks, which means they may not be correctly implemented on alien systems. Additionally, these are not true -multi-threading. If you'd like to learn more about threading, see the +multithreading. If you'd like to learn more about threading, see the F<modules> file mentioned below in the SEE ALSO section. =head2 Bidirectional Communication @@ -404,7 +404,7 @@ doesn't actually work: open(PROG_FOR_READING_AND_WRITING, "| some program |") -and if you forget to use the B<-w> flag, then you'll miss out +and if you forget to use the B<-w> flag, then you'll miss out entirely on the diagnostic message: Can't do bidirectional pipe at -e line 1. @@ -435,13 +435,13 @@ The problem with this is that Unix buffering is really going to ruin your day. Even though your C<Writer> filehandle is auto-flushed, and the process on the other end will get your data in a timely manner, you can't usually do anything to force it to give it back to you -in a similarly quick fashion. In this case, we could, because we +in a similarly quick fashion. In this case, we could, because we gave I<cat> a B<-u> flag to make it unbuffered. But very few Unix commands are designed to operate over pipes, so this seldom works -unless you yourself wrote the program on the other end of the +unless you yourself wrote the program on the other end of the double-ended pipe. -A solution to this is the non-standard F<Comm.pl> library. It uses +A solution to this is the nonstandard F<Comm.pl> library. It uses pseudo-ttys to make your program behave more reasonably: require 'Comm.pl'; @@ -452,8 +452,8 @@ pseudo-ttys to make your program behave more reasonably: } This way you don't have to have control over the source code of the -program you're using. The F<Comm> library also has expect() -and interact() functions. Find the library (and we hope its +program you're using. The F<Comm> library also has expect() +and interact() functions. Find the library (and we hope its successor F<IPC::Chat>) at your nearest CPAN archive as detailed in the SEE ALSO section below. @@ -510,16 +510,16 @@ Here's a sample TCP client using Internet-domain sockets: $proto = getprotobyname('tcp'); socket(SOCK, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; connect(SOCK, $paddr) || die "connect: $!"; - while ($line = <SOCK>) { + while (defined($line = <SOCK>)) { print $line; - } + } close (SOCK) || die "close: $!"; exit; And here's a corresponding server to go along with it. We'll leave the address as INADDR_ANY so that the kernel can choose -the appropriate interface on multi-homed hosts. If you want sit +the appropriate interface on multihomed hosts. If you want sit on a particular interface (like the external side of a gateway or firewall machine), you should fill this in with your real address instead. @@ -531,14 +531,14 @@ instead. use Socket; use Carp; - sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } + sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } my $port = shift || 2345; my $proto = getprotobyname('tcp'); $port = $1 if $port =~ /(\d+)/; # untaint port number socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; - setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, + setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1)) || die "setsockopt: $!"; bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!"; listen(Server,SOMAXCONN) || die "listen: $!"; @@ -553,16 +553,16 @@ instead. my($port,$iaddr) = sockaddr_in($paddr); my $name = gethostbyaddr($iaddr,AF_INET); - logmsg "connection from $name [", - inet_ntoa($iaddr), "] + logmsg "connection from $name [", + inet_ntoa($iaddr), "] at port $port"; - print Client "Hello there, $name, it's now ", + print Client "Hello there, $name, it's now ", scalar localtime, "\n"; - } + } -And here's a multi-threaded version. It's multi-threaded in that -like most typical servers, it spawns (forks) a slave server to +And here's a multithreaded version. It's multithreaded in that +like most typical servers, it spawns (forks) a slave server to handle the client request so that the master server can quickly go back to service a new client. @@ -574,14 +574,14 @@ go back to service a new client. use Carp; sub spawn; # forward declaration - sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } + sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } my $port = shift || 2345; my $proto = getprotobyname('tcp'); $port = $1 if $port =~ /(\d+)/; # untaint port number - + socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; - setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, + setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1)) || die "setsockopt: $!"; bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!"; listen(Server,SOMAXCONN) || die "listen: $!"; @@ -591,7 +591,7 @@ go back to service a new client. my $waitedpid = 0; my $paddr; - sub REAPER { + sub REAPER { $waitedpid = wait; $SIG{CHLD} = \&REAPER; # loathe sysV logmsg "reaped $waitedpid" . ($? ? " with exit $?" : ''); @@ -599,30 +599,30 @@ go back to service a new client. $SIG{CHLD} = \&REAPER; - for ( $waitedpid = 0; - ($paddr = accept(Client,Server)) || $waitedpid; - $waitedpid = 0, close Client) + for ( $waitedpid = 0; + ($paddr = accept(Client,Server)) || $waitedpid; + $waitedpid = 0, close Client) { next if $waitedpid and not $paddr; my($port,$iaddr) = sockaddr_in($paddr); my $name = gethostbyaddr($iaddr,AF_INET); - logmsg "connection from $name [", - inet_ntoa($iaddr), "] + logmsg "connection from $name [", + inet_ntoa($iaddr), "] at port $port"; - spawn sub { + spawn sub { print "Hello there, $name, it's now ", scalar localtime, "\n"; - exec '/usr/games/fortune' + exec '/usr/games/fortune' or confess "can't exec fortune: $!"; }; - } + } sub spawn { my $coderef = shift; - unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') { + unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') { confess "usage: spawn CODEREF"; } @@ -640,7 +640,7 @@ go back to service a new client. open(STDOUT, ">&Client") || die "can't dup client to stdout"; ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr"; exit &$coderef(); - } + } This server takes the trouble to clone off a child version via fork() for each incoming request. That way it can handle many requests at once, @@ -666,11 +666,11 @@ differ from the system on which it's being run: use Socket; my $SECS_of_70_YEARS = 2208988800; - sub ctime { scalar localtime(shift) } + sub ctime { scalar localtime(shift) } - my $iaddr = gethostbyname('localhost'); - my $proto = getprotobyname('tcp'); - my $port = getservbyname('time', 'tcp'); + my $iaddr = gethostbyname('localhost'); + my $proto = getprotobyname('tcp'); + my $port = getservbyname('time', 'tcp'); my $paddr = sockaddr_in(0, $iaddr); my($host); @@ -695,7 +695,7 @@ differ from the system on which it's being run: That's fine for Internet-domain clients and servers, but what about local communications? While you can use the same setup, sometimes you don't want to. Unix-domain sockets are local to the current host, and are often -used internally to implement pipes. Unlike Internet domain sockets, UNIX +used internally to implement pipes. Unlike Internet domain sockets, Unix domain sockets can show up in the file system with an ls(1) listing. $ ls -l /dev/log @@ -705,7 +705,7 @@ You can test for these with Perl's B<-S> file test: unless ( -S '/dev/log' ) { die "something's wicked with the print system"; - } + } Here's a sample Unix-domain client: @@ -718,12 +718,12 @@ Here's a sample Unix-domain client: $rendezvous = shift || '/tmp/catsock'; socket(SOCK, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!"; connect(SOCK, sockaddr_un($rendezvous)) || die "connect: $!"; - while ($line = <SOCK>) { + while (defined($line = <SOCK>)) { print $line; - } + } exit; -And here's a corresponding server. +And here's a corresponding server. #!/usr/bin/perl -Tw require 5.002; @@ -746,17 +746,17 @@ And here's a corresponding server. $SIG{CHLD} = \&REAPER; - for ( $waitedpid = 0; - accept(Client,Server) || $waitedpid; - $waitedpid = 0, close Client) + for ( $waitedpid = 0; + accept(Client,Server) || $waitedpid; + $waitedpid = 0, close Client) { next if $waitedpid; logmsg "connection on $NAME"; - spawn sub { + spawn sub { print "Hello there, it's now ", scalar localtime, "\n"; exec '/usr/games/fortune' or die "can't exec fortune: $!"; }; - } + } As you see, it's remarkably similar to the Internet domain TCP server, so much so, in fact, that we've omitted several duplicate functions--spawn(), @@ -799,8 +799,8 @@ with TCP, you'd have to use a different socket handle for each host. use Socket; use Sys::Hostname; - my ( $count, $hisiaddr, $hispaddr, $histime, - $host, $iaddr, $paddr, $port, $proto, + my ( $count, $hisiaddr, $hispaddr, $histime, + $host, $iaddr, $paddr, $port, $proto, $rin, $rout, $rtime, $SECS_of_70_YEARS); $SECS_of_70_YEARS = 2208988800; @@ -847,7 +847,7 @@ several processes. That's because Perl would reallocate your string when you weren't wanting it to. -Here's a small example showing shared memory usage. +Here's a small example showing shared memory usage. $IPC_PRIVATE = 0; $IPC_RMID = 0; @@ -925,7 +925,7 @@ C<require "sys/ipc.ph">. Better yet, perhaps someone should create an C<IPC::SysV> module the way we have the C<Socket> module for normal client-server communications. -(... time passes) +(... time passes) Voila! Check out the IPC::SysV modules written by Jack Shirazi. You can find them at a CPAN store near you. @@ -961,8 +961,8 @@ signals and to stick with simple TCP and UDP socket operations; e.g., don't try to pass open file descriptors over a local UDP datagram socket if you want your code to stand a chance of being portable. -Because few vendors provide C libraries that are safely -re-entrant, the prudent programmer will do little else within +Because few vendors provide C libraries that are safely +reentrant, the prudent programmer will do little else within a handler beyond die() to raise an exception and longjmp(3) out. =head1 AUTHOR diff --git a/pod/perllocale.pod b/pod/perllocale.pod index 31ab40a58d..ca8518f8f8 100644 --- a/pod/perllocale.pod +++ b/pod/perllocale.pod @@ -46,7 +46,7 @@ B<Definitions for the locales which you use must be installed>. You, or your system administrator, must make sure that this is the case. The available locales, the location in which they are kept, and the manner in which they are installed, vary from system to system. Some systems -provide only a few, hard-wired, locales, and do not allow more to be +provide only a few, hardwired, locales, and do not allow more to be added; others allow you to add "canned" locales provided by the system supplier; still others allow you or the system administrator to define and add arbitrary locales. (You may have to ask your supplier to @@ -182,7 +182,7 @@ As the example shows, if the second argument is an empty string, the category's locale is returned to the default specified by the corresponding environment variables. Generally, this results in a return to the default which was in force when Perl started up: changes -to the environment made by the application after start-up may or may not +to the environment made by the application after startup may or may not be noticed, depending on the implementation of your system's C library. If the second argument does not correspond to a valid locale, the locale @@ -584,13 +584,13 @@ True/false results are never tainted. Three examples illustrate locale-dependent tainting. The first program, which ignores its locale, won't run: a value taken -directly from the command-line may not be used to name an output file +directly from the command line may not be used to name an output file when taint checks are enabled. #/usr/local/bin/perl -T # Run with taint checking - # Command-line sanity check omitted... + # Command line sanity check omitted... $tainted_output_file = shift; open(F, ">$tainted_output_file") @@ -598,7 +598,7 @@ when taint checks are enabled. The program can be made to run by "laundering" the tainted value through a regular expression: the second example - which still ignores locale -information - runs, creating the file named on its command-line +information - runs, creating the file named on its command line if it can. #/usr/local/bin/perl -T @@ -632,7 +632,7 @@ of a match involving C<\w> when C<use locale> is in effect. =item PERL_BADLANG A string that can suppress Perl's warning about failed locale settings -at start-up. Failure can occur if the locale support in the operating +at startup. Failure can occur if the locale support in the operating system is lacking (broken) is some way - or if you mistyped the name of a locale when you set up your environment. If this environment variable is absent, or has a value which does not evaluate to integer zero - that diff --git a/pod/perllol.pod b/pod/perllol.pod index f15b24384e..ac36364ae0 100644 --- a/pod/perllol.pod +++ b/pod/perllol.pod @@ -16,7 +16,7 @@ old array @LoL that you can get at with two subscripts, like C<$LoL[3][2]>. Her a declaration of the array: # assign to our array a list of list references - @LoL = ( + @LoL = ( [ "fred", "barney" ], [ "george", "jane", "elroy" ], [ "homer", "marge", "bart" ], @@ -39,10 +39,10 @@ but rather just a reference to it, you could do something more like this: print $ref_to_LoL->[2][2]; -Notice that the outer bracket type has changed, and so our access syntax +Notice that the outer bracket type has changed, and so our access syntax has also changed. That's because unlike C, in perl you can't freely -interchange arrays and references thereto. $ref_to_LoL is a reference to an -array, whereas @LoL is an array proper. Likewise, C<$LoL[2]> is not an +interchange arrays and references thereto. $ref_to_LoL is a reference to an +array, whereas @LoL is an array proper. Likewise, C<$LoL[2]> is not an array, but an array ref. So how come you can write these: $LoL[2][2] @@ -72,7 +72,7 @@ each line is a row and each word an element. If you're trying to develop an while (<>) { @tmp = split; push @LoL, [ @tmp ]; - } + } You might also have loaded that from a function: @@ -81,7 +81,7 @@ You might also have loaded that from a function: } Or you might have had a temporary variable sitting around with the -list in it. +list in it. for $i ( 1 .. 10 ) { @tmp = somefunc($i); @@ -93,8 +93,8 @@ constructor. That's because this will be very wrong: $LoL[$i] = @tmp; -You see, assigning a named list like that to a scalar just counts the -number of elements in @tmp, which probably isn't what you want. +You see, assigning a named list like that to a scalar just counts the +number of elements in @tmp, which probably isn't what you want. If you are running under C<use strict>, you'll have to add some declarations to make it happy: @@ -104,13 +104,13 @@ declarations to make it happy: while (<>) { @tmp = split; push @LoL, [ @tmp ]; - } + } Of course, you don't need the temporary array to have a name at all: while (<>) { push @LoL, [ split ]; - } + } You also don't have to use push(). You could just make a direct assignment if you knew where you wanted to put it: @@ -119,30 +119,30 @@ if you knew where you wanted to put it: for $i ( 0 .. 10 ) { $line = <>; $LoL[$i] = [ split ' ', $line ]; - } + } or even just my (@LoL, $i); for $i ( 0 .. 10 ) { $LoL[$i] = [ split ' ', <> ]; - } + } You should in general be leery of using potential list functions -in a scalar context without explicitly stating such. +in a scalar context without explicitly stating such. This would be clearer to the casual reader: my (@LoL, $i); for $i ( 0 .. 10 ) { $LoL[$i] = [ split ' ', scalar(<>) ]; - } + } If you wanted to have a $ref_to_LoL variable as a reference to an array, you'd have to do something like this: while (<>) { push @$ref_to_LoL, [ split ]; - } + } Actually, if you were using strict, you'd have to declare not only $ref_to_LoL as you had to declare @LoL, but you'd I<also> having to @@ -152,7 +152,7 @@ perl version 5.001m that's been fixed for the 5.002 release.) my $ref_to_LoL = []; while (<>) { push @$ref_to_LoL, [ split ]; - } + } Ok, now you can add new rows. What about adding new columns? If you're dealing with just matrices, it's often easiest to use simple assignment: @@ -165,9 +165,9 @@ dealing with just matrices, it's often easiest to use simple assignment: for $x ( 3, 7, 9 ) { $LoL[$x][20] += func2($x); - } + } -It doesn't matter whether those elements are already +It doesn't matter whether those elements are already there or not: it'll gladly create them for you, setting intervening elements to C<undef> as need be. @@ -186,7 +186,7 @@ to push() must be a real array, not just a reference to such. =head1 Access and Printing -Now it's time to print your data structure out. How +Now it's time to print your data structure out. How are you going to do that? Well, if you want only one of the elements, it's trivial: @@ -198,10 +198,10 @@ say print @LoL; # WRONG because you'll get just references listed, and perl will never -automatically dereference things for you. Instead, you have to +automatically dereference things for you. Instead, you have to roll yourself a loop or two. This prints the whole structure, using the shell-style for() construct to loop across the outer -set of subscripts. +set of subscripts. for $aref ( @LoL ) { print "\t [ @$aref ],\n"; @@ -221,7 +221,7 @@ or maybe even this. Notice the inner loop. } } -As you can see, it's getting a bit complicated. That's why +As you can see, it's getting a bit complicated. That's why sometimes is easier to take a temporary on your way through: for $i ( 0 .. $#LoL ) { @@ -254,10 +254,10 @@ Here's how to do one operation using a loop. We'll assume an @LoL variable as before. @part = (); - $x = 4; + $x = 4; for ($y = 7; $y < 13; $y++) { push @part, $LoL[$x][$y]; - } + } That same loop could be replaced with a slice operation: @@ -273,9 +273,9 @@ $x run from 4..8 and $y run from 7 to 12? Hmm... here's the simple way: for ($starty = $y = 7; $x <= 12; $y++) { $newLoL[$x - $startx][$y - $starty] = $LoL[$x][$y]; } - } + } -We can reduce some of the looping through slices +We can reduce some of the looping through slices for ($x = 4; $x <= 8; $x++) { push @newLoL, [ @{ $LoL[$x] } [ 7..12 ] ]; @@ -293,13 +293,13 @@ If I were you, I'd put that in a function: @newLoL = splice_2D( \@LoL, 4 => 8, 7 => 12 ); sub splice_2D { my $lrr = shift; # ref to list of list refs! - my ($x_lo, $x_hi, + my ($x_lo, $x_hi, $y_lo, $y_hi) = @_; - return map { - [ @{ $lrr->[$_] } [ $y_lo .. $y_hi ] ] + return map { + [ @{ $lrr->[$_] } [ $y_lo .. $y_hi ] ] } $x_lo .. $x_hi; - } + } =head1 SEE ALSO diff --git a/pod/perlmod.pod b/pod/perlmod.pod index 194cd1125d..29f9059220 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -41,7 +41,7 @@ package's symbol table. All other symbols are kept in package C<main>, including all of the punctuation variables like $_. In addition, the identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC, and SIG are forced to be in package C<main>, even when used for other purposes than -their built-in one. Note also that, if you have a package called C<m>, +their builtin one. Note also that, if you have a package called C<m>, C<s>, or C<y>, then you can't use the qualified form of an identifier because it will be interpreted instead as a pattern match, a substitution, or a translation. @@ -77,8 +77,8 @@ use the C<*name> typeglob notation. In fact, the following have the same effect, though the first is more efficient because it does the symbol table lookups at compile time: - local(*main::foo) = *main::bar; local($main::{'foo'}) = - $main::{'bar'}; + local(*main::foo) = *main::bar; + local($main::{'foo'}) = $main::{'bar'}; You can use this to print out all the variables in a package, for instance. Here is F<dumpvar.pl> from the Perl library: @@ -328,7 +328,7 @@ the rest of the current file. This will not work if you use C<require> instead of C<use>. With require you can get into this problem: require Cwd; # make Cwd:: accessible - $here = Cwd::getcwd(); + $here = Cwd::getcwd(); use Cwd; # import names from Cwd:: $here = getcwd(); @@ -381,7 +381,7 @@ F<.pl> files will all eventually be converted into standard modules, and the F<.ph> files made by B<h2ph> will probably end up as extension modules made by B<h2xs>. (Some F<.ph> values may already be available through the POSIX module.) The B<pl2pm> file in the distribution may help in your -conversion, but it's just a mechanical process and therefore far from +conversion, but it's just a mechanical process and therefore far from bulletproof. =head2 Pragmatic Modules @@ -398,7 +398,7 @@ which lasts until the end of that BLOCK. Unlike the pragmas that effect the C<$^H> hints variable, the C<use vars> and C<use subs> declarations are not BLOCK-scoped. They allow -you to pre-declare a variables or subroutines within a particular +you to predeclare a variables or subroutines within a particular I<file> rather than just a block. Such declarations are effective for the entire file for which they were declared. You cannot rescind them with C<no vars> or C<no subs>. @@ -430,7 +430,7 @@ manipulate @INC at compile time =item locale -use or ignore current locale for built-in operations (see L<perllocale>) +use or ignore current locale for builtin operations (see L<perllocale>) =item ops @@ -450,7 +450,7 @@ restrict unsafe constructs =item subs -pre-declare sub names +predeclare sub names =item vmsish @@ -458,7 +458,7 @@ adopt certain VMS-specific behaviors =item vars -pre-declare global variable names +predeclare global variable names =back @@ -556,7 +556,7 @@ determine libraries to use and how to use them =item ExtUtils::MM_OS2 -methods to override UN*X behaviour in ExtUtils::MakeMaker +methods to override Unix behaviour in ExtUtils::MakeMaker =item ExtUtils::MM_Unix @@ -564,7 +564,7 @@ methods used by ExtUtils::MakeMaker =item ExtUtils::MM_VMS -methods to override UN*X behaviour in ExtUtils::MakeMaker +methods to override Unix behaviour in ExtUtils::MakeMaker =item ExtUtils::MakeMaker @@ -616,7 +616,7 @@ create or remove a series of directories =item File::stat -by-name interface to Perl's built-in stat() functions +by-name interface to Perl's builtin stat() functions =item FileCache @@ -704,19 +704,19 @@ Hello, anybody home? =item Net::hostent -by-name interface to Perl's built-in gethost*() functions +by-name interface to Perl's builtin gethost*() functions =item Net::netent -by-name interface to Perl's built-in getnet*() functions +by-name interface to Perl's builtin getnet*() functions =item Net::protoent -by-name interface to Perl's built-in getproto*() functions +by-name interface to Perl's builtin getproto*() functions =item Net::servent -by-name interface to Perl's built-in getserv*() functions +by-name interface to Perl's builtin getserv*() functions =item Opcode @@ -768,7 +768,7 @@ try every conceivable way to get hostname =item Sys::Syslog -interface to the UNIX syslog(3) calls +interface to the Unix syslog(3) calls =item Term::Cap @@ -800,7 +800,7 @@ implementation of the Soundex Algorithm as described by Knuth =item Text::Tabs -expand and unexpand tabs per the unix expand(1) and unexpand(1) +expand and unexpand tabs per the Unix expand(1) and unexpand(1) =item Text::Wrap @@ -828,11 +828,11 @@ efficiently compute time from local and GMT time =item Time::gmtime -by-name interface to Perl's built-in gmtime() function +by-name interface to Perl's builtin gmtime() function =item Time::localtime -by-name interface to Perl's built-in localtime() function +by-name interface to Perl's builtin localtime() function =item Time::tm @@ -844,11 +844,11 @@ base class for ALL classes (blessed references) =item User::grent -by-name interface to Perl's built-in getgr*() functions +by-name interface to Perl's builtin getgr*() functions =item User::pwent -by-name interface to Perl's built-in getpw*() functions +by-name interface to Perl's builtin getpw*() functions =back @@ -862,7 +862,8 @@ your system man(1) command. If that fails, try the I<perldoc> program. =head2 Extension Modules -Extension modules are written in C (or a mix of Perl and C) and get +Extension modules are written in C (or a mix of Perl and C) and may be +statically linked or in general are dynamically loaded into Perl if and when you need them. Supported extension modules include the Socket, Fcntl, and POSIX modules. @@ -1213,7 +1214,7 @@ standards for naming modules and the interface to methods in those modules. To be portable each component of a module name should be limited to -11 characters. If it might be used on DOS then try to ensure each is +11 characters. If it might be used on MS-DOS then try to ensure each is unique in the first 8 characters. Nested modules make this easier. =item Have you got it right? @@ -1279,8 +1280,8 @@ How you choose to license your work is a personal decision. The general mechanism is to assert your Copyright and then make a declaration of how others may copy/use/modify your work. -Perl, for example, is supplied with two types of license: The GNU -GPL and The Artistic License (see the files README, Copying, and +Perl, for example, is supplied with two types of licence: The GNU +GPL and The Artistic Licence (see the files README, Copying, and Artistic). Larry has good reasons for NOT just using the GNU GPL. My personal recommendation, out of respect for Larry, Perl, and the diff --git a/pod/perlobj.pod b/pod/perlobj.pod index 07a71dc203..765b7ffab7 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -9,7 +9,7 @@ See L<perlref> for that. Second, if you still find the following reference work too complicated, a tutorial on object-oriented programming in Perl can be found in L<perltoot>. -If you're still with us, then +If you're still with us, then here are three very simple definitions that you should find reassuring. =over 4 @@ -44,11 +44,11 @@ constructor: package Critter; sub new { bless {} } -The C<{}> constructs a reference to an anonymous hash containing no +The C<{}> constructs a reference to an anonymous hash containing no key/value pairs. The bless() takes that reference and tells the object it references that it's now a Critter, and returns the reference. This is for convenience, because the referenced object itself knows that -it has been blessed, and its reference to it could have been returned +it has been blessed, and the reference to it could have been returned directly, like this: sub new { @@ -82,7 +82,7 @@ so that your constructors may be inherited: Or if you expect people to call not just C<CLASS-E<gt>new()> but also C<$obj-E<gt>new()>, then use something like this. The initialize() -method used will be of whatever $class we blessed the +method used will be of whatever $class we blessed the object into: sub new { @@ -102,7 +102,7 @@ be accessed only through the class's methods. A constructor may re-bless a referenced object currently belonging to another class, but then the new class is responsible for all cleanup later. The previous blessing is forgotten, as an object may belong -to only one class at a time. (Although of course it's free to +to only one class at a time. (Although of course it's free to inherit methods from many classes.) A clarification: Perl objects are blessed. References are not. Objects @@ -115,7 +115,7 @@ the following example: bless $a, BLAH; print "\$b is a ", ref($b), "\n"; -This reports $b as being a BLAH, so obviously bless() +This reports $b as being a BLAH, so obviously bless() operated on the object and not on the reference. =head2 A Class is Simply a Package @@ -130,7 +130,7 @@ package. This is how Perl implements inheritance. Each element of the @ISA array is just the name of another package that happens to be a class package. The classes are searched (depth first) for missing methods in the order that they occur in @ISA. The classes accessible -through @ISA are known as base classes of the current class. +through @ISA are known as base classes of the current class. If a missing method is found in one of the base classes, it is cached in the current class for efficiency. Changing @ISA or defining new @@ -159,7 +159,7 @@ Unlike say C++, Perl doesn't provide any special syntax for method definition. (It does provide a little syntax for method invocation though. More on that later.) A method expects its first argument to be the object or package it is being invoked on. There are just two -types of methods, which we'll call class and instance. +types of methods, which we'll call class and instance. (Sometimes you'll hear these called static and virtual, in honor of the two C++ method types they most closely resemble.) @@ -324,7 +324,7 @@ You do not need to C<use UNIVERSAL> in order to make these methods available to your program. This is necessary only if you wish to have C<isa> available as a plain subroutine in the current package. -=head2 Destructors +=head2 Destructors When the last reference to an object goes away, the object is automatically destroyed. (This may even be after you exit, if you've @@ -345,14 +345,14 @@ automatically when the current object is freed. An indirect object is limited to a name, a scalar variable, or a block, because it would have to do too much lookahead otherwise, just like any other postfix dereference in the language. The left side of -E<gt> is not so -limited, because it's an infix operator, not a postfix operator. +limited, because it's an infix operator, not a postfix operator. -That means that below, A and B are equivalent to each other, and C and D -are equivalent, but AB and CD are different: +That means that in the following, A and B are equivalent to each other, and +C and D are equivalent, but A/B and C/D are different: - A: method $obref->{"fieldname"} + A: method $obref->{"fieldname"} B: (method $obref)->{"fieldname"} - C: $obref->{"fieldname"}->method() + C: $obref->{"fieldname"}->method() D: method {$obref->{"fieldname"}} =head2 Summary @@ -372,12 +372,12 @@ probably won't matter. A more serious concern is that unreachable memory with a non-zero reference count will not normally get freed. Therefore, this is a bad -idea: +idea: { my $a; $a = \$a; - } + } Even thought $a I<should> go away, it can't. When building recursive data structures, you'll have to break the self-reference yourself explicitly @@ -391,7 +391,7 @@ node such as one might use in a sophisticated tree structure: $node->{LEFT} = $node->{RIGHT} = $node; $node->{DATA} = [ @_ ]; return bless $node => $class; - } + } If you create nodes like that, they (currently) won't go away unless you break their self reference yourself. (In other words, this is not to be @@ -403,10 +403,10 @@ When an interpreter thread finally shuts down (usually when your program exits), then a rather costly but complete mark-and-sweep style of garbage collection is performed, and everything allocated by that thread gets destroyed. This is essential to support Perl as an embedded or a -multi-threadable language. For example, this program demonstrates Perl's +multithreadable language. For example, this program demonstrates Perl's two-phased garbage collection: - #!/usr/bin/perl + #!/usr/bin/perl package Subtle; sub new { @@ -414,12 +414,12 @@ two-phased garbage collection: $test = \$test; warn "CREATING " . \$test; return bless \$test; - } + } sub DESTROY { my $self = shift; warn "DESTROYING $self"; - } + } package main; @@ -429,7 +429,7 @@ two-phased garbage collection: my $b = Subtle->new; $$a = 0; # break selfref warn "leaving block"; - } + } warn "just exited block"; warn "time to die..."; @@ -447,7 +447,7 @@ When run as F</tmp/test>, the following output is produced: DESTROYING Subtle=SCALAR(0x8e57c) during global destruction. Notice that "global destruction" bit there? That's the thread -garbage collector reaching the unreachable. +garbage collector reaching the unreachable. Objects are always destructed, even when regular refs aren't and in fact are destructed in a separate pass before ordinary refs just to try to @@ -462,8 +462,8 @@ at a future date. =head1 SEE ALSO -A kinder, gentler tutorial on object-oriented programming in Perl can +A kinder, gentler tutorial on object-oriented programming in Perl can be found in L<perltoot>. -You should also check out L<perlbot> for other object tricks, traps, and tips, +You should also check out L<perlbot> for other object tricks, traps, and tips, as well as L<perlmod> for some style guides on constructing both modules and classes. diff --git a/pod/perlop.pod b/pod/perlop.pod index a0756678d1..4817aaf5fe 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -8,7 +8,7 @@ Perl operators have the following associativity and precedence, listed from highest precedence to lowest. Note that all operators borrowed from C keep the same precedence relationship with each other, even where C's precedence is slightly screwy. (This makes learning -Perl easier for C folks.) With very few exceptions, these all +Perl easier for C folks.) With very few exceptions, these all operate on scalar values only, not array values. left terms and list operators (leftward) @@ -16,7 +16,7 @@ operate on scalar values only, not array values. nonassoc ++ -- right ** right ! ~ \ and unary + and - - left =~ !~ + left =~ !~ left * / % x left + - . left << >> @@ -42,7 +42,7 @@ In the following sections, these operators are covered in precedence order. =head2 Terms and List Operators (Leftward) -Any TERM is of highest precedence of Perl. These includes variables, +A TERM has the highest precedence in Perl. They includes variables, quote and quote-like operators, any expression in parentheses, and any function whose arguments are parenthesized. Actually, there aren't really functions in this sense, just list operators and unary @@ -56,7 +56,7 @@ just like a normal function call. In the absence of parentheses, the precedence of list operators such as C<print>, C<sort>, or C<chmod> is either very high or very low depending on -whether you look at the left side of operator or the right side of it. +whether you are looking at the left side or the right side of the operator. For example, in @ary = (1, 3, sort 4, 2); @@ -81,11 +81,11 @@ Also note that print ($foo & 255) + 1, "\n"; -probably doesn't do what you expect at first glance. See +probably doesn't do what you expect at first glance. See L<Named Unary Operators> for more discussion of this. Also parsed as terms are the C<do {}> and C<eval {}> constructs, as -well as subroutine and method calls, and the anonymous +well as subroutine and method calls, and the anonymous constructors C<[]> and C<{}>. See also L<Quote and Quote-like Operators> toward the end of this section, @@ -110,7 +110,7 @@ See L<perlobj>. increment or decrement the variable before returning the value, and if placed after, increment or decrement the variable after returning the value. -The auto-increment operator has a little extra built-in magic to it. If +The auto-increment operator has a little extra builtin magic to it. If you increment a variable that is numeric, or that has ever been used in a numeric context, you get a normal increment. If, however, the variable has been used in only string contexts since it was set, and @@ -179,7 +179,12 @@ Binary "*" multiplies two numbers. Binary "/" divides two numbers. -Binary "%" computes the modulus of the two numbers. +Binary "%" computes the modulus of two numbers. Given integer +operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is +C<$a> minus the largest multiple of C<$b> that is not greater than +C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the +smallest multiple of C<$b> that is not less than C<$a> (i.e. the +result will be less than or equal to zero). Binary "x" is the repetition operator. In a scalar context, it returns a string consisting of the left operand repeated the number of @@ -347,12 +352,12 @@ operators depending on the context. In a list context, it returns an array of values counting (by ones) from the left value to the right value. This is useful for writing C<for (1..10)> loops and for doing slice operations on arrays. Be aware that under the current implementation, -a temporary array is created, so you'll burn a lot of memory if you +a temporary array is created, so you'll burn a lot of memory if you write something like this: for (1 .. 1_000_000) { # code - } + } In a scalar context, ".." returns a boolean value. The operator is bistable, like a flip-flop, and emulates the line-range (comma) operator @@ -416,11 +421,11 @@ like an if-then-else. If the argument before the ? is true, the argument before the : is returned, otherwise the argument after the : is returned. For example: - printf "I have %d dog%s.\n", $n, + printf "I have %d dog%s.\n", $n, ($n == 1) ? '' : "s"; Scalar or list context propagates downward into the 2nd -or 3rd argument, whichever is selected. +or 3rd argument, whichever is selected. $a = $ok ? $b : $c; # get a scalar @a = $ok ? @b : @c; # get an array @@ -446,8 +451,8 @@ is equivalent to $a = $a + 2; although without duplicating any side effects that dereferencing the lvalue -might trigger, such as from tie(). Other assignment operators work similarly. -The following are recognized: +might trigger, such as from tie(). Other assignment operators work similarly. +The following are recognized: **= += *= &= <<= &&= -= /= |= >>= ||= @@ -533,12 +538,12 @@ Address-of operator. (But see the "\" operator for taking a reference.) =item unary * -Dereference-address operator. (Perl's prefix dereferencing +Dereference-address operator. (Perl's prefix dereferencing operators are typed: $, @, %, and &.) =item (TYPE) -Type casting operator. +Type casting operator. =back @@ -550,7 +555,7 @@ 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 +the same character fore and aft, but the 4 sorts of brackets (round, angle, square, curly) will all nest. Customary Generic Meaning Interpolates @@ -706,7 +711,7 @@ beginning. Examples: # scalar context $/ = ""; $* = 1; # $* deprecated in modern perls - while ($paragraph = <>) { + while (defined($paragraph = <>)) { while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) { $sentences++; } @@ -792,7 +797,7 @@ A double-quoted, interpolated string. A string which is interpolated and then executed as a system command. The collected standard output of the command is returned. In scalar -context, it comes back as a single (potentially multi-line) string. +context, it comes back as a single (potentially multiline) string. In list context, returns a list of lines (however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR). @@ -847,7 +852,7 @@ Options are: Any non-alphanumeric, non-whitespace delimiter may replace the slashes. If single quotes are used, no interpretation is done on the replacement string (the C</e> modifier overrides this, however). Unlike -Perl 4, Perl 5 treats back-ticks as normal delimiters; the replacement +Perl 4, Perl 5 treats backticks as normal delimiters; the replacement text is not evaluated as a command. If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own pair of quotes, which may or may not be bracketing quotes, e.g., @@ -892,7 +897,7 @@ Examples: s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields -Note the use of $ instead of \ in the last example. Unlike +Note the use of $ instead of \ in the last example. Unlike B<sed>, we use the \E<lt>I<digit>E<gt> form in only the left hand side. Anywhere else it's $E<lt>I<digit>E<gt>. @@ -915,12 +920,12 @@ Translates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced or deleted. If no string is specified via the =~ or !~ operator, the $_ string is translated. (The -string specified with =~ must be a scalar variable, an array element, -or an assignment to one of those, i.e., an lvalue.) For B<sed> devotees, -C<y> is provided as a synonym for C<tr>. If the SEARCHLIST is -delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of -quotes, which may or may not be bracketing quotes, e.g., C<tr[A-Z][a-z]> -or C<tr(+-*/)/ABCD/>. +string specified with =~ must be a scalar variable, an array element, a +hash element, or an assignment to one of those, i.e., an lvalue.) +For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the +SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has +its own pair of quotes, which may or may not be bracketing quotes, +e.g., C<tr[A-Z][a-z]> or C<tr(+-*/)/ABCD/>. Options: @@ -983,8 +988,8 @@ an eval(): =head2 I/O Operators -There are several I/O operators you should know about. -A string is enclosed by back-ticks (grave accents) first undergoes +There are several I/O operators you should know about. +A string is enclosed by backticks (grave accents) first undergoes variable substitution just like a double quoted string. It is then interpreted as a command, and the output of that command is the value of the pseudo-literal, like in a shell. In a scalar context, a single @@ -997,8 +1002,8 @@ of C<$?>). Unlike in B<csh>, no translation is done on the return data--newlines remain newlines. Unlike in any of the shells, single quotes do not hide variable names in the command from interpretation. To pass a $ through to the shell you need to hide it with a backslash. -The generalized form of back-ticks is C<qx//>. (Because back-ticks -always undergo shell expansion as well, see L<perlsec> for +The generalized form of backticks is C<qx//>. (Because backticks +always undergo shell expansion as well, see L<perlsec> for security concerns.) Evaluating a filehandle in angle brackets yields the next line from @@ -1063,7 +1068,7 @@ continue as if the input were one big happy file. (But see example under eof() for how to reset line numbers on each file.) If you want to set @ARGV to your own list of files, go right ahead. If -you want to pass switches into your script, you can use one of the +you want to pass switches into your script, you can use one of the Getopts modules or put a loop on the front like this: while ($_ = $ARGV[0], /^-/) { @@ -1120,7 +1125,7 @@ machine.) Of course, the shortest way to do the above is: Because globbing invokes a shell, it's often faster to call readdir() yourself and do your own grep() on the filenames. Furthermore, due to its current -implementation of using a shell, the glob() routine may get "Arg list too +implementation of using a shell, the glob() routine may get "Arg list too long" errors (unless you've installed tcsh(1L) as F</bin/csh>). A glob evaluates its (embedded) argument only when it is starting a new @@ -1138,7 +1143,7 @@ than $file = <blurch*>; because the latter will alternate between returning a filename and -returning FALSE. +returning FALSE. It you're trying to do variable interpolation, it's definitely better to use the glob() function, because the older notation can cause people @@ -1159,14 +1164,14 @@ compile time. You can say 'Now is the time for all' . "\n" . 'good men to come to.' -and this all reduces to one string internally. Likewise, if +and this all reduces to one string internally. Likewise, if you say foreach $file (@filenames) { if (-s $file > 5 + 100 * 2**16) { ... } - } + } -the compiler will pre-compute the number that +the compiler will precompute the number that expression represents so that the interpreter won't have to. @@ -1180,7 +1185,7 @@ floating point. But by saying you may tell the compiler that it's okay to use integer operations from here to the end of the enclosing BLOCK. An inner BLOCK may -countermand this by saying +countermand this by saying no integer; diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 6a13991437..1dfb3ac3d4 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -54,7 +54,7 @@ items consistent: either use "=item *" for all of them, to produce bullets, or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use "=item foo", "=item bar", etc., i.e., things that looks nothing like bullets or numbers. If you start with bullets or numbers, stick with them, as many -formatters use the first "=item" type to decide how to format the list. +formatters use the first "=item" type to decide how to format the list. For, begin, and end let you include sections that are not interpreted as pod text, but passed directly to particular formatters. A formatter @@ -63,12 +63,12 @@ completely ignored. The directive "=for" specifies that the entire next paragraph is in the format indicated by the first word after "=for", like this: - =for html <br> + =for html <br> <p> This is a raw HTML paragraph </p> The paired commands "=begin" and "=end" work very similarly to "=for", but instead of only accepting a single paragraph, all text from "=begin" to a -paragraph with a matching "=end" are treated as a particular format. +paragraph with a matching "=end" are treated as a particular format. Here are some examples of how to use these: @@ -132,7 +132,7 @@ here and in commands: I<text> italicize text, used for emphasis or variables B<text> embolden text, used for switches and programs S<text> text contains non-breaking spaces - C<code> literal code + C<code> literal code L<name> A link (cross reference) to name L<name> manual page L<name/ident> item in manual page diff --git a/pod/perlre.pod b/pod/perlre.pod index 74a8bd9fd5..68964a0e9b 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -23,18 +23,18 @@ Do case-insensitive pattern matching. If C<use locale> is in effect, the case map is taken from the current locale. See L<perllocale>. -=item m +=item m Treat string as multiple lines. That is, change "^" and "$" from matching at only the very start or end of the string to the start or end of any line anywhere within the string, -=item s +=item s Treat string as single line. That is, change "." to match any character whatsoever, even a newline, which it normally would not match. -=item x +=item x Extend your pattern's legibility by permitting whitespace and comments. @@ -49,7 +49,7 @@ The C</x> modifier itself needs a little more explanation. It tells the regular expression parser to ignore whitespace that is neither backslashed nor within a character class. You can use this to break up your regular expression into (slightly) more readable parts. The C<#> -character is also treated as a meta-character introducing a comment, +character is also treated as a metacharacter introducing a comment, just as in ordinary Perl code. This also means that if you want real whitespace or C<#> characters in the pattern that you'll have to either escape them or encode them using octal or hex escapes. Taken together, @@ -67,7 +67,7 @@ See L<Version 8 Regular Expressions> for details. In particular the following metacharacters have their standard I<egrep>-ish meanings: - \ Quote the next meta-character + \ Quote the next metacharacter ^ Match the beginning of the line . Match any character (except newline) $ Match the end of the line (or before newline at the end) @@ -80,13 +80,13 @@ beginning of the string, the "$" character at only the end (or before the newline at the end) and Perl does certain optimizations with the assumption that the string contains only one line. Embedded newlines will not be matched by "^" or "$". You may, however, wish to treat a -string as a multi-line buffer, such that the "^" will match after any +string as a multiline buffer, such that the "^" will match after any newline within the string, and "$" will match before any newline. At the cost of a little more overhead, you can do this by using the /m modifier on the pattern match operator. (Older programs did this by setting C<$*>, but this practice is now deprecated.) -To facilitate multi-line substitutions, the "." character never matches a +To facilitate multiline substitutions, the "." character never matches a newline unless you use the C</s> modifier, which in effect tells Perl to pretend the string is a single line--even if it isn't. The C</s> modifier also overrides the setting of C<$*>, in case you have some (badly behaved) older @@ -106,13 +106,11 @@ as a regular character.) The "*" modifier is equivalent to C<{0,}>, the "+" modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. n and m are limited to integral values less than 65536. -By default, a quantified sub-pattern is "greedy", that is, it will match as -many times as possible without causing the rest of the pattern not to match. -The standard quantifiers are all "greedy", in that they match as many -occurrences as possible (given a particular starting location) without -causing the pattern to fail. If you want it to match the minimum number -of times possible, follow the quantifier with a "?" after any of them. -Note that the meanings don't change, just the "gravity": +By default, a quantified subpattern is "greedy", that is, it will match as +many times as possible (given a particular starting location) while still +allowing the rest of the pattern to match. If you want it to match the +minimum number of times possible, follow the quantifier with a "?". Note +that the meanings don't change, just the "greediness": *? Match 0 or more times +? Match 1 or more times @@ -176,7 +174,7 @@ just like "^" and "$" except that they won't match multiple times when the C</m> modifier is used, while "^" and "$" will match at every internal line boundary. To match the actual end of the string, not ignoring newline, you can use C<\Z(?!\n)>. The C<\G> assertion can be used to mix global -matches (using C<m//g>) and non-global ones, as described in +matches (using C<m//g>) and non-global ones, as described in L<perlop/"Regexp Quote-Like Operators">. It is also useful when writing C<lex>-like scanners, when you have several regexps which you want to match against consequent substrings of your @@ -230,14 +228,14 @@ You will note that all backslashed metacharacters in Perl are alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular expression languages, there are no backslashed symbols that aren't alphanumeric. So anything that looks like \\, \(, \), \E<lt>, \E<gt>, \{, or \} is always -interpreted as a literal character, not a meta-character. This makes it +interpreted as a literal character, not a metacharacter. This makes it simple to quote a string that you want to use for a pattern but that you are afraid might contain metacharacters. Quote simply all the non-alphanumeric characters: $pattern =~ s/(\W)/\\$1/g; -You can also use the built-in quotemeta() function to do this. +You can also use the builtin quotemeta() function to do this. An even easier way to quote metacharacters right in the match operator is to say @@ -420,7 +418,7 @@ definition might succeed against a particular string. And if there are multiple ways it might succeed, you need to understand backtracking to know which variety of success you will achieve. When using lookahead assertions and negations, this can all get even -tricker. Imagine you'd like to find a sequence of non-digits not +tricker. Imagine you'd like to find a sequence of non-digits not followed by "123". You might try to write that as $_ = "ABC123"; @@ -454,14 +452,14 @@ backtracking, whereas test 1 will not. What's happening is that you've asked "Is it true that at the start of $x, following 0 or more non-digits, you have something that's not 123?" If the pattern matcher had let C<\D*> expand to "ABC", this would have caused the whole pattern to -fail. +fail. The search engine will initially match C<\D*> with "ABC". Then it will try to match C<(?!123> with "123" which, of course, fails. But because a quantifier (C<\D*>) has been used in the regular expression, the search engine can backtrack and retry the match differently -in the hope of matching the complete regular expression. +in the hope of matching the complete regular expression. -Well now, +Well now, the pattern really, I<really> wants to succeed, so it uses the standard regexp back-off-and-retry and lets C<\D*> expand to just "AB" this time. Now there's indeed something following "AB" that is not @@ -503,7 +501,7 @@ it would take literally forever--or until you ran out of stack space. In case you're not familiar with the "regular" Version 8 regexp routines, here are the pattern-matching rules not described above. -Any single character matches itself, unless it is a I<meta-character> +Any single character matches itself, unless it is a I<metacharacter> with a special meaning described here or above. You can cause characters which normally function as metacharacters to be interpreted literally by prefixing them with a "\" (e.g., "\." matches a ".", not any @@ -518,13 +516,13 @@ in the list. Within a list, the "-" character is used to specify a range, so that C<a-z> represents all the characters between "a" and "z", inclusive. -Characters may be specified using a meta-character syntax much like that +Characters may be specified using a metacharacter syntax much like that used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return, "\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string of octal digits, matches the character whose ASCII value is I<nnn>. Similarly, \xI<nn>, where I<nn> are hexadecimal digits, matches the character whose ASCII value is I<nn>. The expression \cI<x> matches the -ASCII character control-I<x>. Finally, the "." meta-character matches any +ASCII character control-I<x>. Finally, the "." metacharacter matches any character except "\n" (unless you use C</s>). You can specify a series of alternatives for a pattern using "|" to @@ -539,14 +537,14 @@ start and end. Note however that "|" is interpreted as a literal with square brackets, so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>. -Within a pattern, you may designate sub-patterns for later reference by +Within a pattern, you may designate subpatterns for later reference by enclosing them in parentheses, and you may refer back to the I<n>th -sub-pattern later in the pattern using the meta-character \I<n>. -Sub-patterns are numbered based on the left to right order of their +subpattern later in the pattern using the metacharacter \I<n>. +Subpatterns are numbered based on the left to right order of their opening parenthesis. Note that a backreference matches whatever -actually matched the sub-pattern in the string being examined, not the -rules for that sub-pattern. Therefore, C<(0|0x)\d*\s\1\d*> will -match "0x1234 0x4321",but not "0x1234 01234", because sub-pattern 1 +actually matched the subpattern in the string being examined, not the +rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will +match "0x1234 0x4321",but not "0x1234 01234", because subpattern 1 actually matched "0x", even though the rule C<0|0x> could potentially match the leading 0 in the second number. diff --git a/pod/perlref.pod b/pod/perlref.pod index 4a0f14635c..cf793652f7 100644 --- a/pod/perlref.pod +++ b/pod/perlref.pod @@ -24,12 +24,12 @@ object, but we usually reserve the word for references to objects that have been officially "blessed" into a class package.) Symbolic references are names of variables or other objects, just as a -symbolic link in a UNIX filesystem contains merely the name of a file. +symbolic link in a Unix filesystem contains merely the name of a file. The C<*glob> notation is a kind of symbolic reference. (Symbolic references are sometimes called "soft references", but please don't call them that; references are confusing enough without useless synonyms.) -In contrast, hard references are more like hard links in a UNIX file +In contrast, hard references are more like hard links in a Unix file system: They are used to access an underlying object without concern for what its (other) name is. When the word "reference" is used without an adjective, like in the following paragraph, it usually is talking about a @@ -41,14 +41,14 @@ scalar is holding a reference, it always behaves as a simple scalar. It doesn't magically start being an array or hash or subroutine; you have to tell it explicitly to do so, by dereferencing it. -References can be constructed several ways. +References can be constructed in several ways. =over 4 =item 1. By using the backslash operator on a variable, subroutine, or value. -(This works much like the & (address-of) operator works in C.) Note +(This works much like the & (address-of) operator in C.) Note that this typically creates I<ANOTHER> reference to a variable, because there's already a reference to the variable in the symbol table. But the symbol table reference might go away, and you'll still have the @@ -63,7 +63,7 @@ reference that the backslash returned. Here are some examples: It isn't possible to create a true reference to an IO handle (filehandle or dirhandle) using the backslash operator. See the explanation of the *foo{THING} syntax below. (However, you're apt to find Perl code -out there using globrefs as though they were IO handles, which is +out there using globrefs as though they were IO handles, which is grandfathered into continued functioning.) =item 2. @@ -74,7 +74,7 @@ brackets: $arrayref = [1, 2, ['a', 'b', 'c']]; Here we've constructed a reference to an anonymous array of three elements -whose final element is itself reference to another anonymous array of three +whose final element is itself a reference to another anonymous array of three elements. (The multidimensional syntax described later can be used to access this. For example, after the above, C<$arrayref-E<gt>[2][1]> would have the value "b".) @@ -83,10 +83,10 @@ Note that taking a reference to an enumerated list is not the same as using square brackets--instead it's the same as creating a list of references! - @list = (\$a, \@b, \%c); + @list = (\$a, \@b, \%c); @list = \($a, @b, %c); # same thing! -As a special case, C<\(@foo)> returns a list of references to the contents +As a special case, C<\(@foo)> returns a list of references to the contents of C<@foo>, not a reference to C<@foo> itself. Likewise for C<%foo>. =item 3. @@ -143,8 +143,8 @@ context even when it's called outside of the context. In human terms, it's a funny way of passing arguments to a subroutine when you define it as well as when you call it. It's useful for setting up little bits of code to run later, such as callbacks. You can even -do object-oriented stuff with it, though Perl provides a different -mechanism to do that already--see L<perlobj>. +do object-oriented stuff with it, though Perl already provides a different +mechanism to do that--see L<perlobj>. You can also think of closure as a way to write a subroutine template without using eval. (In fact, in version 5.000, eval was the I<only> way to get @@ -298,7 +298,7 @@ Admittedly, it's a little silly to use the curlies in this case, but the BLOCK can contain any arbitrary expression, in particular, subscripted expressions: - &{ $dispatch{$index} }(1,2,3); # call correct routine + &{ $dispatch{$index} }(1,2,3); # call correct routine Because of being able to omit the curlies for the simple case of C<$$x>, people often make the mistake of viewing the dereferencing symbols as @@ -416,7 +416,7 @@ that, you can say use strict 'refs'; and then only hard references will be allowed for the rest of the enclosing -block. An inner block may countermand that with +block. An inner block may countermand that with no strict 'refs'; @@ -429,7 +429,7 @@ invisible to this mechanism. For example: { my $value = 20; print $$ref; - } + } This will still print 10, not 20. Remember that local() affects package variables, which are all "global" to the package. @@ -495,7 +495,7 @@ converted into a string: $x{ \$a } = $a; -If you try to dereference the key, it won't do a hard dereference, and +If you try to dereference the key, it won't do a hard dereference, and you won't accomplish what you're attempting. You might want to do something more like diff --git a/pod/perlrun.pod b/pod/perlrun.pod index a2e0764c7b..dd467a5050 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -44,7 +44,7 @@ beginning, unless you've specified a B<-x> switch, in which case it scans for the first line starting with #! and containing the word "perl", and starts there instead. This is useful for running a script embedded in a larger message. (In this case you would indicate the end -of the script using the __END__ token.) +of the script using the C<__END__> token.) The #! line is always examined for switches as the line is being parsed. Thus, if you're on a machine that allows only one argument @@ -81,7 +81,7 @@ dispatch the program to the correct interpreter for them. After locating your script, Perl compiles the entire script to an internal form. If there are any compilation errors, execution of the script is not attempted. (This is unlike the typical shell script, -which might run partway through before finding a syntax error.) +which might run part-way through before finding a syntax error.) If the script is syntactically correct, it is executed. If the script runs off the end without hitting an exit() or die() operator, an implicit @@ -102,7 +102,7 @@ Put as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's `extproc' handling). -=item DOS +=item MS-DOS Create a batch file to run your script, and codify it in C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source @@ -138,10 +138,10 @@ For example: # Unix perl -e 'print "Hello world\n"' - # DOS, etc. + # MS-DOS, etc. perl -e "print \"Hello world\n\"" - # Mac + # Macintosh print "Hello world\n" (then Run "Myscript" or Shift-Command-R) @@ -149,7 +149,7 @@ For example: perl -e "print ""Hello world\n""" The problem is that none of this is reliable: it depends on the command -tirely possible neither works. If 4DOS was the command shell, this would +and it is entirely possible neither works. If 4DOS was the command shell, this would probably work better: perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" @@ -158,9 +158,9 @@ CMD.EXE in Windows NT slipped a lot of standard Unix functionality in when nobody was looking, but just try to find documentation for its quoting rules. -Under the Mac, it depends which environment you are using. The MacPerl +Under the Macintosh, it depends which environment you are using. The MacPerl shell, or MPW, is much like Unix shells in its support for several -quoting variants, except that it makes free use of the Mac's non-ASCII +quoting variants, except that it makes free use of the Macintosh's non-ASCII characters as control characters. There is no general solution to all of this. It's just a mess. @@ -211,7 +211,7 @@ An alternate delimiter may be specified using B<-F>. causes Perl to check the syntax of the script and then exit without executing it. Actually, it I<will> execute C<BEGIN>, C<END>, and C<use> blocks, -because these are considered as occurring outside the execution of +because these are considered as occurring outside the execution of your program. =item B<-d> @@ -254,11 +254,11 @@ equivalent to B<-Dtls>): =item B<-e> I<commandline> -may be used to enter one line of script. +may be used to enter one line of script. If B<-e> is given, Perl -will not look for a script filename in the argument list. +will not look for a script filename in the argument list. Multiple B<-e> commands may -be given to build up a multi-line script. +be given to build up a multiline script. Make sure to use semicolons where you would in a normal program. =item B<-F>I<pattern> @@ -309,8 +309,8 @@ know when the filename has changed. It does, however, use ARGVOUT for the selected filehandle. Note that STDOUT is restored as the default output filehandle after the loop. -You can use C<eof> without parenthesis to locate the end of each input file, -in case you want to append to each file, or reset line numbering (see +You can use C<eof> without parenthesis to locate the end of each input file, +in case you want to append to each file, or reset line numbering (see example in L<perlfunc/eof>). =item B<-I>I<directory> @@ -358,7 +358,7 @@ e.g., C<-M'module qw(foo bar)'>. If the first character after the C<-M> or C<-m> is a dash (C<->) then the 'use' is replaced with 'no'. -A little built-in syntactic sugar means you can also say +A little builtin syntactic sugar means you can also say C<-mmodule=foo,bar> or C<-Mmodule=foo,bar> as a shortcut for C<-M'module qw(foo bar)'>. This avoids the need to use quotes when importing symbols. The actual code generated by C<-Mmodule=foo,bar> is @@ -547,6 +547,14 @@ instead say use lib "/my/directory"; +=item PERL5OPT + +Command-line options (switches). Switches in this variable are taken +as if they were on every Perl command line. Only the B<-[DIMUdmw]> +switches are allowed. When running taint checks (because the script +was running setuid or setgid, or the B<-T> switch was used), this +variable is ignored. + =item PERLLIB A colon-separated list of directories in which to look for Perl library diff --git a/pod/perlsec.pod b/pod/perlsec.pod index 0d72cf0ca6..e21f97f21f 100644 --- a/pod/perlsec.pod +++ b/pod/perlsec.pod @@ -6,10 +6,10 @@ perlsec - Perl security Perl is designed to make it easy to program securely even when running with extra privileges, like setuid or setgid programs. Unlike most -command-line shells, which are based on multiple substitution passes on +command line shells, which are based on multiple substitution passes on each line of the script, Perl uses a more conventional evaluation scheme with fewer hidden snags. Additionally, because the language has more -built-in functionality, it can rely less upon external (and possibly +builtin functionality, it can rely less upon external (and possibly untrustworthy) programs to accomplish its purposes. Perl automatically enables a set of special security checks, called I<taint @@ -29,7 +29,7 @@ and it is these checks especially that contribute to making a setuid Perl program more secure than the corresponding C program. You may not use data derived from outside your program to affect something -else outside your program--at least, not by accident. All command-line +else outside your program--at least, not by accident. All command line arguments, environment variables, locale information (see L<perllocale>), and file input are marked as "tainted". Tainted data may not be used directly or indirectly in any command that invokes a sub-shell, nor in any @@ -57,7 +57,7 @@ For example: $path = $ENV{'PATH'}; # $path now tainted - $ENV{'PATH'} = '/bin:/usr/bin'; + $ENV{'PATH'} = '/bin:/usr/bin'; $ENV{'IFS'} = '' if $ENV{'IFS'} ne ''; $path = $ENV{'PATH'}; # $path now NOT tainted @@ -82,7 +82,7 @@ For example: If you try to do something insecure, you will get a fatal error saying something like "Insecure dependency" or "Insecure PATH". Note that you can still write an insecure B<system> or B<exec>, but only by explicitly -doing something like the last example above. +doing something like the last example above. =head2 Laundering and Detecting Tainted Data @@ -91,9 +91,9 @@ trigger an "Insecure dependency" message, you can use the following I<is_tainted()> function. sub is_tainted { - return ! eval { - join('',@_), kill 0; - 1; + return ! eval { + join('',@_), kill 0; + 1; }; } @@ -106,7 +106,7 @@ same expression, the whole expression is considered tainted. But testing for taintedness gets you only so far. Sometimes you have just to clear your data's taintedness. The only way to bypass the tainting -mechanism is by referencing sub-patterns from a regular expression match. +mechanism is by referencing subpatterns from a regular expression match. Perl presumes that if you reference a substring using $1, $2, etc., that you knew what you were doing when you wrote the pattern. That means using a bit of thought--don't just blindly untaint anything, or you defeat the @@ -119,7 +119,7 @@ Here's a test to make sure that the data contains nothing but "word" characters (alphabetics, numerics, and underscores), a hyphen, an at sign, or a dot. - if ($data =~ /^([-\@\w.]+)$/) { + if ($data =~ /^([-\@\w.]+)$/) { $data = $1; # $data now untainted } else { die "Bad data in $data"; # log this somewhere @@ -146,12 +146,12 @@ block. See L<perllocale/SECURITY> for further discussion and examples. When you make a script executable, in order to make it usable as a command, the system will pass switches to perl from the script's #! -line. Perl checks that any command-line switches given to a setuid +line. Perl checks that any command line switches given to a setuid (or setgid) script actually match the ones set on the #! line. Some -UNIX and UNIX-like environments impose a one-switch limit on the #! +Unix and Unix-like environments impose a one-switch limit on the #! line, so you may need to use something like C<-wU> instead of C<-w -U> -under such systems. (This issue should arise only in UNIX or -UNIX-like environments that support #! and setuid or setgid scripts.) +under such systems. (This issue should arise only in Unix or +Unix-like environments that support #! and setuid or setgid scripts.) =head2 Cleaning Up Your Path @@ -164,7 +164,7 @@ it's generated because you never set your PATH environment variable, or you didn't set it to something that was safe. Because Perl can't guarantee that the executable in question isn't itself going to turn around and execute some other program that is dependent on your PATH, it -makes sure you set the PATH. +makes sure you set the PATH. It's also possible to get into trouble with other operations that don't care whether they use tainted values. Make judicious use of the file @@ -177,8 +177,8 @@ prevent stupid mistakes, not to remove the need for thought. Perl does not call the shell to expand wild cards when you pass B<system> and B<exec> explicit parameter lists instead of strings with possible shell wildcards in them. Unfortunately, the B<open>, B<glob>, and -back-tick functions provide no such alternate calling convention, so more -subterfuge will be required. +backtick functions provide no such alternate calling convention, so more +subterfuge will be required. Perl provides a reasonably safe way to open a file or pipe from a setuid or setgid program: just create a child process with reduced privilege who @@ -193,13 +193,13 @@ parent. Because the file or pipe was opened in the child while running under less privilege than the parent, it's not apt to be tricked into doing something it shouldn't. -Here's a way to do back-ticks reasonably safely. Notice how the B<exec> is +Here's a way to do backticks reasonably safely. Notice how the B<exec> is not called with a string that the shell could expand. This is by far the best way to call something that might be subjected to shell escapes: just never call the shell at all. By the time we get to the B<exec>, tainting is turned off, however, so be careful what you call and what you pass it. - use English; + use English; die unless defined $pid = open(KID, "-|"); if ($pid) { # parent while (<KID>) { @@ -247,7 +247,7 @@ Alternately, it can simply ignore the setuid bit on scripts. If the latter is true, Perl can emulate the setuid and setgid mechanism when it notices the otherwise useless setuid/gid bits on Perl scripts. It does this via a special executable called B<suidperl> that is automatically -invoked for you if it's needed. +invoked for you if it's needed. However, if the kernel setuid script feature isn't disabled, Perl will complain loudly that your setuid script is insecure. You'll need to @@ -258,14 +258,14 @@ kernel bug that plagues setuid scripts. Here's a simple wrapper, written in C: #define REAL_PATH "/path/to/script" - main(ac, av) + main(ac, av) char **av; { execv(REAL_PATH, av); - } + } -Compile this wrapper into a binary executable and then make I<it> rather -than your script setuid or setgid. +Compile this wrapper into a binary executable and then make I<it> rather +than your script setuid or setgid. See the program B<wrapsuid> in the F<eg> directory of your Perl distribution for a convenient way to do this automatically for all your @@ -308,7 +308,7 @@ instead of fixing them, is little security indeed. You can try using encryption via source filters (Filter::* from CPAN). But crackers might be able to decrypt it. You can try using the -byte-code compiler and interpreter described below, but crackers might +byte code compiler and interpreter described below, but crackers might be able to de-compile it. You can try using the native-code compiler described below, but crackers might be able to disassemble it. These pose varying degrees of difficulty to people wanting to get at your diff --git a/pod/perlstyle.pod b/pod/perlstyle.pod index 734b9ad032..8adb901139 100644 --- a/pod/perlstyle.pod +++ b/pod/perlstyle.pod @@ -6,7 +6,7 @@ perlstyle - Perl style guide Each programmer will, of course, have his or her own preferences in regards to formatting, but there are some general guidelines that will -make your programs easier to read, understand, and maintain. +make your programs easier to read, understand, and maintain. The most important thing is to run your programs under the B<-w> flag at all times. You may turn it off explicitly for particular @@ -17,7 +17,7 @@ useful. Regarding aesthetics of code lay out, about the only thing Larry cares strongly about is that the closing curly brace of -a multi-line BLOCK should line up with the keyword that started the construct. +a multiline BLOCK should line up with the keyword that started the construct. Beyond that, he has other preferences that aren't so strong: =over 4 @@ -32,7 +32,7 @@ Opening curly on same line as keyword, if possible, otherwise line up. =item * -Space before the opening curly of a multi-line BLOCK. +Space before the opening curly of a multiline BLOCK. =item * @@ -154,13 +154,13 @@ the middle. Just "outdent" it a little to make it more visible: =item * Don't be afraid to use loop labels--they're there to enhance -readability as well as to allow multi-level loop breaks. See the +readability as well as to allow multilevel loop breaks. See the previous example. =item * Avoid using grep() (or map()) or `backticks` in a void context, that is, -when you just throw away their return values. Those functions all +when you just throw away their return values. Those functions all have return values, so use them. Otherwise use a foreach() loop or the system() function instead. @@ -178,7 +178,7 @@ determined by the B<Configure> program when Perl was installed. Choose mnemonic identifiers. If you can't remember what mnemonic means, you've got a problem. -=item * +=item * While short identifiers like $gotit are probably ok, use underscores to separate words. It is generally easier to read $var_names_like_this than @@ -190,19 +190,19 @@ reserves lowercase module names for "pragma" modules like C<integer> and C<strict>. Other modules should begin with a capital letter and use mixed case, but probably without underscores due to limitations in primitive file systems' representations of module names as files that must fit into a -few sparse bites. +few sparse bytes. =item * -You may find it helpful to use letter case to indicate the scope -or nature of a variable. For example: +You may find it helpful to use letter case to indicate the scope +or nature of a variable. For example: - $ALL_CAPS_HERE constants only (beware clashes with perl vars!) - $Some_Caps_Here package-wide global/static - $no_caps_here function scope my() or local() variables + $ALL_CAPS_HERE constants only (beware clashes with perl vars!) + $Some_Caps_Here package-wide global/static + $no_caps_here function scope my() or local() variables -Function and method names seem to work best as all lowercase. -E.g., $obj-E<gt>as_string(). +Function and method names seem to work best as all lowercase. +E.g., $obj-E<gt>as_string(). You can use a leading underscore to indicate that a variable or function should not be used outside the package that defined it. @@ -227,12 +227,12 @@ Use here documents instead of repeated print() statements. =item * Line up corresponding things vertically, especially if it'd be too long -to fit on one line anyway. +to fit on one line anyway. - $IDX = $ST_MTIME; - $IDX = $ST_ATIME if $opt_u; - $IDX = $ST_CTIME if $opt_c; - $IDX = $ST_SIZE if $opt_s; + $IDX = $ST_MTIME; + $IDX = $ST_ATIME if $opt_u; + $IDX = $ST_CTIME if $opt_c; + $IDX = $ST_SIZE if $opt_s; mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!"; chdir($tmpdir) or die "can't chdir $tmpdir: $!"; diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 6e2309dfb2..602e5c0dda 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -23,7 +23,7 @@ To import subroutines: To call subroutines: NAME(LIST); # & is optional with parentheses. - NAME LIST; # Parentheses optional if pre-declared/imported. + NAME LIST; # Parentheses optional if predeclared/imported. &NAME; # Passes current @_ to subroutine. =head1 DESCRIPTION @@ -58,10 +58,14 @@ it was assigned to.) Note that assigning to the whole array @_ removes the aliasing, and does not update any arguments. The return value of the subroutine is the value of the last expression -evaluated. Alternatively, a return statement may be used to specify the -returned value and exit the subroutine. If you return one or more arrays -and/or hashes, these will be flattened together into one large -indistinguishable list. +evaluated. Alternatively, a return statement may be used exit the +subroutine, optionally specifying the returned value, which will be +evaluated in the appropriate context (list, scalar, or void) depending +on the context of the subroutine call. If you specify no return value, +the subroutine will return an empty list in a list context, an undefined +value in a scalar context, or nothing in a void context. If you return +one or more arrays and/or hashes, these will be flattened together into +one large indistinguishable list. Perl does not have named formal parameters, but in practice all you do is assign to a my() list of these. Any variables you use in the function @@ -89,7 +93,7 @@ Example: sub get_line { $thisline = $lookahead; # GLOBAL VARIABLES!! - LINE: while ($lookahead = <STDIN>) { + LINE: while (defined($lookahead = <STDIN>)) { if ($lookahead =~ /^[ \t]/) { $thisline .= $lookahead; } @@ -118,8 +122,8 @@ do in-place modifications of @_ and change its caller's values. upcase_in($v1, $v2); # this changes $v1 and $v2 sub upcase_in { - for (@_) { tr/a-z/A-Z/ } - } + for (@_) { tr/a-z/A-Z/ } + } You aren't allowed to modify constants in this way, of course. If an argument were actually literal and you tried to change it, you'd take a @@ -127,17 +131,17 @@ argument were actually literal and you tried to change it, you'd take a upcase_in("frederick"); -It would be much safer if the upcase_in() function +It would be much safer if the upcase_in() function were written to return a copy of its parameters instead of changing them in place: ($v3, $v4) = upcase($v1, $v2); # this doesn't sub upcase { + return unless defined wantarray; # void context, do nothing my @parms = @_; - for (@parms) { tr/a-z/A-Z/ } - # wantarray checks if we were called in list context + for (@parms) { tr/a-z/A-Z/ } return wantarray ? @parms : $parms[0]; - } + } Notice how this (unprototyped) function doesn't care whether it was passed real scalars or arrays. Perl will see everything as one big long flat @_ @@ -159,7 +163,7 @@ made @b an empty list. See L</"Pass by Reference"> for alternatives. A subroutine may be called using the "&" prefix. The "&" is optional in modern Perls, and so are the parentheses if the subroutine has been -pre-declared. (Note, however, that the "&" is I<NOT> optional when +predeclared. (Note, however, that the "&" is I<NOT> optional when you're just naming the subroutine, such as when it's used as an argument to defined() or undef(). Nor is it optional when you want to do an indirect subroutine call with a subroutine name or reference @@ -179,7 +183,7 @@ new users may wish to avoid. &foo(); # the same &foo; # foo() get current args, like foo(@_) !! - foo; # like foo() IFF sub foo pre-declared, else "foo" + foo; # like foo() IFF sub foo predeclared, else "foo" Not only does the "&" form make the argument list optional, but it also disables any prototype checking on the arguments you do provide. This @@ -226,7 +230,7 @@ this is used to name the parameters to a subroutine. Examples: my $arg = shift; # name doesn't matter $arg **= 1/3; return $arg; - } + } The "my" is simply a modifier on something you might assign to. So when you do assign to the variables in its argument list, the "my" doesn't @@ -253,7 +257,7 @@ the current statement. Thus, my $x = $x; -can be used to initialize the new $x with the value of the old $x, and +can be used to initialize the new $x with the value of the old $x, and the expression my $x = 123 and $x == 123 @@ -264,7 +268,7 @@ Lexical scopes of control structures are not bounded precisely by the braces that delimit their controlled blocks; control expressions are part of the scope, too. Thus in the loop - while (my $line = <>) { + while (defined(my $line = <>)) { $line = lc $line; } continue { print $line; @@ -367,28 +371,28 @@ just enclose the whole function in an extra block, and put the static variable outside the function but in the block. { - my $secret_val = 0; + my $secret_val = 0; sub gimme_another { return ++$secret_val; - } - } + } + } # $secret_val now becomes unreachable by the outside # world, but retains its value between calls to gimme_another -If this function is being sourced in from a separate file +If this function is being sourced in from a separate file via C<require> or C<use>, then this is probably just fine. If it's -all in the main program, you'll need to arrange for the my() +all in the main program, you'll need to arrange for the my() to be executed early, either by putting the whole block above -your pain program, or more likely, placing merely a BEGIN +your pain program, or more likely, placing merely a BEGIN sub around it to make sure it gets executed before your program starts to run: sub BEGIN { - my $secret_val = 0; + my $secret_val = 0; sub gimme_another { return ++$secret_val; - } - } + } + } See L<perlrun> about the BEGIN function. @@ -412,7 +416,7 @@ Synopsis: local *merlyn = *randal; # now $merlyn is really $randal, plus # @merlyn is really @randal, etc local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal - local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc + local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc A local() modifies its listed variables to be local to the enclosing block, (or subroutine, C<eval{}>, or C<do>) and I<any called from @@ -433,9 +437,9 @@ subroutine. Examples: for $i ( 0 .. 9 ) { $digits{$i} = $i; - } + } # assume this function uses global %digits hash - parse_num(); + parse_num(); # now temporarily add to %digits hash if ($base12) { @@ -525,29 +529,29 @@ list of all their former last elements: my @retlist = (); foreach $aref ( @_ ) { push @retlist, pop @$aref; - } + } return @retlist; - } + } -Here's how you might write a function that returns a +Here's how you might write a function that returns a list of keys occurring in all the hashes passed to it: - @common = inter( \%foo, \%bar, \%joe ); + @common = inter( \%foo, \%bar, \%joe ); sub inter { my ($k, $href, %seen); # locals foreach $href (@_) { while ( $k = each %$href ) { $seen{$k}++; - } - } + } + } return grep { $seen{$_} == @_ } keys %seen; - } + } So far, we're using just the normal list return mechanism. -What happens if you want to pass or return a hash? Well, -if you're using only one of them, or you don't mind them +What happens if you want to pass or return a hash? Well, +if you're using only one of them, or you don't mind them concatenating, then the normal calling convention is ok, although -a little expensive. +a little expensive. Where people get into trouble is here: @@ -572,8 +576,8 @@ in order of how many elements they have in them: return ($cref, $dref); } else { return ($dref, $cref); - } - } + } + } It turns out that you can actually do this also: @@ -585,8 +589,8 @@ It turns out that you can actually do this also: return (\@c, \@d); } else { return (\@d, \@c); - } - } + } + } Here we're using the typeglobs to do symbol table aliasing. It's a tad subtle, though, and also won't work if you're using my() @@ -617,7 +621,7 @@ If you're planning on generating new filehandles, you could do this: my $name = shift; local *FH; return open (FH, $path) ? *FH : undef; - } + } Although that will actually produce a small memory leak. See the bottom of L<perlfunc/open()> for a somewhat cleaner way using the IO::Handle @@ -744,7 +748,7 @@ if you decide that a function should take just one parameter, like this: sub func ($) { my $n = shift; print "you gave me $n\n"; - } + } and someone has been calling it with an array or expression returning a list: @@ -760,15 +764,17 @@ in @foo. And the split() gets called in a scalar context and starts scribbling on your @_ parameter list. This is all very powerful, of course, and should be used only in moderation -to make the world a better place. +to make the world a better place. =head2 Constant Functions Functions with a prototype of C<()> are potential candidates for -inlining. If the result after optimization and constant folding is a -constant then it will be used in place of new-style calls to the -function. Old-style calls (that is, calls made using C<&>) are not -affected. +inlining. If the result after optimization and constant folding is +either a constant or a lexically-scoped scalar which has no other +references, then it will be used in place of function calls made +without C<&> or C<do>. Calls made using C<&> or C<do> are never +inlined. (See constant.pm for an easy way to declare most +constants.) All of the following functions would be inlined. @@ -781,8 +787,8 @@ All of the following functions would be inlined. sub FLAG_FOO () { 1 << 8 } sub FLAG_BAR () { 1 << 9 } sub FLAG_MASK () { FLAG_FOO | FLAG_BAR } - - sub OPT_BAZ () { 1 } + + sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) } sub BAZ_VAL () { if (OPT_BAZ) { return 23; @@ -792,6 +798,13 @@ All of the following functions would be inlined. } } + sub N () { int(BAZ_VAL) / 3 } + BEGIN { + my $prod = 1; + for (1..N) { $prod *= $_ } + sub N_FACTORIAL () { $prod } + } + If you redefine a subroutine which was eligible for inlining you'll get a mandatory warning. (You can use this warning to tell whether or not a particular subroutine is considered constant.) The warning is @@ -802,9 +815,8 @@ ensure that it isn't inlined, either by dropping the C<()> prototype (which changes the calling semantics, so beware) or by thwarting the inlining mechanism in some other way, such as - my $dummy; sub not_inlined () { - $dummy || 23 + 23 if $]; } =head2 Overriding Builtin Functions @@ -816,7 +828,7 @@ on a non-Unix system. Overriding may be done only by importing the name from a module--ordinary predeclaration isn't good enough. However, the -C<subs> pragma (compiler directive) lets you, in effect, pre-declare subs +C<subs> pragma (compiler directive) lets you, in effect, predeclare subs via the import syntax, and these names may then override the builtin ones: use subs 'chdir', 'chroot', 'chmod', 'chown'; @@ -864,12 +876,12 @@ should just call system() with those arguments. All you'd do is this: my $program = $AUTOLOAD; $program =~ s/.*:://; system($program, @_); - } + } date(); who('am', 'i'); ls('-l'); -In fact, if you pre-declare the functions you want to call that way, you don't +In fact, if you predeclare the functions you want to call that way, you don't even need the parentheses: use subs qw(date who ls); @@ -889,6 +901,6 @@ functions to perl code in L<perlxs>. =head1 SEE ALSO See L<perlref> for more on references. See L<perlxs> if you'd -like to learn about calling C subroutines from perl. See -L<perlmod> to learn about bundling up your functions in +like to learn about calling C subroutines from perl. See +L<perlmod> to learn about bundling up your functions in separate files. diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index 77dcc597a9..9c3f6617bd 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -32,20 +32,23 @@ that. A declaration can be put anywhere a statement can, but has no effect on the execution of the primary sequence of statements--declarations all take effect at compile time. Typically all the declarations are put at -the beginning or the end of the script. However, if you're using +the beginning or the end of the script. However, if you're using lexically-scoped private variables created with my(), you'll have to make sure your format or subroutine definition is within the same block scope as the my if you expect to be able to access those private variables. Declaring a subroutine allows a subroutine name to be used as if it were a list operator from that point forward in the program. You can declare a -subroutine (prototyped to take one scalar parameter) without defining it by saying just: +subroutine without defining it by saying C<sub name>, thus: - sub myname ($); + sub myname; $me = myname $0 or die "can't get myname"; -Note that it functions as a list operator though, not as a unary -operator, so be careful to use C<or> instead of C<||> there. +Note that it functions as a list operator, not as a unary operator; so +be careful to use C<or> instead of C<||> in this case. However, if +you were to declare the subroutine as C<sub myname ($)>, then +C<myname> would functonion as a unary operator, so either C<or> or +C<||> would work. Subroutines declarations can also be loaded up with the C<require> statement or both loaded and imported into your namespace with a C<use> statement. @@ -65,7 +68,7 @@ semicolon, unless it is the final statement in a block, in which case the semicolon is optional. (A semicolon is still encouraged there if the block takes up more than one line, because you may eventually add another line.) Note that there are some operators like C<eval {}> and C<do {}> that look -like compound statements, but aren't (they're just TERMs in an expression), +like compound statements, but aren't (they're just TERMs in an expression), and thus need an explicit termination if used as the last item in a statement. Any simple statement may optionally be followed by a I<SINGLE> modifier, @@ -178,25 +181,26 @@ want to skip ahead and get the next record. while (<>) { chomp; - if (s/\\$//) { - $_ .= <>; + if (s/\\$//) { + $_ .= <>; redo unless eof(); } # now process $_ - } + } which is Perl short-hand for the more explicitly written version: - LINE: while ($line = <ARGV>) { + LINE: while (defined($line = <ARGV>)) { chomp($line); - if ($line =~ s/\\$//) { - $line .= <ARGV>; + if ($line =~ s/\\$//) { + $line .= <ARGV>; redo LINE unless eof(); # not eof(ARGV)! } # now process $line - } + } -Or here's a simpleminded Pascal comment stripper (warning: assumes no { or } in strings). +Or here's a simpleminded Pascal comment stripper (warning: assumes no +{ or } in strings). LINE: while (<STDIN>) { while (s|({.*}.*){.*}|$1 |) {} @@ -246,15 +250,15 @@ for variables declared with C<my> in the initialization expression.) Besides the normal array index looping, C<for> can lend itself to many other interesting applications. Here's one that avoids the -problem you get into if you explicitly test for end-of-file on -an interactive file descriptor causing your program to appear to +problem you get into if you explicitly test for end-of-file on +an interactive file descriptor causing your program to appear to hang. $on_a_tty = -t STDIN && -t STDOUT; sub prompt { print "yes? " if $on_a_tty } for ( prompt(); <STDIN>; prompt() ) { # do something - } + } =head2 Foreach Loops @@ -309,12 +313,12 @@ Here's how a C programmer might code up a particular algorithm in Perl: Whereas here's how a Perl programmer more comfortable with the idiom might do it: - OUTER: foreach my $wid (@ary1) { + OUTER: foreach my $wid (@ary1) { INNER: foreach my $jet (@ary2) { next OUTER if $wid > $jet; $wid += $jet; - } - } + } + } See how much easier this is? It's cleaner, safer, and faster. It's cleaner because it's less noisy. It's safer because if code gets added @@ -370,19 +374,19 @@ or or formatted so it stands out more as a "proper" switch statement: SWITCH: { - /^abc/ && do { - $abc = 1; - last SWITCH; + /^abc/ && do { + $abc = 1; + last SWITCH; }; - /^def/ && do { - $def = 1; - last SWITCH; + /^def/ && do { + $def = 1; + last SWITCH; }; - /^xyz/ && do { - $xyz = 1; - last SWITCH; + /^xyz/ && do { + $xyz = 1; + last SWITCH; }; $nothing = 1; } @@ -416,14 +420,14 @@ a temporary assignment to $_ for convenient matching: /Anywhere/ && do { push @flags, '-h'; last; }; /In Rulings/ && do { last; }; die "unknown value for form variable where: `$where'"; - } + } Another interesting approach to a switch statement is arrange for a C<do> block to return the proper value: $amode = do { - if ($flag & O_RDONLY) { "r" } - elsif ($flag & O_WRONLY) { ($flag & O_APPEND) ? "a" : "w" } + if ($flag & O_RDONLY) { "r" } + elsif ($flag & O_WRONLY) { ($flag & O_APPEND) ? "a" : "w" } elsif ($flag & O_RDWR) { if ($flag & O_CREAT) { "w+" } else { ($flag & O_APPEND) ? "a+" : "r+" } @@ -475,14 +479,14 @@ encounters a line that begins with an equal sign and a word, like this Then that text and all remaining text up through and including a line beginning with C<=cut> will be ignored. The format of the intervening -text is described in L<perlpod>. +text is described in L<perlpod>. This allows you to intermix your source code and your documentation text freely, as in =item snazzle($) - The snazzle() function will behave in the most spectacular + The snazzle() function will behave in the most spectacular form that you can possibly imagine, not even excepting cybernetic pyrotechnics. @@ -491,11 +495,11 @@ and your documentation text freely, as in sub snazzle($) { my $thingie = shift; ......... - } + } -Note that pod translators should look at only paragraphs beginning +Note that pod translators should look at only paragraphs beginning with a pod directive (it makes parsing easier), whereas the compiler -actually knows to look for pod escapes even in the middle of a +actually knows to look for pod escapes even in the middle of a paragraph. This means that the following secret stuff will be ignored by both the compiler and the translators. @@ -532,18 +536,18 @@ shell: die 'foo'; __END__ foo at bzzzt line 201. - + % perl # line 200 "bzzzt" eval qq[\n#line 2001 ""\ndie 'foo']; print $@; __END__ foo at - line 2001. - + % perl eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@; __END__ foo at foo bar line 200. - + % perl # line 345 "goop" eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'"; diff --git a/pod/perltoc.pod b/pod/perltoc.pod index baef9320aa..9a103bfaeb 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -66,7 +66,7 @@ authors =over -=item Non-commercial Reproduction +=item Noncommercial Reproduction =item Commercial Reproduction @@ -224,13 +224,13 @@ MacPerl, Perl5-Porters, NTPerl, Perl-Packrats =item How can I hide the source for my Perl program? -=item How can I compile my Perl program into byte-code or C? +=item How can I compile my Perl program into byte code or C? -=item How can I get '#!perl' to work on [MSDOS,NT,...]? +=item How can I get '#!perl' to work on [MS-DOS,Windows NT,...]? =item Can I write useful perl programs on the command line? -=item Why don't perl one-liners work on my DOS/Mac/VMS system? +=item Why don't perl one-liners work on my MS-DOS/Macintosh/VMS system? =item Where can I learn about CGI or Web programming in Perl? @@ -414,7 +414,7 @@ it? =item Why does passing a subroutine an undefined element in a hash create it? -=item How can I make the Perl equivalent of a C structure/C++ class/hash +=item How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays? =item How can I use a reference as a hash key? @@ -484,7 +484,7 @@ filehandles between subroutines? How do I make an array of filehandles? =item What can't I just open(FH, ">file.lock")? -=item I still don't get locking. I just want to increment the number +=item I still don't get locking. I just want to increment the number in the file. How can I do this? =item How do I randomly update a binary file? @@ -511,7 +511,7 @@ in the file. How can I do this? =item How do I close a file descriptor by number? -=item Why can't I use "C:\temp\foo" in DOS paths? What doesn't +=item Why can't I use "C:\temp\foo" in MS-DOS paths? What doesn't `C:\temp\foo.exe` work? =item Why doesn't glob("*.*") get all the files? @@ -532,7 +532,7 @@ protected files? Isn't this a bug in Perl? =over =item How can I hope to use regular expressions without creating illegible -and unmaintainable code? +and unmaintainable code? Comments Outside the Regexp, Comments Inside the Regexp, Different Delimiters @@ -551,7 +551,7 @@ case on the RHS? =item How can I match a locale-smart version of C</[a-zA-Z]/>? -=item How can I quote a variable to use in a regexp? +=item How can I quote a variable to use in a regexp? =item What is C</o> really for? @@ -580,7 +580,7 @@ file? =item What's wrong with using grep or map in a void context? -=item How can I match strings with multi-byte characters? +=item How can I match strings with multibyte characters? =back @@ -637,7 +637,7 @@ is in scope? =item Why doesn't "local($foo) = <FILE>;" work right? -=item How do I redefine a built-in function, operator, or method? +=item How do I redefine a builtin function, operator, or method? =item What's the difference between calling a function as &foo and foo()? @@ -714,7 +714,7 @@ does the error message "Protocol not supported" mean? =item How can I call backticks without shell processing? =item Why can't my script read from STDIN after I gave it EOF (^D on Unix, -^Z on MSDOS)? +^Z on MS-DOS)? =item How can I convert my shell script to perl? @@ -823,29 +823,37 @@ file on another machine? =over -=item Compilation Option: Binary Compatibility With 5.003 +=item Compilation option: Binary compatibility with 5.003 + +=item $PERL5OPT environment variable + +=item More precise warnings =item Subroutine arguments created only when they're modified -=item Fixed Parsing of $$<digit>, &$<digit>, etc. +=item Simple functions' C<AUTOLOAD> not looked up as method + +=item Fixed parsing of $$<digit>, &$<digit>, etc. + +=item No resetting of $. on implicit close -=item No Resetting of $. on Implicit Close +=item C<wantarray> may return undef -=item Changes to Tainting Checks +=item Changes to tainting checks -=item New Opcode Module and Revised Safe Module +=item New Opcode module and revised Safe module -=item Embedding Improvements +=item Embedding improvements -=item Internal Change: FileHandle Class Based on IO::* Classes +=item Internal change: FileHandle class based on IO::* classes -=item Internal Change: PerlIO internal IO abstraction interface +=item Internal change: PerlIO abstraction interface -=item New and Changed Built-in Variables +=item New and changed builtin variables $^E, $^H, $^M -=item New and Changed Built-in Functions +=item New and changed builtin functions delete on slices, flock, printf and sprintf, keys as an lvalue, my() in Control Structures, unpack() and pack(), use VERSION, use Module VERSION @@ -853,36 +861,37 @@ LIST, prototype(FUNCTION), srand, $_ as Default, C<m//g> does not trigger a pos() reset on failure, C<m//x> ignores whitespace before ?*+{}, nested C<sub{}> closures work now, formats work right on changing lexicals -=item New Built-in Methods +=item New builtin methods isa(CLASS), can(METHOD), VERSION( [NEED] ) -=item TIEHANDLE Now Supported +=item TIEHANDLE now supported TIEHANDLE classname, LIST, PRINT this, LIST, READ this LIST, READLINE this, GETC this, DESTROY this -=item Malloc Enhancements +=item Malloc enhancements -DDEBUGGING_MSTATS, -DEMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE -=item Miscellaneous Efficiency Enhancements +=item Miscellaneous efficiency enhancements =back =item Pragmata -use blib, use blib 'dir', use locale, use ops, use vmsish +use autouse MODULE => qw(sub1 sub2 sub3), use blib, use blib 'dir', use +constant NAME => VALUE, use locale, use ops, use vmsish =item Modules =over -=item Installation Directories +=item Installation directories -=item Fcntl +=item Module information summary -=item Module Information Summary +=item Fcntl =item IO @@ -892,7 +901,7 @@ use blib, use blib 'dir', use locale, use ops, use vmsish =item Net::Ping -=item Overridden Built-ins +=item Object-oriented overrides for builtin operators =back @@ -919,20 +928,24 @@ L<perlsec> "my" variable %s masks earlier declaration in same scope, %s argument is not a HASH element or slice, Allocation too large: %lx, Allocation too -large, Attempt to free non-existent shared string, Attempt to use reference -as lvalue in substr, Unsupported function fork, Ill-formed logical name -|%s| in prime_env_iter, Can't use bareword ("%s") as %s ref while "strict -refs" in use, Constant subroutine %s redefined, Died, Integer overflow in -hex number, Integer overflow in octal number, Name "%s::%s" used only once: -possible typo, Null picture in formline, Offset outside string, Stub found -while resolving method `%s' overloading `%s' in package `%s', Cannot -resolve method `%s' overloading `%s' in package `s', Out of memory!, Out of -memory during request for %s, Possible attempt to put comments in qw() -list, Possible attempt to separate words with commas, Scalar value @%s{%s} -better written as $%s{%s}, untie attempted while %d inner references still -exist, Value of %s construct can be "0"; test with defined(), Variable "%s" -may be unavailable, Variable "%s" will not stay shared, Warning: -something's wrong, Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, +large, Applying %s to %s will act on scalar(%s), Attempt to free +nonexistent shared string, Attempt to use reference as lvalue in substr, +Can't use bareword ("%s") as %s ref while "strict refs" in use, Cannot +resolve method `%s' overloading `%s' in package `%s', Constant subroutine +%s redefined, Constant subroutine %s undefined, Copy method did not return +a reference, Died, Exiting pseudo-block via %s, Illegal character %s +(carriage return), Illegal switch in PERL5OPT: %s, Integer overflow in hex +number, Integer overflow in octal number, Name "%s::%s" used only once: +possible typo, Null picture in formline, Offset outside string, Out of +memory!, Out of memory during request for %s, Possible attempt to put +comments in qw() list, Possible attempt to separate words with commas, +Scalar value @%s{%s} better written as $%s{%s}, Stub found while resolving +method `%s' overloading `%s' in package `%s', Too late for "B<-T>" option, +untie attempted while %d inner references still exist, Unrecognized +character %s, Unsupported function fork, Value of %s can be "0"; test with +defined(), Variable "%s" may be unavailable, Variable "%s" will not stay +shared, Warning: something's wrong, Ill-formed logical name |%s| in +prime_env_iter, Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, PERL_SH_DIR too long, Process terminated by SIG%s =item BUGS @@ -1098,7 +1111,7 @@ i, m, s, x =item #! and quoting on non-Unix systems -OS/2, DOS, Win95/NT, Macintosh +OS/2, MS-DOS, Win95/NT, Macintosh =item Switches @@ -1113,8 +1126,8 @@ B<-T>, B<-u>, B<-U>, B<-v>, B<-V>, B<-V:>I<name>, B<-w>, B<-x> I<directory> =item ENVIRONMENT -HOME, LOGDIR, PATH, PERL5LIB, PERLLIB, PERL5DB, PERL_DEBUG_MSTATS, -PERL_DESTRUCT_LEVEL +HOME, LOGDIR, PATH, PERL5LIB, PERL5OPT, PERLLIB, PERL5DB, +PERL_DEBUG_MSTATS, PERL_DESTRUCT_LEVEL =head2 perlfunc - Perl builtin functions @@ -1179,9 +1192,9 @@ qx/STRING/, qw/STRING/, quotemeta EXPR, quotemeta, rand EXPR, rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET, read FILEHANDLE,SCALAR,LENGTH, readdir DIRHANDLE, readlink EXPR, readlink, recv SOCKET,SCALAR,LEN,FLAGS, redo LABEL, redo, ref EXPR, ref, rename OLDNAME,NEWNAME, require EXPR, require, -reset EXPR, reset, return LIST, reverse LIST, rewinddir DIRHANDLE, rindex -STR,SUBSTR,POSITION, rindex STR,SUBSTR, rmdir FILENAME, rmdir, s///, scalar -EXPR, seek FILEHANDLE,POSITION,WHENCE, seekdir DIRHANDLE,POS, select +reset EXPR, reset, return EXPR, return, reverse LIST, rewinddir DIRHANDLE, +rindex STR,SUBSTR,POSITION, rindex STR,SUBSTR, rmdir FILENAME, rmdir, s///, +scalar EXPR, seek FILEHANDLE,POSITION,WHENCE, seekdir DIRHANDLE,POS, select FILEHANDLE, select, select RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget KEY,NSEMS,FLAGS, semop KEY,OPSTRING, send SOCKET,MSG,FLAGS,TO, send SOCKET,MSG,FLAGS, setpgrp PID,PGRP, setpriority @@ -1713,7 +1726,7 @@ more elaborate constructs isa(CLASS), can(METHOD), VERSION( [NEED] ) -=item Destructors +=item Destructors =item WARNING @@ -1866,7 +1879,7 @@ command, m expr, m package =item Debugger input/output -Prompt, Multi-line commands, Stack backtrace, Listing, Frame listing +Prompt, Multiline commands, Stack backtrace, Listing, Frame listing =item Debugging compile-time statements @@ -2018,7 +2031,7 @@ Unclassified =item PREAMBLE -B<Use C from Perl?>, B<Use a UNIX program from Perl?>, B<Use Perl from +B<Use C from Perl?>, B<Use a Unix program from Perl?>, B<Use Perl from Perl?>, B<Use C from C?>, B<Use Perl from C?> =item ROADMAP @@ -2228,13 +2241,13 @@ B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)> =item What is an "IV"? -=item Working with SV's +=item Working with SVs =item What's Really Stored in an SV? -=item Working with AV's +=item Working with AVs -=item Working with HV's +=item Working with HVs =item Hash API Extensions @@ -2248,7 +2261,7 @@ B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)> =item Stashes and Globs -=item Double-Typed SV's +=item Double-Typed SVs =item Magic Variables @@ -2304,27 +2317,28 @@ AvFILL, av_clear, av_extend, av_fetch, av_len, av_make, av_pop, av_push, av_shift, av_store, av_undef, av_unshift, CLASS, Copy, croak, CvSTASH, DBsingle, DBsub, DBtrace, dMARK, dORIGMARK, dowarn, dSP, dXSARGS, dXSI32, dXSI32, ENTER, EXTEND, FREETMPS, G_ARRAY, G_DISCARD, G_EVAL, GIMME, -G_NOARGS, G_SCALAR, gv_fetchmeth, gv_fetchmethod, gv_stashpv, gv_stashsv, -GvSV, HEf_SVKEY, HeHASH, HeKEY, HeKLEN, HePV, HeSVKEY, HeSVKEY_force, -HeSVKEY_set, HeVAL, hv_clear, hv_delayfree_ent, hv_delete, hv_delete_ent, -hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, hv_free_ent, hv_iterinit, -hv_iterkey, hv_iterkeysv, hv_iternext, hv_iternextsv, hv_iterval, hv_magic, -HvNAME, hv_store, hv_store_ent, hv_undef, isALNUM, isALPHA, isDIGIT, -isLOWER, isSPACE, isUPPER, items, ix, LEAVE, MARK, mg_clear, mg_copy, -mg_find, mg_free, mg_get, mg_len, mg_magical, mg_set, Move, na, New, Newc, -Newz, newAV, newHV, newRV_inc, newRV_noinc, newSV, newSViv, newSVnv, -newSVpv, newSVrv, newSVsv, newXS, newXSproto, Nullav, Nullch, Nullcv, -Nullhv, Nullsv, ORIGMARK, perl_alloc, perl_call_argv, perl_call_method, -perl_call_pv, perl_call_sv, perl_construct, perl_destruct, perl_eval_sv, -perl_free, perl_get_av, perl_get_cv, perl_get_hv, perl_get_sv, perl_parse, -perl_require_pv, perl_run, POPi, POPl, POPp, POPn, POPs, PUSHMARK, PUSHi, -PUSHn, PUSHp, PUSHs, PUTBACK, Renew, Renewc, RETVAL, safefree, safemalloc, -saferealloc, savepv, savepvn, SAVETMPS, SP, SPAGAIN, ST, strEQ, strGE, -strGT, strLE, strLT, strNE, strnEQ, strnNE, sv_2mortal, sv_bless, sv_catpv, -sv_catpvn, sv_catsv, sv_cmp, sv_cmp, SvCUR, SvCUR_set, sv_dec, sv_dec, -SvEND, sv_eq, SvGROW, sv_grow, sv_inc, SvIOK, SvIOK_off, SvIOK_on, -SvIOK_only, SvIOK_only, SvIOKp, sv_isa, SvIV, sv_isobject, SvIVX, SvLEN, -sv_len, sv_len, sv_magic, sv_mortalcopy, SvOK, sv_newmortal, sv_no, SvNIOK, +GIMME_V, G_NOARGS, G_SCALAR, G_VOID, gv_fetchmeth, gv_fetchmethod, +gv_stashpv, gv_stashsv, GvSV, HEf_SVKEY, HeHASH, HeKEY, HeKLEN, HePV, +HeSVKEY, HeSVKEY_force, HeSVKEY_set, HeVAL, hv_clear, hv_delayfree_ent, +hv_delete, hv_delete_ent, hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, +hv_free_ent, hv_iterinit, hv_iterkey, hv_iterkeysv, hv_iternext, +hv_iternextsv, hv_iterval, hv_magic, HvNAME, hv_store, hv_store_ent, +hv_undef, isALNUM, isALPHA, isDIGIT, isLOWER, isSPACE, isUPPER, items, ix, +LEAVE, MARK, mg_clear, mg_copy, mg_find, mg_free, mg_get, mg_len, +mg_magical, mg_set, Move, na, New, Newc, Newz, newAV, newHV, newRV_inc, +newRV_noinc, newSV, newSViv, newSVnv, newSVpv, newSVrv, newSVsv, newXS, +newXSproto, Nullav, Nullch, Nullcv, Nullhv, Nullsv, ORIGMARK, perl_alloc, +perl_call_argv, perl_call_method, perl_call_pv, perl_call_sv, +perl_construct, perl_destruct, perl_eval_sv, perl_free, perl_get_av, +perl_get_cv, perl_get_hv, perl_get_sv, perl_parse, perl_require_pv, +perl_run, POPi, POPl, POPp, POPn, POPs, PUSHMARK, PUSHi, PUSHn, PUSHp, +PUSHs, PUTBACK, Renew, Renewc, RETVAL, safefree, safemalloc, saferealloc, +savepv, savepvn, SAVETMPS, SP, SPAGAIN, ST, strEQ, strGE, strGT, strLE, +strLT, strNE, strnEQ, strnNE, sv_2mortal, sv_bless, sv_catpv, sv_catpvn, +sv_catsv, sv_cmp, sv_cmp, SvCUR, SvCUR_set, sv_dec, sv_dec, SvEND, sv_eq, +SvGROW, sv_grow, sv_inc, SvIOK, SvIOK_off, SvIOK_on, SvIOK_only, +SvIOK_only, SvIOKp, sv_isa, SvIV, sv_isobject, SvIVX, SvLEN, sv_len, +sv_len, sv_magic, sv_mortalcopy, SvOK, sv_newmortal, sv_no, SvNIOK, SvNIOK_off, SvNIOKp, SvNOK, SvNOK_off, SvNOK_on, SvNOK_only, SvNOK_only, SvNOKp, SvNV, SvNVX, SvPOK, SvPOK_off, SvPOK_on, SvPOK_only, SvPOK_only, SvPOKp, SvPV, SvPVX, SvREFCNT, SvREFCNT_dec, SvREFCNT_inc, SvROK, @@ -2355,6 +2369,8 @@ B<perl_call_sv>, B<perl_call_pv>, B<perl_call_method>, B<perl_call_argv> =over +=item G_VOID + =item G_SCALAR =item G_ARRAY @@ -2363,11 +2379,11 @@ B<perl_call_sv>, B<perl_call_pv>, B<perl_call_method>, B<perl_call_argv> =item G_NOARGS -=item G_EVAL +=item G_EVAL =item G_KEEPERR -=item Determining the Context +=item Determining the Context =back @@ -2399,7 +2415,7 @@ B<perl_call_sv>, B<perl_call_pv>, B<perl_call_method>, B<perl_call_argv> =item Using perl_call_method -=item Using GIMME +=item Using GIMME_V =item Using Perl to dispose of temporaries @@ -2445,6 +2461,22 @@ callback =item AUTHOR +=head2 constant - Perl pragma to declare constants + +=item SYNOPSIS + +=item DESCRIPTION + +=item NOTES + +=item TECHNICAL NOTE + +=item BUGS + +=item AUTHOR + +=item COPYRIGHT + =head2 diagnostics - Perl compiler pragma to force verbose warning diagnostics @@ -2693,10 +2725,14 @@ new, debug =item Standard Exports -timeit(COUNT, CODE), timethis, timethese, timediff, timestr +timeit(COUNT, CODE), timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] ), +timethese ( COUNT, CODEHASHREF, [ STYLE ] ), timediff ( T1, T2 ), timestr ( +TIMEDIFF, [ STYLE, [ FORMAT ]] ) =item Optional Exports +clearcache ( COUNT ), clearallcache ( ), disablecache ( ), enablecache ( ) + =back =item NOTES @@ -2719,6 +2755,271 @@ timeit(COUNT, CODE), timethis, timethese, timediff, timestr =item AUTHOR +=head2 CGI - Simple Common Gateway Interface Class + +=item ABSTRACT + +=item INSTALLATION: + +=item DESCRIPTION + +=over + +=item CREATING A NEW QUERY OBJECT: + +=item CREATING A NEW QUERY OBJECT FROM AN INPUT FILE + +=item FETCHING A LIST OF KEYWORDS FROM THE QUERY: + +=item FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT: + +=item FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER: + +=item SETTING THE VALUE(S) OF A NAMED PARAMETER: + +=item APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER: + +=item IMPORTING ALL PARAMETERS INTO A NAMESPACE: + +=item DELETING A PARAMETER COMPLETELY: + +=item DELETING ALL PARAMETERS: + +=item SAVING THE STATE OF THE FORM TO A FILE: + +=item CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION: + +=item COMPATIBILITY WITH CGI-LIB.PL + +=item CALLING CGI FUNCTIONS THAT TAKE MULTIPLE ARGUMENTS + +=item CREATING THE HTTP HEADER: + +=item GENERATING A REDIRECTION INSTRUCTION + +=item CREATING THE HTML HEADER: + +B<Parameters:>, 4, 5, 6.. + +=item ENDING THE HTML DOCUMENT: + +=back + +=item CREATING FORMS: + +=over + +=item CREATING AN ISINDEX TAG + +=item STARTING AND ENDING A FORM + +B<application/x-www-form-urlencoded>, B<multipart/form-data> + +=item CREATING A TEXT FIELD + +B<Parameters> + +=item CREATING A BIG TEXT FIELD + +=item CREATING A PASSWORD FIELD + +=item CREATING A FILE UPLOAD FIELD + +B<Parameters> + +=item CREATING A POPUP MENU + +=item CREATING A SCROLLING LIST + +B<Parameters:> + +=item CREATING A GROUP OF RELATED CHECKBOXES + +B<Parameters:> + +=item CREATING A STANDALONE CHECKBOX + +B<Parameters:> + +=item CREATING A RADIO BUTTON GROUP + +B<Parameters:> + +=item CREATING A SUBMIT BUTTON + +B<Parameters:> + +=item CREATING A RESET BUTTON + +=item CREATING A DEFAULT BUTTON + +=item CREATING A HIDDEN FIELD + +B<Parameters:> + +=item CREATING A CLICKABLE IMAGE BUTTON + +B<Parameters:>, 3.The third option (-align, optional) is an alignment type, +and may be +TOP, BOTTOM or MIDDLE + +=item CREATING A JAVASCRIPT ACTION BUTTON + +=back + +=item NETSCAPE COOKIES + +1. an expiration time, 2. a domain, 3. a path, 4. a "secure" flag, +B<-name>, B<-value>, B<-path>, B<-domain>, B<-expires>, B<-secure> + +=item WORKING WITH NETSCAPE FRAMES + +1. Create a <Frameset> document, 2. Specify the destination for the +document in the HTTP header, 3. Specify the destination for the document in +the <FORM> tag + +=item DEBUGGING + +=over + +=item DUMPING OUT ALL THE NAME/VALUE PAIRS + +=back + +=item FETCHING ENVIRONMENT VARIABLES + +B<accept()>, B<raw_cookie()>, B<user_agent()>, B<path_info()>, +B<path_translated()>, B<remote_host()>, B<script_name()>Return the script +name as a partial URL, for self-refering +scripts, B<referer()>, B<auth_type ()>, B<server_name ()>, B<virtual_host +()>, B<server_software ()>, B<remote_user ()>, B<user_name ()>, +B<request_method()> + +=item CREATING HTML ELEMENTS: + +=over + +=item PROVIDING ARGUMENTS TO HTML SHORTCUTS + +=item Generating new HTML tags + +=back + +=item IMPORTING CGI METHOD CALLS INTO YOUR NAME SPACE + +B<cgi>, B<form>, B<html2>, B<html3>, B<netscape>, B<shortcuts>, +B<standard>, B<all> + +=item USING NPH SCRIPTS + +In the B<use> statementSimply add ":nph" to the list of symbols to be +imported into your script:, By calling the B<nph()> method:, By using +B<-nph> parameters in the B<header()> and B<redirect()> statements: + +=item AUTHOR INFORMATION + +=item CREDITS + +Matt Heffron (heffron@falstaff.css.beckman.com), James Taylor +(james.taylor@srs.gov), Scott Anguish <sanguish@digifix.com>, Mike Jewell +(mlj3u@virginia.edu), Timothy Shimmin (tes@kbs.citri.edu.au), Joergen Haegg +(jh@axis.se), Laurent Delfosse (delfosse@csgrad1.cs.wvu.edu), Richard +Resnick (applepi1@aol.com), Craig Bishop (csb@barwonwater.vic.gov.au), Tony +Curtis (tc@vcpc.univie.ac.at), Tim Bunce (Tim.Bunce@ig.co.uk), Tom +Christiansen (tchrist@convex.com), Andreas Koenig +(k@franz.ww.TU-Berlin.DE), Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au), +Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu), Stephen Dahmen +(joyfire@inxpress.net), Ed Jordan (ed@fidalgo.net), David Alan Pisoni +(david@cnation.com), ...and many many more.. + +=item A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT + +=item BUGS + +=item SEE ALSO + +=head2 CGI::Apache - Make things work with CGI.pm against Perl-Apache API + +=item SYNOPSIS + +=item DESCRIPTION + +=item NOTE + +=item SEE ALSO + +=item AUTHOR + +=head2 CGI::Carp, B<CGI::Carp> - CGI routines for writing to the HTTPD (or +other) error log + +=item SYNOPSIS + +=item DESCRIPTION + +=item REDIRECTING ERROR MESSAGES + +=item MAKING PERL ERRORS APPEAR IN THE BROWSER WINDOW + +=item CHANGE LOG + +=item AUTHORS + +=item SEE ALSO + +=head2 CGI::Fast - CGI Interface for Fast CGI + +=item SYNOPSIS + +=item DESCRIPTION + +=item OTHER PIECES OF THE PUZZLE + +=item WRITING FASTCGI PERL SCRIPTS + +=item INSTALLING FASTCGI SCRIPTS + +=item USING FASTCGI SCRIPTS AS CGI SCRIPTS + +=item CAVEATS + +=item AUTHOR INFORMATION + +=item BUGS + +=item SEE ALSO + +=head2 CGI::Push - Simple Interface to Server Push + +=item SYNOPSIS + +=item DESCRIPTION + +=item USING CGI::Push + +-last_page, -type, -delay, -cookie, -target, -expires + +=item INSTALLING CGI::Push SCRIPTS + +=item CAVEATS + +=item AUTHOR INFORMATION + +=item BUGS + +=item SEE ALSO + +=head2 CGI::Switch - Try more than one constructors and return the first +object available + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +=item AUTHOR + =head2 CPAN - query, download and build perl modules from CPAN sites =item SYNOPSIS @@ -4067,6 +4368,27 @@ Constants, Macros =item CREATION +=head2 Pod::Html, Pod::HTML - module to convert pod files to HTML + +=item SYNOPSIS + +=item DESCRIPTION + +=item ARGUMENTS + +help, htmlroot, infile, outfile, podroot, podpath, libpods, netscape, +nonetscape, index, noindex, recurse, norecurse, title, verbose + +=item EXAMPLE + +=item AUTHOR + +=item BUGS + +=item SEE ALSO + +=item COPYRIGHT + =head2 Pod::Text - convert POD data to formatted ASCII text =item SYNOPSIS diff --git a/pod/perltoot.pod b/pod/perltoot.pod index a8a77f1c68..c23591245a 100644 --- a/pod/perltoot.pod +++ b/pod/perltoot.pod @@ -311,7 +311,7 @@ be made through methods. Perl doesn't impose restrictions on who gets to use which methods. The public-versus-private distinction is by convention, not syntax. -(Well, unless you use the Alias module described below in +(Well, unless you use the Alias module described below in L</"Data Members as Variables">.) Occasionally you'll see method names beginning or ending with an underscore or two. This marking is a convention indicating that the methods are private to that class alone and sometimes to its @@ -350,7 +350,7 @@ Some might argue that one should go at these this way: } But since these methods are all executing in the class itself, this -may not be critical. There are trade-offs to be made. Using direct +may not be critical. There are tradeoffs to be made. Using direct hash access is faster (about an order of magnitude faster, in fact), and it's more convenient when you want to interpolate in strings. But using methods (the external interface) internally shields not just the users of @@ -1091,7 +1091,7 @@ In version 5.003, there were no predefined methods there, but you could put whatever you felt like into it. However, as of version 5.004 (or some subversive releases, like 5.003_08), -UNIVERSAL has some methods in it already. These are built-in to your Perl +UNIVERSAL has some methods in it already. These are builtin to your Perl binary, so they don't take any extra time to load. Predefined methods include isa(), can(), and VERSION(). isa() tells you whether an object or class "is" another one without having to traverse the hierarchy yourself: @@ -1417,7 +1417,7 @@ is modify %fields. No new functions need be written. I could have avoided the C<_permitted> field entirely, but I wanted to demonstrate how to store a reference to class data on the -object so you wouldn't have to access that class data +object so you wouldn't have to access that class data directly from an object method. =head2 Inherited Autoloaded Data Methods @@ -1624,7 +1624,7 @@ functions in the 5.004 release of Perl in File::stat, Net::hostent, Net::netent, Net::protoent, Net::servent, Time::gmtime, Time::localtime, User::grent, and User::pwent. These modules have a final component that's all lowercase, by convention reserved for compiler pragmas, -because they affect the compilation and change a built-in function. +because they affect the compilation and change a builtin function. They also have the type names that a C programmer would most expect. =head2 Data Members as Variables @@ -1688,7 +1688,7 @@ update value fields in the hash. Convenient, eh? The need for the C<use vars> declaration is because what Alias does is play with package globals with the same name as the fields. To use -globals while C<use strict> is in effect, you have to pre-declare them. +globals while C<use strict> is in effect, you have to predeclare them. These package variables are localized to the block enclosing the attr() call just as if you'd used a local() on them. However, that means that they're still considered global variables with temporary values, just @@ -1726,7 +1726,7 @@ object (one expecting a reference), or vice versa. Z<>From the C++ perspective, all methods in Perl are virtual. This, by the way, is why they are never checked for function -prototypes in the argument list as regular built-in and user-defined +prototypes in the argument list as regular builtin and user-defined functions can be. Because a class is itself something of an object, Perl's classes can be @@ -1737,7 +1737,7 @@ notion, but not the former. =head1 SEE ALSO -The following man pages will doubtless provide more +The following manpages will doubtless provide more background for this one: L<perlmod>, L<perlref>, @@ -1755,7 +1755,7 @@ experiences have mandated its inclusion: Copyright 1996 Tom Christiansen. All Rights Reserved. This work derives in part from the second edition of I<Programming Perl>. -Although destined for release as a man page with the standard Perl +Although destined for release as a manpage with the standard Perl distribution, it is not public domain (nor is any of Perl and its docset: publishers beware). It's expected to someday make its way into a revision of the Camel Book. While it is copyright by me with all rights reserved, diff --git a/pod/perltrap.pod b/pod/perltrap.pod index fd91182d1e..fd41f2ef4d 100644 --- a/pod/perltrap.pod +++ b/pod/perltrap.pod @@ -20,8 +20,8 @@ The English module, loaded via use English; -allows you to refer to special variables (like $RS) as -though they were in B<awk>; see L<perlvar> for details. +allows you to refer to special variables (like C<$/>) with names (like +C<$RS>), as though they were in B<awk>; see L<perlvar> for details. =item * @@ -57,8 +57,8 @@ comparisons. =item * Reading an input line does not split it for you. You get to split it -yourself to an array. And the split() operator has different -arguments. +to an array yourself. And the split() operator has different +arguments than B<awk>'s. =item * @@ -157,7 +157,7 @@ You must use C<elsif> rather than C<else if>. =item * -The C<break> and C<continue> keywords from C become in +The C<break> and C<continue> keywords from C become in Perl C<last> and C<next>, respectively. Unlike in C, these do I<NOT> work within a C<do { } while> construct. @@ -230,18 +230,18 @@ Sharp shell programmers should take note of the following: =item * -The back-tick operator does variable interpolation without regard to +The backtick operator does variable interpolation without regard to the presence of single quotes in the command. =item * -The back-tick operator does no translation of the return value, unlike B<csh>. +The backtick operator does no translation of the return value, unlike B<csh>. =item * Shells (especially B<csh>) do several levels of substitution on each command line. Perl does substitution in only certain constructs -such as double quotes, back-ticks, angle brackets, and search patterns. +such as double quotes, backticks, angle brackets, and search patterns. =item * @@ -274,14 +274,14 @@ context than they do in a scalar one. See L<perldata> for details. =item * Avoid barewords if you can, especially all lowercase ones. -You can't tell by just looking at it whether a bareword is -a function or a string. By using quotes on strings and +You can't tell by just looking at it whether a bareword is +a function or a string. By using quotes on strings and parentheses on function calls, you won't ever get them confused. =item * -You cannot discern from mere inspection which built-ins -are unary operators (like chop() and chdir()) +You cannot discern from mere inspection which builtins +are unary operators (like chop() and chdir()) and which are list operators (like print() and unlink()). (User-defined subroutines can be B<only> list operators, never unary ones.) See L<perlop>. @@ -290,7 +290,7 @@ unary ones.) See L<perlop>. People have a hard time remembering that some functions default to $_, or @ARGV, or whatever, but that others which -you might expect to do not. +you might expect to do not. =item * @@ -299,7 +299,7 @@ operation on that handle. The data read is assigned to $_ only if the file read is the sole condition in a while loop: while (<FH>) { } - while ($_ = <FH>) { }.. + while (defined($_ = <FH>)) { }.. <FH>; # data discarded! =item * @@ -312,14 +312,14 @@ these two constructs are quite different: =item * -The C<do {}> construct isn't a real loop that you can use +The C<do {}> construct isn't a real loop that you can use loop control on. =item * -Use C<my()> for local variables whenever you can get away with -it (but see L<perlform> for where you can't). -Using C<local()> actually gives a local value to a global +Use C<my()> for local variables whenever you can get away with +it (but see L<perlform> for where you can't). +Using C<local()> actually gives a local value to a global variable, which leaves you open to unforeseen side-effects of dynamic scoping. @@ -333,7 +333,7 @@ external name is still an alias for the original. =head2 Perl4 to Perl5 Traps -Practicing Perl4 Programmers should take note of the following +Practicing Perl4 Programmers should take note of the following Perl4-to-Perl5 specific traps. They're crudely ordered according to the following list: @@ -397,11 +397,11 @@ Also note that at least some of these can be caught with B<-w>. =head2 Discontinuance, Deprecation, and BugFix traps Anything that has been discontinued, deprecated, or fixed as -a bug from perl4. +a bug from perl4. =over 4 -=item * Discontinuance +=item * Discontinuance Symbols starting with "_" are no longer forced into package main, except for C<$_> itself (and C<@_>, etc.). @@ -411,11 +411,11 @@ for C<$_> itself (and C<@_>, etc.). package main; print "\$_legacy is ",$_legacy,"\n"; - + # perl4 prints: $_legacy is 1 # perl5 prints: $_legacy is -=item * Deprecation +=item * Deprecation Double-colon is now a valid package separator in a variable name. Thus these behave differently in perl4 vs. perl5, because the packages don't exist. @@ -433,11 +433,11 @@ whether this should be classed as a bug or not. $x = 10 ; print "x=${'x}\n" ; - + # perl4 prints: x=10 # perl5 prints: Can't find string terminator "'" anywhere before EOF -Also see precedence traps, for parsing C<$:>. +Also see precedence traps, for parsing C<$:>. =item * BugFix @@ -446,39 +446,39 @@ context (as the Camel says) rather than list context. sub sub1{return(0,2) } # return a 2-elem array sub sub2{ return(1,2,3)} # return a 3-elem array - @a1 = ("a","b","c","d","e"); + @a1 = ("a","b","c","d","e"); @a2 = splice(@a1,&sub1,&sub2); print join(' ',@a2),"\n"; - + # perl4 prints: a b - # perl5 prints: c d e + # perl5 prints: c d e -=item * Discontinuance +=item * Discontinuance You can't do a C<goto> into a block that is optimized away. Darn. goto marker1; - for(1){ + for(1){ marker1: print "Here I is!\n"; - } - + } + # perl4 prints: Here I is! # perl5 dumps core (SEGV) -=item * Discontinuance +=item * Discontinuance It is no longer syntactically legal to use whitespace as the name of a variable, or as a delimiter for any kind of quote construct. -Double darn. +Double darn. $a = ("foo bar"); $b = q baz ; print "a is $a, b is $b\n"; - + # perl4 prints: a is foo bar, b is baz - # perl5 errors: Bare word found where operator expected + # perl5 errors: Bareword found where operator expected =item * Discontinuance @@ -490,7 +490,7 @@ The archaic while/if BLOCK BLOCK syntax is no longer supported. else { print "False!"; } - + # perl4 prints: True! # perl5 errors: syntax error at test.pl line 1, near "if {" @@ -500,11 +500,11 @@ The C<**> operator now binds more tightly than unary minus. It was documented to work this way before, but didn't. print -4**2,"\n"; - + # perl4 prints: 16 # perl5 prints: -16 -=item * Discontinuance +=item * Discontinuance The meaning of C<foreach{}> has changed slightly when it is iterating over a list which is not an array. This used to assign the list to a @@ -518,12 +518,12 @@ values. $var = 1; } print (join(':',@list)); - + # perl4 prints: ab:abc:bcd:def # perl5 prints: 1:1:bcd:def To retain Perl4 semantics you need to assign your list -explicitly to a temporary array and then iterate over that. For +explicitly to a temporary array and then iterate over that. For example, you might need to change foreach $var (grep(/ab/,@list)){ @@ -556,10 +556,10 @@ would silently accept an B<-e> switch without a following arg. Both of these behaviors have been fixed. perl -e'print "attached to -e"' 'print "separate arg"' - + # perl4 prints: separate arg # perl5 prints: attached to -e - + perl -e # perl4 prints: @@ -574,7 +574,7 @@ number of elements in the resulting list. @x = ('existing'); print push(@x, 'first new', 'second new'); - + # perl4 prints: second new # perl5 prints: 3 @@ -600,7 +600,7 @@ See L<perldiag> for full details. Some error messages will be different. -=item * Discontinuance +=item * Discontinuance Some bugs may have been inadvertently removed. :-) @@ -618,7 +618,7 @@ Note the space between . and = $string . = "more string"; print $string; - + # perl4 prints: more string # perl5 prints: syntax error at - line 1, near ". =" @@ -629,7 +629,7 @@ Better parsing in perl 5 sub foo {} &foo print("hello, world\n"); - + # perl4 prints: hello, world # perl5 prints: syntax error @@ -639,7 +639,7 @@ Better parsing in perl 5 print ($foo == 1) ? "is one\n" : "is zero\n"; - + # perl4 prints: is zero # perl5 warns: "Useless use of a constant in void context" if using -w @@ -657,12 +657,12 @@ operands, or output from same. Formatted output and significant digits print 7.373504 - 0, "\n"; - printf "%20.18f\n", 7.373504 - 0; - + printf "%20.18f\n", 7.373504 - 0; + # Perl4 prints: 7.375039999999996141 7.37503999999999614 - + # Perl5 prints: 7.373504 7.37503999999999614 @@ -676,7 +676,7 @@ If in doubt: use Math::BigInt; -=item * Numerical +=item * Numerical Assignment of return values from numeric equality tests does not work in perl5 when the test evaluates to false (0). @@ -706,7 +706,7 @@ Negative array subscripts now count from the end of the array. @a = (1, 2, 3, 4, 5); print "The third element of the array is $a[3] also expressed as $a[-2] \n"; - + # perl4 prints: The third element of the array is 4 also expressed as # perl5 prints: The third element of the array is 4 also expressed as 4 @@ -715,13 +715,13 @@ Negative array subscripts now count from the end of the array. Setting C<$#array> lower now discards array elements, and makes them impossible to recover. - @a = (a,b,c,d,e); + @a = (a,b,c,d,e); print "Before: ",join('',@a); - $#a =1; + $#a =1; print ", After: ",join('',@a); $#a =3; print ", Recovered: ",join('',@a),"\n"; - + # perl4 prints: Before: abcde, After: ab, Recovered: abcd # perl5 prints: Before: abcde, After: ab, Recovered: ab @@ -729,11 +729,11 @@ impossible to recover. Hashes get defined before use - local($s,@a,%h); + local($s,@a,%h); die "scalar \$s defined" if defined($s); die "array \@a defined" if defined(@a); die "hash \%h defined" if defined(%h); - + # perl4 prints: # perl5 dies: hash %h defined @@ -746,17 +746,17 @@ variable is localized subsequent to the assignment *b = *a; local(@a); print @b,"\n"; - + # perl4 prints: This is Perl 4 # perl5 prints: - + # Another example - + *fred = *barney; # fred is aliased to barney @barney = (1, 2, 4); # @fred; print "@fred"; # should print "1, 2, 4" - + # perl4 prints: 1 2 4 # perl5 prints: In string, @fred now must be written as \@fred @@ -770,7 +770,7 @@ does to auto(magic)increment. print ++$x," : "; print -$x," : "; print ++$x,"\n"; - + # perl4 prints: aab : -0 : 1 # perl5 prints: aab : -aab : aac @@ -788,13 +788,13 @@ perl 4 lets you modify constants: $_[0] = "m"; print " after: $_[0]\n"; } - + # perl4: # before: x after: m # before: a after: m # before: m after: m # before: m after: m - + # Perl5: # before: x after: m # Modification of a read-only value attempted at foo.pl line 12. @@ -805,7 +805,7 @@ perl 4 lets you modify constants: The behavior is slightly different for: print "$x", defined $x - + # perl 4: 1 # perl 5: <no output, $x is not called into existence> @@ -823,7 +823,7 @@ that perl4 exhibits for only scalars. sub test { local( *theArgument ) = @_; local( %aNewLocal ); # perl 4 != 5.001l,m - $aNewLocal{"aKey"} = "this should never appear"; + $aNewLocal{"aKey"} = "this should never appear"; print "SUB: ", $theArgument{"aKey"}, "\n"; $aNewLocal{"aKey"} = "level $GlobalLevel"; # what should print $GlobalLevel++; @@ -831,14 +831,14 @@ that perl4 exhibits for only scalars. &test( *aNewLocal ); } } - + # Perl4: # MAIN:global value # SUB: global value # SUB: level 0 # SUB: level 1 # SUB: level 2 - + # Perl5: # MAIN:global value # SUB: global value @@ -862,19 +862,19 @@ context. This means you can interpolate list values now. @<<<<< @||||| @>>>>> @fmt; . - write; - + write; + # perl4 errors: Please use commas to separate fields in file # perl5 prints: foo bar baz =item * (scalar context) -The C<caller()> function now returns a false value in a scalar context -if there is no caller. This lets library files determine if they're +The C<caller()> function now returns a false value in a scalar context +if there is no caller. This lets library files determine if they're being required. caller() ? (print "You rang?\n") : (print "Got a 0\n"); - + # perl4 errors: There is no caller # perl5 prints: Got a 0 @@ -886,7 +886,7 @@ scalar context to its arguments. @y= ('a','b','c'); $x = (1, 2, @y); print "x = $x\n"; - + # Perl4 prints: x = c # Thinks list context interpolates list # Perl5 prints: x = 3 # Knows scalar uses length of list @@ -898,15 +898,15 @@ This test could be added to t/op/sprintf.t @z = ('%s%s', 'foo', 'bar'); $x = sprintf(@z); if ($x eq 'foobar') {print "ok 2\n";} else {print "not ok 2 '$x'\n";} - + # perl4 prints: ok 2 # perl5 prints: not ok 2 C<printf()> works fine, though: printf STDOUT (@z); - print "\n"; - + print "\n"; + # perl4 prints: foobar # perl5 prints: foobar @@ -941,7 +941,7 @@ These are now semantic errors because of precedence: print "n is $n, "; $m = keys %map + 2; # number of items in hash plus 2 print "m is $m\n"; - + # perl4 prints: n is 3, m is 6 # perl5 errors and fails to compile @@ -963,7 +963,7 @@ would be erroneously parsed as On the other hand, - $a += /foo/ ? 1 : 2; + $a += /foo/ ? 1 : 2; now works as a C programmer would expect. @@ -975,7 +975,7 @@ is now incorrect. You need parentheses around the filehandle. Otherwise, perl5 leaves the statement as its default precedence: open(FOO || die); - + # perl4 opens or dies # perl5 errors: Precedence problem: open FOO should be open(FOO) @@ -985,16 +985,16 @@ perl4 gives the special variable, C<$:> precedence, where perl5 treats C<$::> as main C<package> $a = "x"; print "$::a"; - + # perl 4 prints: -:a # perl 5 prints: x =item * Precedence -concatenation precedence over filetest operator? +concatenation precedence over filetest operator? + + -e $foo .= "q" - -e $foo .= "q" - # perl4 prints: no output # perl5 prints: Can't modify -e in concatenation @@ -1021,14 +1021,14 @@ All types of RE traps. =item * Regular Expression C<s'$lhs'$rhs'> now does no interpolation on either side. It used to -interpolate C<$lhs> but not C<$rhs>. (And still does not match a literal +interpolate C<$lhs> but not C<$rhs>. (And still does not match a literal '$' in string) $a=1;$b=2; $string = '1 2 $a $b'; $string =~ s'$a'$b'; print $string,"\n"; - + # perl4 prints: $b 2 $a $b # perl5 prints: 1 2 $a $b @@ -1043,7 +1043,7 @@ state of the searched string is lost) &doit("blah"); } sub doit{local($_) = shift; print "Got $_ "} - + # perl4 prints: blah blah blah # perl5 prints: infinite loop blah... @@ -1072,7 +1072,7 @@ the whole match, just like C<$&>. Perl5 does not. "abcdef" =~ /b.*e/; print "\$+ = $+\n"; - + # perl4 prints: bcde # perl5 prints: @@ -1083,7 +1083,7 @@ substitution now returns the null string if it fails $string = "test"; $value = ($string =~ s/foo//); print $value, "\n"; - + # perl4 prints: 0 # perl5 prints: @@ -1091,13 +1091,13 @@ Also see L<Numerical Traps> for another example of this new feature. =item * Regular Expression -C<s`lhs`rhs`> (using back-ticks) is now a normal substitution, with no -back-tick expansion +C<s`lhs`rhs`> (using backticks) is now a normal substitution, with no +backtick expansion $string = ""; $string =~ s`^`hostname`; print $string, "\n"; - + # perl4 prints: <the local hostname> # perl5 prints: hostname @@ -1106,7 +1106,7 @@ back-tick expansion Stricter parsing of variables used in regular expressions s/^([^$grpc]*$grpc[$opt$plus$rep]?)//o; - + # perl4: compiles w/o error # perl5: with Scalar found where operator expected ..., near "$opt$plus" @@ -1114,12 +1114,12 @@ an added component of this example, apparently from the same script, is the actual value of the s'd string after the substitution. C<[$opt]> is a character class in perl4 and an array subscript in perl5 - $grpc = 'a'; + $grpc = 'a'; $opt = 'r'; $_ = 'bar'; s/^([^$grpc]*$grpc[$opt]?)/foo/; print ; - + # perl4 prints: foo # perl5 prints: foobar @@ -1134,11 +1134,11 @@ repeatedly, like C</x/> or C<m!x!>. if( &match() ) { # m?x? matches more then once print "perl4\n"; - } else { + } else { # m?x? matches only once - print "perl5\n"; + print "perl5\n"; } - + # perl4 prints: perl4 # perl5 prints: perl5 @@ -1156,7 +1156,7 @@ found using the C<pos()> function--see L<perlfunc/pos>). print $1 while ($test =~ /(o)/g); # pos $test = 0; # to get old behavior } - + # perl4 prints: oooooo # perl5.004 prints: oo @@ -1181,7 +1181,7 @@ calls if a subroutine by that name is defined before the compiler sees them. sub SeeYa { warn"Hasta la vista, baby!" } $SIG{'TERM'} = SeeYa; print "SIGTERM is now $SIG{'TERM'}\n"; - + # perl4 prints: SIGTERM is main'SeeYa # perl5 prints: SIGTERM is now main::1 @@ -1192,10 +1192,10 @@ Use B<-w> to catch this one reverse is no longer allowed as the name of a sort subroutine. sub reverse{ print "yup "; $a <=> $b } - print sort reverse a,b,c; - + print sort reverse a,b,c; + # perl4 prints: yup yup yup yup abc - # perl5 prints: abc + # perl5 prints: abc =item * warn() won't let you specify a filehandle. @@ -1205,7 +1205,7 @@ filehandle in perl4. With perl5 it does not. warn STDERR "Foo!"; # perl4 prints: Foo! - # perl5 prints: String found where operator expected + # perl5 prints: String found where operator expected =back @@ -1215,47 +1215,47 @@ filehandle in perl4. With perl5 it does not. =item * (SysV) -Under HPUX, and some other SysV OS's, one had to reset any signal handler, -within the signal handler function, each time a signal was handled with -perl4. With perl5, the reset is now done correctly. Any code relying +Under HPUX, and some other SysV OSes, one had to reset any signal handler, +within the signal handler function, each time a signal was handled with +perl4. With perl5, the reset is now done correctly. Any code relying on the handler _not_ being reset will have to be reworked. Since version 5.002, Perl uses sigaction() under SysV. sub gotit { - print "Got @_... "; - } + print "Got @_... "; + } $SIG{'INT'} = 'gotit'; - + $| = 1; $pid = fork; if ($pid) { kill('INT', $pid); sleep(1); kill('INT', $pid); - } else { + } else { while (1) {sleep(10);} - } - + } + # perl4 (HPUX) prints: Got INT... # perl5 (HPUX) prints: Got INT... Got INT... =item * (SysV) -Under SysV OS's, C<seek()> on a file opened to append C<E<gt>E<gt>> now does -the right thing w.r.t. the fopen() man page. e.g., - When a file is opened +Under SysV OSes, C<seek()> on a file opened to append C<E<gt>E<gt>> now does +the right thing w.r.t. the fopen() manpage. e.g., - When a file is opened for append, it is impossible to overwrite information already in the file. open(TEST,">>seek.test"); - $start = tell TEST ; + $start = tell TEST ; foreach(1 .. 9){ print TEST "$_ "; } $end = tell TEST ; seek(TEST,$start,0); print TEST "18 characters here"; - + # perl4 (solaris) seek.test has: 18 characters here # perl5 (solaris) seek.test has: 1 2 3 4 5 6 7 8 9 18 characters here @@ -1274,8 +1274,8 @@ within certain expressions, statements, contexts, or whatever. @ now always interpolates an array in double-quotish strings. - print "To: someone@somewhere.com\n"; - + print "To: someone@somewhere.com\n"; + # perl4 prints: To:someone@somewhere.com # perl5 errors : In string, @somewhere now must be written as \@somewhere @@ -1286,7 +1286,7 @@ Double-quoted strings may no longer end with an unescaped $ or @. $foo = "foo$"; $bar = "bar@"; print "foo is $foo, bar is $bar\n"; - + # perl4 prints: foo is foo$, bar is bar@ # perl5 errors: Final $ should be \$ or $name @@ -1322,8 +1322,8 @@ works fine, however. =item * Interpolation -Creation of hashes on the fly with C<eval "EXPR"> now requires either both -C<$>'s to be protected in the specification of the hash name, or both curlies +Creation of hashes on the fly with C<eval "EXPR"> now requires either both +C<$>'s to be protected in the specification of the hash name, or both curlies to be protected. If both curlies are protected, the result will be compatible with perl4 and perl5. This is a very common practice, and should be changed to use the block form of C<eval{}> if possible. @@ -1366,13 +1366,13 @@ causes the following result: perl4 programs which unconsciously rely on the bugs in earlier perl versions. perl -e '$bar=q/not/; print "This is $foo{$bar} perl5"' - + # perl4 prints: This is not perl5 # perl5 prints: This is perl5 =item * Interpolation -You also have to be careful about array references. +You also have to be careful about array references. print "$foo{" @@ -1385,7 +1385,7 @@ Similarly, watch out for: $foo = "array"; print "\$$foo{bar}\n"; - + # perl4 prints: $array{bar} # perl5 prints: $ @@ -1402,9 +1402,9 @@ C<qq()> string passed to C<eval> \$count++; } ); - + # perl4 runs this ok - # perl5 prints: Can't find string terminator ")" + # perl5 prints: Can't find string terminator ")" =back @@ -1463,7 +1463,7 @@ If the file doit.pl has: sub foo { $rc = do "./do.pl"; return 8; - } + } print &foo, "\n"; And the do.pl file has the following single line: @@ -1473,12 +1473,12 @@ And the do.pl file has the following single line: Running doit.pl gives the following: # perl 4 prints: 3 (aborts the subroutine early) - # perl 5 prints: 8 + # perl 5 prints: 8 Same behavior if you replace C<do> with C<require>. =back -As always, if any of these are ever officially declared as bugs, +As always, if any of these are ever officially declared as bugs, they'll be fixed and removed. diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 1406858331..b569465d15 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -52,7 +52,7 @@ The default input and pattern-searching space. The following pairs are equivalent: while (<>) {...} # equivalent in only while! - while ($_ = <>) {...} + while (defined($_ = <>)) {...} /^Subject:/ $_ =~ /^Subject:/ @@ -63,7 +63,7 @@ equivalent: chop chop($_) -Here are the places where Perl will assume $_ even if you +Here are the places where Perl will assume $_ even if you don't use it: =over 3 @@ -83,16 +83,16 @@ Various list functions like print() and unlink(). The pattern matching operations C<m//>, C<s///>, and C<tr///> when used without an C<=~> operator. -=item * +=item * The default iterator variable in a C<foreach> loop if no other variable is supplied. -=item * +=item * The implicit iterator variable in the grep() and map() functions. -=item * +=item * The default place to put an input record when a C<E<lt>FHE<gt>> operation's result is tested by itself as the sole criterion of a C<while> @@ -108,7 +108,7 @@ test. Note that outside of a C<while> test, this will not happen. =item $E<lt>I<digit>E<gt> -Contains the sub-pattern from the corresponding set of parentheses in +Contains the subpattern from the corresponding set of parentheses in the last pattern matched, not counting patterns matched in nested blocks that have been exited already. (Mnemonic: like \digit.) These variables are all read-only. @@ -162,7 +162,7 @@ This variable is read-only. =item $* -Set to 1 to do multi-line matching within a string, 0 to tell Perl +Set to 1 to do multiline matching within a string, 0 to tell Perl that it can assume that strings contain a single line, for the purpose of optimizing pattern matches. Pattern matches on strings containing multiple newlines can produce confusing results when "C<$*>" is 0. Default @@ -199,15 +199,15 @@ number.) The input record separator, newline by default. Works like B<awk>'s RS variable, including treating empty lines as delimiters if set to the -null string. (Note: An empty line cannot contain any spaces or -tabs.) You may set it to a multicharacter string to match a -multi-character delimiter. Note that setting it to C<"\n\n"> means -something slightly different than setting it to C<"">, if the file -contains consecutive empty lines. Setting it to C<""> will treat two -or more consecutive empty lines as a single empty line. Setting it to -C<"\n\n"> will blindly assume that the next input character belongs to -the next paragraph, even if it's a newline. (Mnemonic: / is used to -delimit line boundaries when quoting poetry.) +null string. (Note: An empty line cannot contain any spaces or tabs.) +You may set it to a multicharacter string to match a multicharacter +delimiter, or to C<undef> to read to end of file. Note that setting it +to C<"\n\n"> means something slightly different than setting it to +C<"">, if the file contains consecutive empty lines. Setting it to +C<""> will treat two or more consecutive empty lines as a single empty +line. Setting it to C<"\n\n"> will blindly assume that the next input +character belongs to the next paragraph, even if it's a newline. +(Mnemonic: / is used to delimit line boundaries when quoting poetry.) undef $/; $_ = <FH>; # whole file now here @@ -222,10 +222,10 @@ better for something :-) =item $| -If set to nonzero, forces a flush after every write or print on the +If set to nonzero, forces a flush right away and after every write or print on the currently selected output channel. Default is 0 (regardless of whether the channel is actually buffered by the system or not; C<$|> tells you -only whether you've asked Perl explicitly to flush after each write). +only whether you've asked Perl explicitly to flush after each write). Note that STDOUT will typically be line buffered if output is to the terminal and block buffered otherwise. Setting this variable is useful primarily when you are outputting to a pipe, such as when you are running @@ -279,7 +279,7 @@ is a space. (Mnemonic: obvious, I think.) =item $; -The subscript separator for multi-dimensional array emulation. If you +The subscript separator for multidimensional array emulation. If you refer to a hash element as $foo{$a,$b,$c} @@ -302,7 +302,7 @@ keys contain binary data there might not be any safe value for "C<$;>". semi-semicolon. Yeah, I know, it's pretty lame, but "C<$,>" is already taken for something more important.) -Consider using "real" multi-dimensional arrays. +Consider using "real" multidimensional arrays. =item $OFMT @@ -372,7 +372,7 @@ appended. (Mnemonic: points to top of page.) =item $: The current set of characters after which a string may be broken to -fill continuation fields (starting with ^) in a format. Default is +fill continuation fields (starting with ^) in a format. Default is S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in poetry is a part of a line.) @@ -399,7 +399,7 @@ L<perlfunc/formline()>. =item $? -The status returned by the last pipe close, back-tick (C<``>) command, +The status returned by the last pipe close, backtick (C<``>) command, or system() operator. Note that this is the status word returned by the wait() system call (or else is made up to look like it). Thus, the exit value of the subprocess is actually (C<$? E<gt>E<gt> 8>), and @@ -459,7 +459,7 @@ the syntax error "at"?) Note that warning messages are not collected in this variable. You can, however, set up a routine to process warnings by setting C<$SIG{__WARN__}> -below. +as described below. =item $PROCESS_ID @@ -531,7 +531,8 @@ multiple groups. =item $0 Contains the name of the file containing the Perl script being -executed. Assigning to "C<$0>" modifies the argument area that the ps(1) +executed. On some operating systems +assigning to "C<$0>" modifies the argument area that the ps(1) program sees. This is more useful as a way of indicating the current program state than it is for hiding the program you're running. (Mnemonic: same as B<sh> and B<ksh>.) @@ -552,24 +553,15 @@ discouraged. =item $] -The string printed out when you say C<perl -v>. -(This is currently I<BROKEN>). -It can be used to -determine at the beginning of a script whether the perl interpreter -executing the script is in the right range of versions. If used in a -numeric context, returns the version + patchlevel / 1000. Example: - - # see if getc is available - ($version,$patchlevel) = - $] =~ /(\d+\.\d+).*\nPatch level: (\d+)/; - print STDERR "(No filename completion available.)\n" - if $version * 1000 + $patchlevel < 2016; - -or, used numerically, +The version + patchlevel / 1000 of the Perl interpreter. This variable +can be used to determine whether the Perl interpreter executing a +script is in the right range of versions. (Mnemonic: Is this version +of perl in the right bracket?) Example: warn "No checksumming!\n" if $] < 3.019; -(Mnemonic: Is this version of perl in the right bracket?) +See also the documentation of C<use VERSION> and C<require VERSION> +for a convenient way to fail if the Perl interpreter is too old. =item $DEBUGGING @@ -704,7 +696,7 @@ the Perl script. Here are some other examples: $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? The one marked scary is problematic because it's a bareword, which means -sometimes it's a string representing the function, and sometimes it's +sometimes it's a string representing the function, and sometimes it's going to call the subroutine call right then and there! Best to be sure and quote it or take a reference to it. *Plumber works too. See L<perlsub>. @@ -749,9 +741,9 @@ By default, running out of memory it is not trappable. However, if compiled for this, Perl may use the contents of C<$^M> as an emergency pool after die()ing with this message. Suppose that your Perl were compiled with -DEMERGENCY_SBRK and used Perl's malloc. Then - + $^M = 'a' x (1<<16); - + would allocate a 64K buffer for use when in emergency. See the F<INSTALL> file for information on how to enable this option. As a disincentive to casual use of this advanced feature, there is no L<English> long name for diff --git a/pod/perlxs.pod b/pod/perlxs.pod index ebead849dc..13ad669531 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -172,7 +172,7 @@ explicitly. If PPCODE: directive is not used, C<void> return value should be used only for subroutines which do not return a value, I<even if> CODE: -directive is used which sets ST(0) explicitly. +directive is used which sets ST(0) explicitly. Older versions of this document recommended to use C<void> return value in such cases. It was discovered that this could lead to @@ -289,7 +289,7 @@ its parameters. The Perl usage is given first. $status = rpcb_gettime( "localhost", $timep ); -The XSUB follows. +The XSUB follows. bool_t rpcb_gettime(host,timep) @@ -319,7 +319,7 @@ above, this keyword does not affect the way the compiler handles RETVAL. =head2 The NO_INIT Keyword The NO_INIT keyword is used to indicate that a function -parameter is being used as only an output value. The B<xsubpp> +parameter is being used only as an output value. The B<xsubpp> compiler will normally generate code to read the values of all function parameters from the argument stack and assign them to C variables upon entry to the function. NO_INIT @@ -328,7 +328,7 @@ output rather than for input and that they will be handled before the function terminates. The following example shows a variation of the rpcb_gettime() function. -This function uses the timep variable as only an output variable and does +This function uses the timep variable only as an output variable and does not care about its initial contents. bool_t @@ -694,7 +694,7 @@ To disable version checking: =head2 The PROTOTYPES: Keyword The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and -C<-noprototypes> options. This keyword overrides the command-line options. +C<-noprototypes> options. This keyword overrides the command line options. Prototypes are enabled by default. When prototypes are enabled XSUBs will be given Perl prototypes. This keyword may be used multiple times in an XS module to enable and disable prototypes for different parts of the module. diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod index e31de334a8..cdd4344b78 100644 --- a/pod/perlxstut.pod +++ b/pod/perlxstut.pod @@ -55,7 +55,7 @@ to use the following line: =item * -This document assumes that the executable named "perl" is Perl version 5. +This document assumes that the executable named "perl" is Perl version 5. Some systems may have installed Perl version 5 as "perl5". =back @@ -145,7 +145,7 @@ And the Mytest.xs file should look something like this: #ifdef __cplusplus } #endif - + PROTOTYPES: DISABLE MODULE = Mytest PACKAGE = Mytest @@ -185,11 +185,11 @@ example only, we'll create a special test script. Create a file called hello that looks like this: #! /opt/perl5/bin/perl - + use ExtUtils::testlib; - + use Mytest; - + Mytest::hello(); Now we run the script and we should see the following output: @@ -222,7 +222,7 @@ the four lines starting at the "CODE:" line to not be indented. However, for readability purposes, it is suggested that you indent them 8 spaces (or one normal tab stop). -Now re-run make to rebuild our new shared library. +Now rerun make to rebuild our new shared library. Now perform the same steps as before, generating a Makefile from the Makefile.PL file, and running make. @@ -453,7 +453,7 @@ this behavior is tolerated. The next example will show how to do this. =head2 EXAMPLE 4 In this example, we'll now begin to write XSUBs that will interact with -pre-defined C libraries. To begin with, we will build a small library of +predefined C libraries. To begin with, we will build a small library of our own, then let h2xs write our .pm and .xs files for us. Create a new directory called Mytest2 at the same level as the directory @@ -475,7 +475,7 @@ Also create a file mylib.c that looks like this: #include <stdlib.h> #include "./mylib.h" - + double foo(a, b, c) int a; @@ -705,7 +705,7 @@ definition is placed. There is absolutely no excuse for not documenting your extension. Documentation belongs in the .pm file. This file will be fed to pod2man, -and the embedded documentation will be converted to the man page format, +and the embedded documentation will be converted to the manpage format, then placed in the blib directory. It will be copied to Perl's man page directory when the extension is installed. @@ -718,7 +718,7 @@ See L<perlpod> for more information about the pod format. =head2 INSTALLING YOUR EXTENSION Once your extension is complete and passes all its tests, installing it -is quite simple: you simply run "make install". You will either need +is quite simple: you simply run "make install". You will either need to have write permission into the directories where Perl is installed, or ask your system administrator to run the make for you. diff --git a/pod/pod2html.PL b/pod/pod2html.PL index 1c53f6c090..de36cd7fc9 100644 --- a/pod/pod2html.PL +++ b/pod/pod2html.PL @@ -32,655 +32,147 @@ $Config{startperl} # In the following, perl variables are not expanded during extraction. print OUT <<'!NO!SUBS!'; +=pod -# -# pod2html - convert pod format to html -# Version 1.21 -# usage: pod2html [podfiles] -# Will read the cwd and parse all files with .pod extension -# if no arguments are given on the command line. -# -# Many helps, suggestions, and fixes from the perl5 porters, and all over. -# Bill Middleton - wjm@metronet.com -# -# Please send patches/fixes/features to me -# - -require 'find.pl'; - -*RS = */; -*ERRNO = *!; - - -################################################################################ -# Invoke with various levels of debugging possible -################################################################################ -while ($ARGV[0] =~ /^-d(.*)/) { - shift; - $Debug{ lc($1 || shift) }++; -} - -# ck for podnames on command line -while ($ARGV[0]) { - push(@Pods,shift); -} - -################################################################################ -# CONFIGURE - change the following to suit your OS and taste -################################################################################ -# The beginning of the url for the anchors to the other sections. -# Edit $type to suit. It's configured for relative url's now. -# Other possibilities are: -# $type = '<A HREF="file://localhost/usr/local/htmldir/'; # file url -# $type = '<A HREF="http://www.bozo.com/perl/manual/html/' # server - -$type = '<A HREF="'; - -################################################################################ -# location of all podfiles unless on command line -# $installprivlib='HD:usr:local:lib:perl5'; # uncomment for Mac -# $installprivlib='C:\usr\local\lib\perl5'; # uncomment for DOS (I hope) -# $installprivlib='/usr/local/lib/perl5'; # Unix -$installprivlib="./"; # Standard perl pod directory for intallation - -################################################################################ -# Where to write out the html files -# $installhtmldir='HD:usr:local:lib:perl5:html'; # uncomment for Mac -# $installhtmldir='C:\usr\local\lib\perl5\html'; # uncomment for DOS (I hope) -$installhtmldir = './'; - -# test for validness - -if(!(-d $installhtmldir)){ - print "Installation directory $installhtmldir does not exist, using cwd\n"; - print "Hit ^C now to edit this script and configure installhtmldir\n"; - $installhtmldir = '.'; -} - -################################################################################ -# the html extension, change to htm for DOS - -$htmlext = "html"; - -################################################################################ -# arbitrary name for this group of pods - -$package = "perl"; - -################################################################################ -# look in these pods for links to things not found within the current pod -# be careful tho, namespace collisions cause stupid links - -@inclusions = qw[ perlfunc perlvar perlrun perlop ]; - -################################################################################ -# Directory path separator -# $sep= ":"; # uncomment for Mac -# $sep= "\"; # uncomment for DOS - -$sep= "/"; - -################################################################################ -# Create 8.3 html files if this equals 1 - -$DOSify=0; - -################################################################################ -# Create maximum 32 character html files if this equals 1 -$MACify=0; - -################################################################################ -# END CONFIGURE -# Beyond here be dragons. :-) -################################################################################ - -$A = {}; # The beginning of all things - -unless(@Pods){ - find($installprivlib); - splice(@Pods,$#Pods+1,0,@modpods);; -} - -@Pods or die "aak, expected pods"; -open(INDEX,">".$installhtmldir.$sep."index.".$htmlext) or - (die "cant open index.$htmlext"); -print INDEX "\n<HTML>\n<HEAD>\n<TITLE>Index of all pods for $package</TITLE></HEAD>\n<BODY>\n"; -print INDEX "<H1>Index of all pods for $package</H1>\n<hr><UL>\n"; -# loop twice through the pods, first to learn the links, then to produce html -for $count (0,1) { - print STDERR "Scanning pods...\n" unless $count; -loop1: - foreach $podfh ( @Pods ) { - $didindex = 0; - $refname = $podfh; - $refname =~ s/\Q$installprivlib${sep}\E?//; - $refname =~ s/${sep}/::/g; - $refname =~ s/\.p(m|od)$//; - $refname =~ s/^pod:://; - $savename = $refname; - $refname =~ s/::/_/g; - if($DOSify && !$count){ # shorten the name for DOS - (length($refname) > 8) and ( $refname = substr($refname,0,8)); - while(defined($DosNames{$refname})){ - @refname=split(//,$refname); - # allow 25 of em - ($refname[$#refname] eq "z") and ($refname[$#refname] = "a"); - $refname[$#refname]++; - $refname=join('',@refname); - $refname =~ s/\W/_/g; - } - $DosNames{$refname} = 1; - $Podnames{$savename} = $refname . ".$htmlext"; - } - elsif(!$DOSify and !$count){ - $Podnames{$savename} = $refname . ".$htmlext"; - } - $pod = $savename; - Debug("files", "opening 2 $podfh" ); - print "Creating $Podnames{$savename} from $podfh\n" if $count; - $RS = "\n="; # grok pods by item (Nonstandard but effecient) - open($podfh,"<".$podfh) || die "can't open $podfh: $ERRNO"; - @all = <$podfh>; - close($podfh); - $RS = "\n"; - ($all[0] =~ s/^=//) || pop(@all); - for ($i=0;$i <= $#all;$i++){ splice(@all,$i+1,1) unless - (($all[$i] =~ s/=$//) && ($all[$i+1] !~ /^cut/)) ; # whoa.. - } - $in_list = 0; - unless (grep(/NAME/,@all)){ - print STDERR "NAME header not found in $podfh, skipping\n"; - #delete($Podnames{$savename}); - next loop1; - } - if ($count) { - next unless length($Podnames{$savename}); - open(HTML,">".$installhtmldir.$sep.$Podnames{$savename}) or - (die "can't create $Podnames{$savename}: $ERRNO"); - print HTML "<HTML><HEAD>"; - print HTML "<TITLE>$refname</TITLE>\n</HEAD>\n<BODY>"; - } - - for ($i = 0; $i <= $#all; $i++) { # decide what to do with each chunk - $all[$i] =~ /^(\w+)\s*(.*)\n?([^\0]*)$/ ; - ($cmd, $title, $rest) = ($1,$2,$3); - if(length($cmd)){$cutting =0;} - next if $cutting; - if(($title =~ /NAME/) and ($didindex == 0) and $count){ - print INDEX "<LI><A HREF=\"$Podnames{$savename}\">$rest</A>\n"; - $didindex=1; - } - if ($cmd eq "item") { - if ($count ) { # producing html - do_list("over",$all[$i],\$in_list,\$depth) unless $depth; - do_item($title,$rest,$in_list); - } - else { - # scan item - scan_thing("item",$title,$pod); - } - } - elsif ($cmd =~ /^head([12])/) { - $num = $1; - if ($count) { # producing html - do_hdr($num,$title,$rest,$depth); - } - else { - # header scan - scan_thing($cmd,$title,$pod); # skip head1 - } - } - elsif ($cmd =~ /^over/) { - $count and $depth and do_list("over",$all[$i+1],\$in_list,\$depth); - } - elsif ($cmd =~ /^back/) { - if ($count) { # producing html - ($depth) or next; # just skip it - do_list("back",$all[$i+1],\$in_list,\$depth); - do_rest("$title$rest"); - } - } - elsif ($cmd =~ /^cut/) { - next; - } - elsif ($cmd =~ /^for/) { # experimental pragma html - if ($count) { # producing html - if ($title =~ s/^html//) { - $in_html =1; - do_rest("$title$rest"); - } - } - } - elsif ($cmd =~ /^begin/) { # experimental pragma html - if ($count) { # producing html - if ($title =~ s/^html//) { - print HTML $title,"\n",$rest; - } - elsif ($title =~ /^end/) { - next; - } - } - } - elsif ($Debug{"misc"}) { - warn("unrecognized header: $cmd"); - } - } - # close open lists without '=back' stmts - if ($count) { # producing html - while ($depth) { - do_list("back",$all[$i+1],\$in_list,\$depth); - } - print HTML "\n</BODY>\n</HTML>\n"; - } - } -} -print INDEX "\n</UL></BODY>\n</HTML>\n"; - -sub do_list{ # setup a list type, depending on some grok logic - my($which,$next_one,$list_type,$depth) = @_; - my($key); - if ($which eq "over") { - unless ($next_one =~ /^item\s+(.*)/) { - warn "Bad list, $1\n" if $Debug{"misc"}; - } - $key = $1; - - if ($key =~ /^1\.?/) { - $$list_type = "OL"; - } elsif ($key =~ /\*\s*$/) { - $$list_type = "UL"; - } elsif ($key =~ /\*?\s*\w/) { - $$list_type = "DL"; - } else { - warn "unknown list type for item $key" if $Debug{"misc"}; - } - - print HTML qq{\n}; - print HTML qq{<$$list_type>}; - $$depth++; - } - elsif ($which eq "back") { - print HTML qq{\n</$$list_type>\n}; - $$depth--; - } -} - -sub do_hdr{ # headers - my($num,$title,$rest,$depth) = @_; - my($savename,$restofname); - print HTML qq{<p><hr>\n} if $num == 1; - ($savename = $title) =~ s/^(\w+)([\s,]+.*)/$1/; - $restofname = $2; - (defined($Podnames{$savename})) ? ($savename = $savename) : ($savename = 0); - process_thing(\$title,"NAME"); - print HTML qq{\n<H$num> }; - if($savename){ - print HTML "<A HREF=\"$Podnames{$savename}\">$savename$restofname</A>"; - } - else{ - print HTML $title; - } - print HTML qq{</H$num>\n}; - do_rest($rest); -} - -sub do_item{ # list items - my($title,$rest,$list_type) = @_; - my $bullet_only; - $bullet_only = ($title eq '*' and $list_type eq 'UL') ? 1 : 0; - my($savename); - $savename = $title; - (defined($Podnames{$savename})) ? ($savename = $savename) : ($savename = 0); - process_thing(\$title,"NAME"); - if ($list_type eq "DL") { - print HTML qq{\n<DT>\n}; - if($savename){ - print HTML "<A HREF=\"$Podnames{$savename}\">$savename $rest</A>\n</DT>"; - } - - else{ - (print HTML qq{\n<STRONG>\n}) unless ($title =~ /STRONG/); - print HTML $title; - if($title !~ /STRONG/){ - print HTML "\n</STRONG></DT>\n"; - } else { - print HTML "</DT>\n"; - } - } - print HTML qq{<DD>\n}; - } - else { - print HTML qq{\n<LI>}; - unless ($bullet_only or $list_type eq "OL") { - if($savename){ - print HTML "<A HREF=\"$savename.$htmlext\">$savename</A>"; - } - else{ - print HTML $title,"\n"; - } - } - } - do_rest($rest); -} - -sub do_rest{ # the rest of the chunk handled here - my($rest) = @_; - my(@lines,$p,$q,$line,,@paras,$inpre); - @paras = split(/\n\n\n*/,$rest); - for ($p = 0; $p <= $#paras; $p++) { - $paras[$p] =~ s/^\n//mg; - @lines = split(/\n/,$paras[$p]); - if ($in_html) { # handle =for html paragraphs - print HTML $paras[0]; - $in_html = 0; - next; - } - elsif ($lines[0] =~ /^\s+\w*\t.*/) { # listing or unordered list - print HTML qq{<UL>}; - foreach $line (@lines) { - ($line =~ /^\s+(\w*)\t(.*)/) && (($key,$rem) = ($1,$2)); - print HTML defined($Podnames{$key}) - ? "<LI>$type$Podnames{$key}\">$key<\/A>\t$rem</LI>\n" - : "<LI>$line</LI>\n"; - } - print HTML qq{</UL>\n}; - } - elsif ($lines[0] =~ /^\s/) { # preformatted code - if ($paras[$p] =~/>>|<</) { - print HTML qq{\n<PRE>\n}; - $inpre=1; - } - else { # Still cant beat XMP. Yes, I know - print HTML qq{\n<XMP>\n}; # it's been obsoleted... suggestions? - $inpre = 0; - } - while (defined($paras[$p])) { - @lines = split(/\n/,$paras[$p]); - foreach $q (@lines) { # mind your p's and q's here :-) - if ($paras[$p] =~ />>|<</) { - if ($inpre) { - process_thing(\$q,"HTML"); - } - else { - print HTML qq{\n</XMP>\n}; - print HTML qq{<PRE>\n}; - $inpre=1; - process_thing(\$q,"HTML"); - } - } - 1 while $q =~ s/\t+/' 'x (length($&) * 8 - length($`) % 8)/e; - print HTML $q,"\n"; - } - last if $paras[$p+1] !~ /^\s/; - $p++; - } - print HTML ($inpre==1) ? (qq{\n</PRE>\n}) : (qq{\n</XMP>\n}); - } - else { # other text - @lines = split(/\n/,$paras[$p]); - foreach $line (@lines) { - process_thing(\$line,"HTML"); - $line =~ s/STRONG([^>])/STRONG>$1/; # lame attempt to fix strong - print HTML qq{$line\n}; - } - } - print HTML qq{<p>}; - } -} - -sub process_thing{ # process a chunk, order important - my($thing,$htype) = @_; - pre_escapes($thing); - find_refs($thing,$htype); - post_escapes($thing); -} - -sub scan_thing{ # scan a chunk for later references - my($cmd,$title,$pod) = @_; - $_ = $title; - s/\n$//; - s/E<(.*?)>/&$1;/g; - # remove any formatting information for the headers - s/[SFCBI]<(.*?)>/$1/g; - # the "don't format me" thing - s/Z<>//g; - if ($cmd eq "item") { - /^\*/ and return; # skip bullets - /^\d+\./ and return; # skip numbers - s/(-[a-z]).*/$1/i; - trim($_); - return if defined $A->{$pod}->{"Items"}->{$_}; - $A->{$pod}->{"Items"}->{$_} = gensym($pod, $_); - $A->{$pod}->{"Items"}->{(split(' ',$_))[0]}=$A->{$pod}->{"Items"}->{$_}; - Debug("items", "item $_"); - if (!/^-\w$/ && /([%\$\@\w]+)/ && $1 ne $_ - && !defined($A->{$pod}->{"Items"}->{$_}) && ($_ ne $1)) - { - $A->{$pod}->{"Items"}->{$1} = $A->{$pod}->{"Items"}->{$_}; - Debug("items", "item $1 REF TO $_"); - } - if ( m{^(tr|y|s|m|q[qwx])/.*[^/]} ) { - my $pf = $1 . '//'; - $pf .= "/" if $1 eq "tr" || $1 eq "y" || $1 eq "s"; - if ($pf ne $_) { - $A->{$pod}->{"Items"}->{$pf} = $A->{$pod}->{"Items"}->{$_}; - Debug("items", "item $pf REF TO $_"); - } - } - } - elsif ($cmd =~ /^head[12]/) { - return if defined($A->{$pod}->{"Headers"}->{$_}); - $A->{$pod}->{"Headers"}->{$_} = gensym($pod, $_); - Debug("headers", "header $_"); - } - else { - warn "unrecognized header: $cmd" if $Debug; - } -} - - -sub picrefs { - my($char, $bigkey, $lilkey,$htype) = @_; - my($key,$ref,$podname); - for $podname ($pod,@inclusions) { - for $ref ( "Items", "Headers" ) { - if (defined $A->{$podname}->{$ref}->{$bigkey}) { - $value = $A->{$podname}->{$ref}->{$key = $bigkey}; - Debug("subs", "bigkey is $bigkey, value is $value\n"); - } - elsif (defined $A->{$podname}->{$ref}->{$lilkey}) { - $value = $A->{$podname}->{$ref}->{$key = $lilkey}; - return "" if $lilkey eq ''; - Debug("subs", "lilkey is $lilkey, value is $value\n"); - } - } - if (length($key)) { - ($pod2, $num) = $value =~ /^(.*)_(\S+_\d+)$/; - if ($htype eq "NAME") { - return "\n<A NAME=\"".$value."\">\n$bigkey</A>\n" - } - else { - 1; # break here - return "\n$type$Podnames{$pod2}\#".$value."\">$bigkey<\/A>\n"; - } - } - } - if ($char =~ /[IF]/) { - return "<EM>$bigkey</EM>"; - } elsif ($char =~ /C/) { - return "<CODE>$bigkey</CODE>"; - } else { - if($bigkey =~ /STRONG/){ - return $bigkey; - } - else { - return "<STRONG>$bigkey</STRONG>"; - } - } -} - -sub find_refs { - my($thing,$htype) = @_; - my($orig) = $$thing; - # LREF: a manpage(3f) we don't know about - for ($$thing) { - #s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))>:the I<$1>$2 manpage:g; - s@(\S+?://\S*[^.,;!?\s])@noremap(qq{<A HREF="$1">$1</A>})@ge; - s,([a-z0-9_.-]+\@([a-z0-9_-]+\.)+([a-z0-9_-]+)),noremap(qq{<A HREF="mailto:$1">$1</A>}),gie; - s/L<([^>]*)>/lrefs($1,$htype)/ge; - s/([CIBF])<(\W*?(-?\w*).*?)>/picrefs($1, $2, $3, $htype)/ge; - s/(S)<([^\/]\W*?(-?\w*).*?)>/picrefs($1, $2, $3, $htype)/ge; - s/((\w+)\(\))/picrefs("I", $1, $2,$htype)/ge; - s/([\$\@%](?!&[gl]t)([\w:]+|\W\b))/varrefs($1,$htype)/ge; - } - if ($$thing eq $orig && $htype eq "NAME") { - $$thing = picrefs("I", $$thing, "", $htype); - } - -} - -sub lrefs { - my($page, $item) = split(m#/#, $_[0], 2); - my($htype) = $_[1]; - my($podname); - my($section) = $page =~ /\((.*)\)/; - my $selfref; - if ($page =~ /^[A-Z]/ && $item) { - $selfref++; - $item = "$page/$item"; - $page = $pod; - } elsif (!$item && $page =~ /[^a-z\-]/ && $page !~ /^\$.$/) { - $selfref++; - $item = $page; - $page = $pod; - } - $item =~ s/\(\)$//; - if (!$item) { - if (!defined $section && defined $Podnames{$page}) { - return "\n$type$Podnames{$page}\">\nthe <EM>$page</EM> manpage<\/A>\n"; - } else { - (warn "Bizarre entry $page/$item") if $Debug; - return "the <EM>$_[0]</EM> manpage\n"; - } - } - - if ($item =~ s/"(.*)"/$1/ || ($item =~ /[^\w\/\-]/ && $item !~ /^\$.$/)) { - $text = "<EM>$item</EM>"; - $ref = "Headers"; - } else { - $text = "<EM>$item</EM>"; - $ref = "Items"; - } - for $podname ($pod, @inclusions) { - undef $value; - if ($ref eq "Items") { - if (defined($value = $A->{$podname}->{$ref}->{$item})) { - ($pod2,$num) = split(/_/,$value,2); # break here - return (($pod eq $pod2) && ($htype eq "NAME")) - ? "\n<A NAME=\"".$value."\">\n$text</A>\n" - : "\n$type$Podnames{$pod2}\#".$value."\">$text<\/A>\n"; - } - } - elsif ($ref eq "Headers") { - if (defined($value = $A->{$podname}->{$ref}->{$item})) { - ($pod2,$num) = split(/_/,$value,2); # break here - return (($pod eq $pod2) && ($htype eq "NAME")) - ? "\n<A NAME=\"".$value."\">\n$text</A>\n" - : "\n$type$Podnames{$pod2}\#".$value."\">$text<\/A>\n"; - } - } - } - warn "No $ref reference for $item (@_)" if $Debug; - return $text; -} - -sub varrefs { - my ($var,$htype) = @_; - for $podname ($pod,@inclusions) { - if ($value = $A->{$podname}->{"Items"}->{$var}) { - ($pod2,$num) = split(/_/,$value,2); - Debug("vars", "way cool -- var ref on $var"); - return (($pod eq $pod2) && ($htype eq "NAME")) # INHERIT $_, $pod - ? "\n<A NAME=\"".$value."\">\n$var</A>\n" - : "\n$type$Podnames{$pod2}\#".$value."\">$var<\/A>\n"; - } - } - Debug( "vars", "bummer, $var not a var"); - if($var =~ /STRONG/){ - return $var; - } - else{ - return "<STRONG>$var</STRONG>"; - } -} - -sub gensym { - my ($podname, $key) = @_; - $key =~ s/\s.*//; - ($key = lc($key)) =~ tr/a-z/_/cs; - my $name = "${podname}_${key}_0"; - $name =~ s/__/_/g; - while ($sawsym{$name}++) { - $name =~ s/_?(\d+)$/'_' . ($1 + 1)/e; - } - return $name; -} - -sub pre_escapes { # twiddle these, and stay up late :-) - my($thing) = @_; - for ($$thing) { - s/([\200-\377])/noremap("&#".ord($1).";")/ge; - s/"(.*?)"/``$1''/gs; - s/&/noremap("&")/ge; - s/<</noremap("<<")/eg; - s/([^ESIBLCF])</$1\<\;/g; - s/E<(\d+)>/\&#$1\;/g; # embedded numeric special - s/E<([^\/][^<>]*)>/\&$1\;/g; # embedded special - } -} -sub noremap { # adding translator for hibit chars soon - my $hide = $_[0]; - $hide =~ tr/\000-\177/\200-\377/; - $hide; -} - - -sub post_escapes { - my($thing) = @_; - for ($$thing) { - s/([^GM])>>/$1\>\;\>\;/g; - s/([^D][^"MGA])>/$1\>\;/g; - tr/\200-\377/\000-\177/; - } -} - -sub Debug { - my $level = shift; - print STDERR @_,"\n" if $Debug{$level}; -} - -sub dumptable { - my $t = shift; - print STDERR "TABLE DUMP $t\n"; - foreach $k (sort keys %$t) { - printf STDERR "%-20s <%s>\n", $t->{$k}, $k; - } -} -sub trim { - for (@_) { - s/^\s+//; - s/\s\n?$//; - } -} -sub wanted { - my $name = $name; - if (-f $_) { - if ($name =~ /\.p(m|od)$/){ - push(@modpods, $name) if ($name =~ /\.p(m|od)$/); - } - } -} +=head1 NAME +pod2html - convert .pod files to .html files + +=head1 SYNOPSIS + + pod2html --help --htmlroot=<name> --infile=<name> --outfile=<name> + --podpath=<name>:...:<name> --podroot=<name> + --libpods=<name>:...:<name> --recurse --norecurse --verbose + --index --noindex --title=<name> + +=head1 DESCRIPTION + +Converts files from pod format (see L<perlpod>) to HTML format. + +=head1 ARGUMENTS + +pod2html takes the following arguments: + +=over 4 + +=item help + + --help + +Displays the usage message. + +=item htmlroot + + --htmlroot=name + +Sets the base URL for the HTML files. When cross-references are made, +the HTML root is prepended to the URL. + +=item infile + + --infile=name + +Specify the pod file to convert. Input is taken from STDIN if no +infile is specified. + +=item outfile + + --outfile=name + +Specify the HTML file to create. Output goes to STDOUT if no outfile +is specified. + +=item podroot + + --podroot=name + +Specify the base directory for finding library pods. + +=item podpath + + --podpath=name:...:name + +Specify which subdirectories of the podroot contain pod files whose +HTML converted forms can be linked-to in cross-references. + +=item libpods + + --libpods=name:...:name + +List of page names (eg, "perlfunc") which contain linkable C<=item>s. + +=item netscape + + --netscape + +Use Netscape HTML directives when applicable. + +=item nonetscape + + --nonetscape + +Do not use Netscape HTML directives (default). + +=item index + + --index + +Generate an index at the top of the HTML file (default behaviour). + +=item noindex + + --noindex + +Do not generate an index at the top of the HTML file. + + +=item recurse + + --recurse + +Recurse into subdirectories specified in podpath (default behaviour). + +=item norecurse + + --norecurse + +Do not recurse into subdirectories specified in podpath. + +=item title + + --title=title + +Specify the title of the resulting HTML file. + +=item verbose + + --verbose + +Display progress messages. + +=back + +=head1 AUTHOR + +Tom Christiansen, E<lt>tchrist@perl.comE<gt>. + +=head1 BUGS + +See L<Pod::Html> for a list of known bugs in the translator. + +=head1 SEE ALSO + +L<perlpod>, L<Pod::HTML> + +=head1 COPYRIGHT + +This program is distributed under the Artistic License. + +=cut + +use Pod::Html; + +pod2html @ARGV; !NO!SUBS! close OUT or die "Can't close $file: $!"; |