diff options
Diffstat (limited to 'pod')
| -rw-r--r-- | pod/perlapio.pod | 4 | ||||
| -rw-r--r-- | pod/perlbook.pod | 24 | ||||
| -rw-r--r-- | pod/perldebug.pod | 26 | ||||
| -rw-r--r-- | pod/perldelta.pod | 51 | ||||
| -rw-r--r-- | pod/perldiag.pod | 77 | ||||
| -rw-r--r-- | pod/perlembed.pod | 245 | ||||
| -rw-r--r-- | pod/perlfunc.pod | 62 | ||||
| -rw-r--r-- | pod/perlguts.pod | 273 | ||||
| -rw-r--r-- | pod/perlop.pod | 20 | ||||
| -rw-r--r-- | pod/perlre.pod | 27 | ||||
| -rw-r--r-- | pod/perlrun.pod | 83 | ||||
| -rw-r--r-- | pod/perltoc.pod | 2 | ||||
| -rw-r--r-- | pod/perltrap.pod | 22 | ||||
| -rw-r--r-- | pod/perlvar.pod | 38 | ||||
| -rw-r--r-- | pod/perlxstut.pod | 4 | ||||
| -rw-r--r-- | pod/pod2man.PL | 24 | ||||
| -rwxr-xr-x | pod/splitpod | 12 |
17 files changed, 662 insertions, 332 deletions
diff --git a/pod/perlapio.pod b/pod/perlapio.pod index d88e44509c..0db385e388 100644 --- a/pod/perlapio.pod +++ b/pod/perlapio.pod @@ -99,12 +99,12 @@ are different, there is only one "count" and order has =item B<PerlIO_close(f)> -=item B<PerlIO_puts(s,f)>, B<PerlIO_putc(c,f)> +=item B<PerlIO_puts(f,s)>, B<PerlIO_putc(f,c)> These correspond to fputs() and fputc(). Note that arguments have been revised to have "file" first. -=item B<PerlIO_ungetc(c,f)> +=item B<PerlIO_ungetc(f,c)> This corresponds to ungetc(). Note that arguments have been revised to have "file" first. diff --git a/pod/perlbook.pod b/pod/perlbook.pod index 8005e81d29..9a725cb833 100644 --- a/pod/perlbook.pod +++ b/pod/perlbook.pod @@ -11,27 +11,23 @@ web-connected, you can even mosey on over to http://www.ora.com/ for an online order form. I<Programming Perl, Second Edition> is a reference work that covers -nearly all of Perl, while I<Learning Perl> is a tutorial that covers -the most frequently used subset of the language. You might also check -out the very handy, inexpensive, and compact I<Perl 5 Desktop -Reference>, especially when the thought of lugging the 676-page Camel -around doesn't make much sense. I<Mastering Regular Expressions>, by -Jeffrey Friedl, is a reference work that covers the art and implementation -of regular expressions in various languages including Perl. +nearly all of Perl, while I<Learning Perl, Second Edition> is a +tutorial that covers the most frequently used subset of the language. +You might also check out the very handy, inexpensive, and compact +I<Perl 5 Desktop Reference>, especially when the thought of lugging +the 676-page Camel around doesn't make much sense. I<Mastering +Regular Expressions>, by Jeffrey Friedl, is a reference work that +covers the art and implementation of regular expressions in various +languages including Perl. Programming Perl, Second Edition (the Camel Book): ISBN 1-56592-149-6 (English) - Learning Perl (the Llama Book): - ISBN 1-56592-042-2 (English) - ISBN 4-89502-678-1 (Japanese) - ISBN 2-84177-005-2 (French) - ISBN 3-930673-08-8 (German) + Learning Perl, Second Edition (the Llama Book): + ISBN 1-56592-284-0 (English) Perl 5 Desktop Reference (the reference card): ISBN 1-56592-187-9 (brief English) Mastering Regular Expressions (the Hip Owl Book): ISBN 1-56592-257-3 (English) - -A new edition of Learning Perl is due mid/late 1997. diff --git a/pod/perldebug.pod b/pod/perldebug.pod index 1b206fb96d..a02fd5c710 100644 --- a/pod/perldebug.pod +++ b/pod/perldebug.pod @@ -8,6 +8,15 @@ First of all, have you tried using the B<-w> switch? =head1 The Perl Debugger +"As soon as we started programming, we found to our +surprise that it wasn't as easy to get programs right +as we had thought. Debugging had to be discovered. +I can remember the exact instant when I realized that +a large part of my life from then on was going to be +spent in finding mistakes in my own programs." + +I< --Maurice Wilkes, 1949> + If you invoke Perl with the B<-d> switch, your script runs under the Perl source debugger. This works like an interactive Perl environment, prompting for debugger commands that let you examine @@ -933,7 +942,7 @@ package DB, Perl sets the array @DB::args to contain the arguments the corresponding stack frame was called with. If perl is run with B<-d> option, the following additional features -are enabled: +are enabled (cf. L<perlvar/$^P>): =over @@ -1008,16 +1017,13 @@ in the package C<DB>.) =back -Note that no subroutine call is possible until C<&DB::sub> is defined -(for subroutines outside of package C<DB>). (This restriction is -recently lifted.) - -(In fact, for the standard debugger the same is true if C<$DB::deep> -(how many levels of recursion deep into the debugger you can go before -a mandatory break) is not defined.) +Note that if C<&DB::sub> needs some external data to be setup for it +to work, no subroutine call is possible until this is done. For the +standard debugger C<$DB::deep> (how many levels of recursion deep into +the debugger you can go before a mandatory break) gives an example of +such a dependency. -With the recent updates the minimal possible debugger consists of one -line +The minimal working debugger consists of one line sub DB::DB {} diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 4c944825bb..8d191e82d7 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -147,6 +147,13 @@ because at least two widely-used modules depend on the old meaning of old (broken) way inside strings; but it generates this message as a warning. And in Perl 5.005, this special treatment will cease. +=head2 Fixed localization of $<digit>, $&, etc. + +Perl versions before 5.004 did not always properly localize the +regex-related special variables. Perl 5.004 does localize them, as +the documentation has always said it should. This may result in $1, +$2, etc. no longer being set where existing programs use them. + =head2 No resetting of $. on implicit close The documentation for Perl 5.0 has always stated that C<$.> is I<not> @@ -285,7 +292,7 @@ there is no C<use English> long name for this variable. 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 +compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then $^M = 'a' x (1<<16); @@ -395,6 +402,9 @@ provides seven bits of the total value, with the most significant first. Bit eight of each byte is set, except for the last byte, in which bit eight is clear. +If 'p' or 'P' are given undef as values, they now generate a NULL +pointer. + Both pack() and unpack() now fail when their templates contain invalid types. (Invalid types used to be ignored.) @@ -495,6 +505,21 @@ before (printed only zeros), but is fine now: $i . +However, it still fails (without a warning) if the foreach is within a +subroutine: + + my $i; + sub foo { + foreach $i ( 1 .. 10 ) { + write; + } + } + foo; + format = + my i is @# + $i + . + =back =head2 New builtin methods @@ -631,24 +656,23 @@ possibly for cleaning up. =head2 Malloc enhancements -Four new compilation flags are recognized by malloc.c. (They have no -effect if perl is compiled with system malloc().) - -=over - -=item -DDEBUGGING_MSTATS - -If perl is compiled with C<DEBUGGING_MSTATS> defined, you can print +If perl is compiled with the malloc included with the perl distribution +(that is, if C<perl -V:d_mymalloc> is 'define') then you can print memory statistics at runtime by running Perl thusly: env PERL_DEBUG_MSTATS=2 perl your_script_here The value of 2 means to print statistics after compilation and on -exit; with a value of 1, the statistics ares printed only on exit. +exit; with a value of 1, the statistics are printed only on exit. (If you want the statistics at an arbitrary time, you'll need to install the optional module Devel::Peek.) -=item -DEMERGENCY_SBRK +Three new compilation flags are recognized by malloc.c. (They have no +effect if perl is compiled with system malloc().) + +=over + +=item -DPERL_EMERGENCY_SBRK If this macro is defined, running out of memory need not be a fatal error: a memory pool can allocated by assigning to the special @@ -705,7 +729,8 @@ Support for the following operating systems is new in Perl 5.004. Perl 5.004 now includes support for building a "native" perl under Windows NT, using the Microsoft Visual C++ compiler (versions 2.0 -and above). The resulting perl can be used under Windows 95 (if it +and above) or the Borland C++ compiler (versions 5.02 and above). +The resulting perl can be used under Windows 95 (if it is installed in the same directory locations as it got installed in Windows NT). This port includes support for perl extension building tools like L<MakeMaker> and L<h2xs>, so that many extensions @@ -719,8 +744,6 @@ Cygwin32 is a set of GNU tools that make it possible to compile and run many UNIX programs under Windows NT by providing a mostly UNIX-like interface for compilation and execution. See L<README.cygwin32> for more details on this port, and how to obtain the Cygwin32 toolkit. -This port has not been as well tested as the "native" port described -above (which is not as well tested as we'd like either :) =head2 Plan 9 diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 1b0f92e31f..a4d9356977 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -23,7 +23,7 @@ L<perlfunc/eval>. Some of these messages are generic. Spots that vary are denoted with a %s, just as in a printf format. Note that some messages start with a %s! -The symbols C<"%-?@> sort before the letters, while C<[> and C<\> sort after. +The symbols C<"%(-?@> sort before the letters, while C<[> and C<\> sort after. =over 4 @@ -143,6 +143,12 @@ Perl yourself. instead of Perl. Check the #! line, or manually feed your script into Perl yourself. +=item (Missing semicolon on previous line?) + +(S) This is an educated guess made in conjunction with the message "%s +found where operator expected". Don't automatically put a semicolon on +the previous line just because you saw this message. + =item B<-P> not allowed for setuid/setgid script (F) The script would have to be opened by the C preprocessor by name, @@ -153,6 +159,12 @@ which provides a race condition that breaks security. (F) Perl can't peek at the stdio buffer of filehandles when it doesn't know about your kind of stdio. You'll have to use a filename instead. +=item C<-p> destination: %s + +(F) An error occurred during the implicit output invoked by the C<-p> +command-line switch. (This output goes to STDOUT unless you've +redirected it with select().) + =item 500 Server error See Server error. @@ -265,6 +277,15 @@ could indicate that SvREFCNT_dec() was called too many times, or that SvREFCNT_inc() was called too few times, or that the SV was mortalized when it shouldn't have been, or that memory has been corrupted. +=item Attempt to pack pointer to temporary value + +(W) You tried to pass a temporary value (like the result of a +function, or a computed expression) to the "p" pack() template. This +means the result contains a pointer to a location that could become +invalid anytime, even before the end of the current statement. Use +literals or global values as arguments to the "p" pack() template to +avoid this warning. + =item Attempt to use reference as lvalue in substr (W) You supplied a reference as the first argument to substr() used @@ -374,6 +395,11 @@ like a block, except that it isn't a proper block. This usually occurs if you tried to jump out of a sort() block or subroutine, which is a no-no. See L<perlfunc/goto>. +=item Can't "goto" into the middle of a foreach loop + +(F) A "goto" statement was executed to jump into the middle of a +foreach loop. You can't get there from here. See L<perlfunc/goto>. + =item Can't "last" outside a block (F) A "last" statement was executed to break out of the current block, @@ -543,8 +569,19 @@ mention "perl" on the #! line somewhere. =item Can't execute %s +(F) You used the B<-S> switch, but the copies of the script to execute found +in the PATH did not have correct permissions. + +=item Can't find %s on PATH, '.' not in PATH + (F) You used the B<-S> switch, but the script to execute could not be found -in the PATH, or at least not with the correct permissions. +in the PATH, or at least not with the correct permissions. The script +exists in the current directory, but PATH prohibits running it. + +=item Can't find %s on PATH + +(F) You used the B<-S> switch, but the script to execute could not be found +in the PATH. =item Can't find label %s @@ -597,12 +634,12 @@ call for another. It can't manufacture one out of whole cloth. In general you should be calling it out of only an AUTOLOAD routine anyway. See L<perlfunc/goto>. -=item Can't localize a reference +=item Can't localize through a reference -(F) You said something like C<local $$ref>, which is not allowed because -the compiler can't determine whether $ref will end up pointing to anything -with a symbol table entry, and a symbol table entry is necessary to -do a local. +(F) You said something like C<local $$ref>, which Perl can't currently +handle, because when it goes to restore the old value of whatever $ref +pointed to after the scope of the local() is finished, it can't be +sure that $ref will still be a reference. =item Can't localize lexical variable %s @@ -611,6 +648,13 @@ lexical variable using "my". This is not allowed. If you want to localize a package variable of the same name, qualify it with the package name. +=item Can't locate auto/%s.al in @INC + +(F) A function (or method) was called in a package which allows autoload, +but there is no function to autoload. Most probable causes are a misprint +in a function/method name or a failure to C<AutoSplit> the file, say, by +doing C<make install>. + =item Can't locate %s in @INC (F) You said to do (or require, or use) a file that couldn't be found @@ -656,8 +700,11 @@ buffer. =item Can't open %s: %s -(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. +(S) The implicit opening of a file through use of the C<E<lt>E<gt>> +filehandle, either implicitly under the C<-n> or C<-p> command-line +switches, or explicitly, failed for the indicated reason. Usually this +is because you don't have read permission for a file which you named +on the command line. =item Can't open bidirectional pipe @@ -1342,12 +1389,6 @@ found where operator expected". Often the missing operator is a comma. As a general rule, you'll find it's missing near the place you were last editing. -=item Missing semicolon on previous line? - -(S) This is an educated guess made in conjunction with the message "%s -found where operator expected". Don't automatically put a semicolon on -the previous line just because you saw this message. - =item Modification of a read-only value attempted (F) You tried, directly or indirectly, to change the value of a @@ -2070,6 +2111,10 @@ or possibly some other missing operator, such as a comma. (W) The filehandle you're sending to got itself closed sometime before now. Check your logic flow. +=item Sequence (? incomplete +(F) A regular expression ended with an incomplete extension (?. +See L<perlre>. + =item Sequence (?#... not terminated (F) A regular expression comment must be terminated by a closing @@ -2491,7 +2536,7 @@ script, a binary program, or a directory as a Perl program. (F) You specified a signal name to the kill() function that was not recognized. Say C<kill -l> in your shell to see the valid signal names on your system. -=item Unrecognized switch: -%s +=item Unrecognized switch: -%s (-h will show valid options) (F) You specified an illegal option to Perl. Don't do that. (If you think you didn't do that, check the #! line to see if it's diff --git a/pod/perlembed.pod b/pod/perlembed.pod index de10860987..c43ed556aa 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -332,155 +332,173 @@ variables and we've simplified our code as well. =head2 Performing Perl pattern matches and substitutions from your C program -The I<perl_eval_pv()> function lets us evaluate strings of Perl code, so we can +The I<perl_eval_sv()> function lets us evaluate chunks of Perl code, so we can define some functions that use it to "specialize" in matches and substitutions: I<match()>, I<substitute()>, and I<matches()>. - char match(char *string, char *pattern); + char match(SV *string, char *pattern); Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which in your C program might appear as "/\\b\\w*\\b/"), match() returns 1 if the string matches the pattern and 0 otherwise. - int substitute(char *string[], char *pattern); + int substitute(SV **string, char *pattern); -Given a pointer to a string and an C<=~> operation (e.g., +Given a pointer to an C<SV> and an C<=~> operation (e.g., C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string -according to the operation, returning the number of substitutions +within the C<AV> at according to the operation, returning the number of substitutions made. - int matches(char *string, char *pattern, char **matches[]); + int matches(SV *string, char *pattern, AV **matches); -Given a string, a pattern, and a pointer to an empty array of strings, +Given an C<SV>, a pattern, and a pointer to an empty C<AV>, matches() evaluates C<$string =~ $pattern> in an array context, and -fills in I<matches> with the array elements (allocating memory as it -does so), returning the number of matches found. +fills in I<matches> with the array elements, returning the number of matches found. Here's a sample program, I<match.c>, that uses all three (long lines have been wrapped here): - #include <EXTERN.h> - #include <perl.h> - - static PerlInterpreter *my_perl; - - /** match(string, pattern) - ** - ** Used for matches in a scalar context. - ** - ** Returns 1 if the match was successful; 0 otherwise. - **/ - char match(char *string, char *pattern) - { - char *command; - command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37); - sprintf(command, "$string = '%s'; $return = $string =~ %s", - string, pattern); - perl_eval_pv(command, TRUE); - free(command); - return SvIV(perl_get_sv("return", FALSE)); - } - /** substitute(string, pattern) - ** - ** Used for =~ operations that modify their left-hand side (s/// and tr///) - ** - ** Returns the number of successful matches, and - ** modifies the input string if there were any. - **/ - int substitute(char *string[], char *pattern) - { - char *command; - STRLEN length; - command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35); - sprintf(command, "$string = '%s'; $ret = ($string =~ %s)", - *string, pattern); - perl_eval_pv(command, TRUE); - free(command); - *string = SvPV(perl_get_sv("string", FALSE), length); - return SvIV(perl_get_sv("ret", FALSE)); - } - /** matches(string, pattern, matches) - ** - ** Used for matches in an array context. - ** - ** Returns the number of matches, - ** and fills in **matches with the matching substrings (allocates memory!) - **/ - int matches(char *string, char *pattern, char **match_list[]) - { - char *command; - SV *current_match; - AV *array; + #include <EXTERN.h> + #include <perl.h> + + /** my_perl_eval_sv(code, error_check) + ** kinda like perl_eval_sv(), + ** but we pop the return value off the stack + **/ + SV* my_perl_eval_sv(SV *sv, I32 croak_on_error) + { + dSP; + SV* retval; + + PUSHMARK(sp); + perl_eval_sv(sv, G_SCALAR); + + SPAGAIN; + retval = POPs; + PUTBACK; + + if (croak_on_error && SvTRUE(GvSV(errgv))) + croak(SvPVx(GvSV(errgv), na)); + + return retval; + } + + /** match(string, pattern) + ** + ** Used for matches in a scalar context. + ** + ** Returns 1 if the match was successful; 0 otherwise. + **/ + + I32 match(SV *string, char *pattern) + { + SV *command = newSV(0), *retval; + + sv_setpvf(command, "my $string = '%s'; $string =~ %s", + SvPV(string,na), pattern); + + retval = my_perl_eval_sv(command, TRUE); + SvREFCNT_dec(command); + + return SvIV(retval); + } + + /** substitute(string, pattern) + ** + ** Used for =~ operations that modify their left-hand side (s/// and tr///) + ** + ** Returns the number of successful matches, and + ** modifies the input string if there were any. + **/ + + I32 substitute(SV **string, char *pattern) + { + SV *command = newSV(0), *retval; + + sv_setpvf(command, "$string = '%s'; ($string =~ %s)", + SvPV(*string,na), pattern); + + retval = my_perl_eval_sv(command, TRUE); + SvREFCNT_dec(command); + + *string = perl_get_sv("string", FALSE); + return SvIV(retval); + } + + /** matches(string, pattern, matches) + ** + ** Used for matches in an array context. + ** + ** Returns the number of matches, + ** and fills in **matches with the matching substrings + **/ + + I32 matches(SV *string, char *pattern, AV **match_list) + { + SV *command = newSV(0); I32 num_matches; - STRLEN length; - int i; - command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38); - sprintf(command, "$string = '%s'; @array = ($string =~ %s)", - string, pattern); - perl_eval_pv(command, TRUE); - free(command); - array = perl_get_av("array", FALSE); - num_matches = av_len(array) + 1; /** assume $[ is 0 **/ - *match_list = (char **) malloc(sizeof(char *) * num_matches); - for (i = 0; i <= num_matches; i++) { - current_match = av_shift(array); - (*match_list)[i] = SvPV(current_match, length); - } + + sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)", + SvPV(string,na), pattern); + + my_perl_eval_sv(command, TRUE); + SvREFCNT_dec(command); + + *match_list = perl_get_av("array", FALSE); + num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/ + return num_matches; - } - main (int argc, char **argv, char **env) - { + } + + main (int argc, char **argv, char **env) + { + PerlInterpreter *my_perl = perl_alloc(); char *embedding[] = { "", "-e", "0" }; - char *text, **match_list; - int num_matches, i; - int j; - my_perl = perl_alloc(); - perl_construct( my_perl ); + AV *match_list; + I32 num_matches, i; + SV *text = newSV(0); + + perl_construct(my_perl); perl_parse(my_perl, NULL, 3, embedding, NULL); - perl_run(my_perl); - - text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/ - sprintf(text, "%s", "When he is at a convenience store and the bill \ - comes to some amount like 76 cents, Maynard is aware that there is \ - something he *should* do, something that will enable him to get back \ - a quarter, but he has no idea *what*. He fumbles through his red \ - squeezey changepurse and gives the boy three extra pennies with his \ - dollar, hoping that he might luck into the correct amount. The boy \ - gives him back two of his own pennies and then the big shiny quarter \ - that is his prize. -RICHH"); + + sv_setpv(text, "When he is at a convenience store and the bill comes to some amount like 76 cents, Maynard is aware that there is something he *should* do, something that will enable him to get back a quarter, but he has no idea *what*. He fumbles through his red squeezey changepurse and gives the boy three extra pennies with his dollar, hoping that he might luck into the correct amount. The boy gives him back two of his own pennies and then the big shiny quarter that is his prize. -RICHH"); + if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/ - printf("match: Text contains the word 'quarter'.\n\n"); + printf("match: Text contains the word 'quarter'.\n\n"); else - printf("match: Text doesn't contain the word 'quarter'.\n\n"); + printf("match: Text doesn't contain the word 'quarter'.\n\n"); + if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/ - printf("match: Text contains the word 'eighth'.\n\n"); + printf("match: Text contains the word 'eighth'.\n\n"); else - printf("match: Text doesn't contain the word 'eighth'.\n\n"); + printf("match: Text doesn't contain the word 'eighth'.\n\n"); + /** Match all occurrences of /wi../ **/ num_matches = matches(text, "m/(wi..)/g", &match_list); printf("matches: m/(wi..)/g found %d matches...\n", num_matches); + for (i = 0; i < num_matches; i++) - printf("match: %s\n", match_list[i]); + printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),na)); printf("\n"); - for (i = 0; i < num_matches; i++) { - free(match_list[i]); - } - free(match_list); + /** Remove all vowels from text **/ num_matches = substitute(&text, "s/[aeiou]//gi"); if (num_matches) { - printf("substitute: s/[aeiou]//gi...%d substitutions made.\n", - num_matches); - printf("Now text is: %s\n\n", text); + printf("substitute: s/[aeiou]//gi...%d substitutions made.\n", + num_matches); + printf("Now text is: %s\n\n", SvPV(text,na)); } + /** Attempt a substitution **/ if (!substitute(&text, "s/Perl/C/")) { - printf("substitute: s/Perl/C...No substitution made.\n\n"); + printf("substitute: s/Perl/C...No substitution made.\n\n"); } - free(text); + + SvREFCNT_dec(text); + perl_destruct_level = 1; perl_destruct(my_perl); perl_free(my_perl); - } + } which produces the output (again, long lines have been wrapped here) @@ -560,15 +578,12 @@ deep breath... int main (int argc, char **argv, char **env) { - char *my_argv[2]; + char *my_argv[] = { "", "power.pl" }; my_perl = perl_alloc(); perl_construct( my_perl ); - my_argv[1] = (char *) malloc(10); - sprintf(my_argv[1], "power.pl"); - - perl_parse(my_perl, NULL, argc, my_argv, NULL); + perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL); perl_run(my_perl); PerlPower(3, 4); /*** Compute 3 ** 4 ***/ @@ -995,7 +1010,7 @@ Dov Grobgeld, and Ilya Zakharevich. Check out Doug's article on embedding in Volume 1, Issue 4 of The Perl Journal. Info about TPJ is available from http://tpj.com. -April 14, 1997 +July 17, 1997 Some of this material is excerpted from Jon Orwant's book: I<Perl 5 Interactive>, Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index a28487ac1d..4f3341d911 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -633,7 +633,7 @@ their own password: print "ok\n"; } -Of course, typing in your own password to whomever asks you +Of course, typing in your own password to whoever asks you for it is unwise. =item dbmclose HASH @@ -1032,17 +1032,19 @@ in case 6. The exec() function executes a system command I<AND NEVER RETURNS>, unless the command does not exist and is executed directly instead of -via C</bin/sh -c> (see below). Use system() instead of exec() if you -want it to return. +via your system's command shell (see below). Use system() instead of +exec() if you want it to return. If there is more than one argument in LIST, or if LIST is an array with more than one value, calls execvp(3) with the arguments in LIST. If there is only one scalar argument, the argument is checked for shell -metacharacters. If there are any, the entire argument is passed to -C</bin/sh -c> for parsing. If there are none, the argument is split -into words and passed directly to execvp(), which is more efficient. -Note: exec() and system() do not flush your output buffer, so you may -need to set C<$|> to avoid lost output. Examples: +metacharacters, and if there are any, the entire argument is passed to +the system's command shell for parsing (this is C</bin/sh -c> on Unix +platforms, but varies on other platforms). If there are no shell +metacharacters in the argument, it is split into words and passed +directly to execvp(), which is more efficient. Note: exec() and +system() do not flush your output buffer, so you may need to set C<$|> +to avoid lost output. Examples: exec '/bin/echo', 'Your arguments are: ', @ARGV; exec "sort $outfile | uniq"; @@ -1061,6 +1063,10 @@ or, more directly, exec {'/bin/csh'} '-sh'; # pretend it's a login shell +When the arguments get executed via the system shell, results will +be subject to its quirks and capabilities. See L<perlop/"`STRING`"> +for details. + =item exists EXPR Returns TRUE if the specified hash key exists in its hash array, even @@ -2150,8 +2156,13 @@ types gobble just one value, but pack it as a string of length count, padding with nulls or spaces as necessary. (When unpacking, "A" strips trailing spaces and nulls, but "a" does not.) Likewise, the "b" and "B" fields pack a string that many bits long. The "h" and "H" fields pack a -string that many nybbles long. The "P" packs a pointer to a structure of -the size indicated by the length. Real numbers (floats and doubles) are +string that many nybbles long. The "p" type packs a pointer to a null- +terminated string. You are responsible for ensuring the string is not a +temporary value (which can potentially get deallocated before you get +around to using the packed result). The "P" packs a pointer to a structure +of the size indicated by the length. A NULL pointer is created if the +corresponding value for "p" or "P" is C<undef>. +Real numbers (floats and doubles) are in the native machine format only; due to the multiplicity of floating formats around, and the lack of a standard "network" representation, no facility for interchange has been made. This means that packed floating @@ -2371,6 +2382,16 @@ chdir() there, it would have been testing the wrong file. @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR); closedir DIR; +=item readline EXPR + +Reads from the file handle EXPR. In scalar context, a single line +is read and returned. In list context, reads until end-of-file is +reached and returns a list of lines (however you've defined lines +with $/ or $INPUT_RECORD_SEPARATOR). +This is the internal function implementing the C<E<lt>EXPRE<gt>> +operator, but you can use it directly. The C<E<lt>EXPRE<gt>> +operator is discussed in more detail in L<perlop/"I/O Operators">. + =item readlink EXPR =item readlink @@ -2380,6 +2401,17 @@ implemented. If not, gives a fatal error. If there is some system error, returns the undefined value and sets C<$!> (errno). If EXPR is omitted, uses $_. +=item readpipe EXPR + +EXPR 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. In list context, returns a list of lines +(however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR). +This is the internal function implementing the C<qx/EXPR/> +operator, but you can use it directly. The C<qx/EXPR/> +operator is discussed in more detail in L<perlop/"I/O Operators">. + =item recv SOCKET,SCALAR,LEN,FLAGS Receives a message on a socket. Attempts to receive LENGTH bytes of @@ -3336,11 +3368,15 @@ L<perlref> for details. Extracts a substring out of EXPR and returns it. First character is at offset 0, or whatever you've set C<$[> to (but don't do that). -If OFFSET is negative, starts +If OFFSET is negative (or more precisely, less than C<$[>), starts that far from the end of the string. If LEN is omitted, returns everything to the end of the string. If LEN is negative, leaves that many characters off the end of the string. +If you specify a substring which is partly outside the string, the part +within the string is returned. If the substring is totally outside +the string a warning is produced. + You can use the substr() function as an lvalue, in which case EXPR must be an lvalue. If you assign something shorter than LEN, the string will shrink, and if you assign @@ -3480,6 +3516,10 @@ signals and core dumps. } $ok = ($rc != 0); +When the arguments get executed via the system shell, results will +be subject to its quirks and capabilities. See L<perlop/"`STRING`"> +for details. + =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET =item syswrite FILEHANDLE,SCALAR,LENGTH diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 28c196017c..ecf8610756 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -765,52 +765,71 @@ the various routines for the various magical types begin with C<magic_>. The current kinds of Magic Virtual Tables are: - mg_type MGVTBL Type of magical + mg_type MGVTBL Type of magic ------- ------ ---------------------------- - \0 vtbl_sv Regexp??? - A vtbl_amagic Operator Overloading - a vtbl_amagicelem Operator Overloading - c 0 Used in Operator Overloading - B vtbl_bm Boyer-Moore??? + \0 vtbl_sv Special scalar variable + A vtbl_amagic %OVERLOAD hash + a vtbl_amagicelem %OVERLOAD hash element + c (none) Holds overload table (AMT) on stash + B vtbl_bm Boyer-Moore (fast string search) E vtbl_env %ENV hash e vtbl_envelem %ENV hash element - g vtbl_mglob Regexp /g flag??? + f vtbl_fm Formline ('compiled' format) + g vtbl_mglob m//g target / study()ed string I vtbl_isa @ISA array i vtbl_isaelem @ISA array element - L 0 (but sets RMAGICAL) Perl Module/Debugger??? - l vtbl_dbline Debugger? + k vtbl_nkeys scalar(keys()) lvalue + L (none) Debugger %_<filename + l vtbl_dbline Debugger %_<filename element o vtbl_collxfrm Locale transformation - P vtbl_pack Tied Array or Hash - p vtbl_packelem Tied Array or Hash element - q vtbl_packelem Tied Scalar or Handle - S vtbl_sig Signal Hash - s vtbl_sigelem Signal Hash element + P vtbl_pack Tied array or hash + p vtbl_packelem Tied array or hash element + q vtbl_packelem Tied scalar or handle + S vtbl_sig %SIG hash + s vtbl_sigelem %SIG hash element t vtbl_taint Taintedness - U vtbl_uvar ??? - v vtbl_vec Vector - x vtbl_substr Substring??? - y vtbl_itervar Shadow "foreach" iterator variable - * vtbl_glob GV??? - # vtbl_arylen Array Length - . vtbl_pos $. scalar variable - ~ None Used by certain extensions + U vtbl_uvar Available for use by extensions + v vtbl_vec vec() lvalue + x vtbl_substr substr() lvalue + y vtbl_defelem Shadow "foreach" iterator variable / + smart parameter vivification + * vtbl_glob GV (typeglob) + # vtbl_arylen Array length ($#ary) + . vtbl_pos pos() lvalue + ~ (none) Available for use by extensions When an uppercase and lowercase letter both exist in the table, then the uppercase letter is used to represent some kind of composite type (a list or a hash), and the lowercase letter is used to represent an element of that composite type. -The '~' magic type is defined specifically for use by extensions and -will not be used by perl itself. Extensions can use ~ magic to 'attach' -private information to variables (typically objects). This is especially -useful because there is no way for normal perl code to corrupt this -private information (unlike using extra elements of a hash object). +The '~' and 'U' magic types are defined specifically for use by +extensions and will not be used by perl itself. Extensions can use +'~' magic to 'attach' private information to variables (typically +objects). This is especially useful because there is no way for +normal perl code to corrupt this private information (unlike using +extra elements of a hash object). + +Similarly, 'U' magic can be used much like tie() to call a C function +any time a scalar's value is used or changed. The C<MAGIC>'s +C<mg_ptr> field points to a C<ufuncs> structure: + + struct ufuncs { + I32 (*uf_val)(IV, SV*); + I32 (*uf_set)(IV, SV*); + IV uf_index; + }; + +When the SV is read from or written to, the C<uf_val> or C<uf_set> +function will be called with C<uf_index> as the first arg and a +pointer to the SV as the second. -Note that because multiple extensions may be using ~ magic it is -important for extensions to take extra care with it. Typically only -using it on objects blessed into the same class as the extension -is sufficient. It may also be appropriate to add an I32 'signature' -at the top of the private data area and check that. +Note that because multiple extensions may be using '~' or 'U' magic, +it is important for extensions to take extra care to avoid conflict. +Typically only using the magic on objects blessed into the same class +as the extension is sufficient. For '~' magic, it may also be +appropriate to add an I32 'signature' at the top of the private data +area and check that. =head2 Finding Magic @@ -885,6 +904,150 @@ This overhead will be comparatively small if the TIE methods are themselves substantial, but if they are only a few statements long, the overhead will not be insignificant. +=head2 Localizing changes + +Perl has a very handy construction + + { + local $var = 2; + ... + } + +This construction is I<approximately> equivalent to + + { + my $oldvar = $var; + $var = 2; + ... + $var = $oldvar; + } + +The biggest difference is that the first construction would +reinstate the initial value of $var, irrespective of how control exits +the block: C<goto>, C<return>, C<die>/C<eval> etc. It is a little bit +more efficient as well. + +There is a way to achieve a similar task from C via Perl API: create a +I<pseudo-block>, and arrange for some changes to be automatically +undone at the end of it, either explicit, or via a non-local exit (via +die()). A I<block>-like construct is created by a pair of +C<ENTER>/C<LEAVE> macros (see L<perlcall/EXAMPLE/"Returning a +Scalar">). Such a construct may be created specially for some +important localized task, or an existing one (like boundaries of +enclosing Perl subroutine/block, or an existing pair for freeing TMPs) +may be used. (In the second case the overhead of additional +localization must be almost negligible.) Note that any XSUB is +automatically enclosed in an C<ENTER>/C<LEAVE> pair. + +Inside such a I<pseudo-block> the following service is available: + +=over + +=item C<SAVEINT(int i)> + +=item C<SAVEIV(IV i)> + +=item C<SAVEI32(I32 i)> + +=item C<SAVELONG(long i)> + +These macros arrange things to restore the value of integer variable +C<i> at the end of enclosing I<pseudo-block>. + +=item C<SAVESPTR(s)> + +=item C<SAVEPPTR(p)> + +These macros arrange things to restore the value of pointers C<s> and +C<p>. C<s> must be a pointer of a type which survives conversion to +C<SV*> and back, C<p> should be able to survive conversion to C<char*> +and back. + +=item C<SAVEFREESV(SV *sv)> + +The refcount of C<sv> would be decremented at the end of +I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be +used instead. + +=item C<SAVEFREEOP(OP *op)> + +The C<OP *> is op_free()ed at the end of I<pseudo-block>. + +=item C<SAVEFREEPV(p)> + +The chunk of memory which is pointed to by C<p> is Safefree()ed at the +end of I<pseudo-block>. + +=item C<SAVECLEARSV(SV *sv)> + +Clears a slot in the current scratchpad which corresponds to C<sv> at +the end of I<pseudo-block>. + +=item C<SAVEDELETE(HV *hv, char *key, I32 length)> + +The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The +string pointed to by C<key> is Safefree()ed. If one has a I<key> in +short-lived storage, the corresponding string may be reallocated like +this: + + SAVEDELETE(defstash, savepv(tmpbuf), strlen(tmpbuf)); + +=item C<SAVEDESTRUCTOR(f,p)> + +At the end of I<pseudo-block> the function C<f> is called with the +only argument (of type C<void*>) C<p>. + +=item C<SAVESTACK_POS()> + +The current offset on the Perl internal stack (cf. C<SP>) is restored +at the end of I<pseudo-block>. + +=back + +The following API list contains functions, thus one needs to +provide pointers to the modifiable data explicitly (either C pointers, +or Perlish C<GV *>s). Where the above macros take C<int>, a similar +function takes C<int *>. + +=over + +=item C<SV* save_scalar(GV *gv)> + +Equivalent to Perl code C<local $gv>. + +=item C<AV* save_ary(GV *gv)> + +=item C<HV* save_hash(GV *gv)> + +Similar to C<save_scalar>, but localize C<@gv> and C<%gv>. + +=item C<void save_item(SV *item)> + +Duplicates the current value of C<SV>, on the exit from the current +C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV> +using the stored value. + +=item C<void save_list(SV **sarg, I32 maxsarg)> + +A variant of C<save_item> which takes multiple arguments via an array +C<sarg> of C<SV*> of length C<maxsarg>. + +=item C<SV* save_svref(SV **sptr)> + +Similar to C<save_scalar>, but will reinstate a C<SV *>. + +=item C<void save_aptr(AV **aptr)> + +=item C<void save_hptr(HV **hptr)> + +Similar to C<save_svref>, but localize C<AV *> and C<HV *>. + +=back + +The C<Alias> module implements localization of the basic types within the +I<caller's scope>. People who are interested in how to localize things in +the containing scope should take a look there too. + =head1 Subroutines =head2 XSUBs and the Argument Stack @@ -1405,11 +1568,6 @@ to indicate the number of items on the stack. Sets up the C<ix> variable for an XSUB which has aliases. This is usually handled automatically by C<xsubpp>. -=item dXSI32 - -Sets up the C<ix> variable for an XSUB which has aliases. This is usually -handled automatically by C<xsubpp>. - =item ENTER Opening bracket on a callback. See C<LEAVE> and L<perlcall>. @@ -2364,14 +2522,6 @@ C<sv2>. I32 sv_cmp _((SV* sv1, SV* sv2)); -=item sv_cmp - -Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the -string in C<sv1> is less than, equal to, or greater than the string in -C<sv2>. - - I32 sv_cmp _((SV* sv1, SV* sv2)); - =item SvCUR Returns the length of the string which is in the SV. See C<SvLEN>. @@ -2390,12 +2540,6 @@ Auto-decrement of the value in the SV. void sv_dec _((SV* sv)); -=item sv_dec - -Auto-decrement of the value in the SV. - - void sv_dec _((SV* sv)); - =item SvEND Returns a pointer to the last character in the string which is in the SV. @@ -2453,12 +2597,6 @@ Tells an SV that it is an integer and disables all other OK bits. SvIOK_on (SV* sv) -=item SvIOK_only - -Tells an SV that it is an integer and disables all other OK bits. - - SvIOK_on (SV* sv) - =item SvIOKp Returns a boolean indicating whether the SV contains an integer. Checks the @@ -2506,12 +2644,6 @@ Returns the length of the string in the SV. Use C<SvCUR>. STRLEN sv_len _((SV* sv)); -=item sv_len - -Returns the length of the string in the SV. Use C<SvCUR>. - - STRLEN sv_len _((SV* sv)); - =item sv_magic Adds magic to an SV. @@ -2585,12 +2717,6 @@ Tells an SV that it is a double and disables all other OK bits. SvNOK_on (SV* sv) -=item SvNOK_only - -Tells an SV that it is a double and disables all other OK bits. - - SvNOK_on (SV* sv) - =item SvNOKp Returns a boolean indicating whether the SV contains a double. Checks the @@ -2634,12 +2760,6 @@ Tells an SV that it is a string and disables all other OK bits. SvPOK_on (SV* sv) -=item SvPOK_only - -Tells an SV that it is a string and disables all other OK bits. - - SvPOK_on (SV* sv) - =item SvPOKp Returns a boolean indicating whether the SV contains a character string. @@ -3050,7 +3170,8 @@ Jeff Okamoto <F<okamoto@corp.hp.com>> With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil -Bowers, Matthew Green, Tim Bunce, Spider Boardman, and Ulrich Pfeifer. +Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, and +Stephen McCamant. API Listing by Dean Roehrich <F<roehrich@cray.com>>. diff --git a/pod/perlop.pod b/pod/perlop.pod index 32a0827cb3..56859029bf 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -702,7 +702,7 @@ each time it matches, and FALSE when it eventually runs out of matches. the search at that point. You can actually find the current match position of a string or set it using the pos() function; see L<perlfunc/pos>.) A failed match normally resets the search position to -the beginning of the string, but you can avoid that by adding the "c" +the beginning of the string, but you can avoid that by adding the C</c> modifier (e.g. C<m//gc>). Modifying the target string also resets the search position. @@ -808,6 +808,24 @@ with $/ or $INPUT_RECORD_SEPARATOR). $today = qx{ date }; +Note that how the string gets evaluated is entirely subject to the +command interpreter on your system. On most platforms, you will have +to protect shell metacharacters if you want them treated literally. +On some platforms (notably DOS-like ones), the shell may not be +capable of dealing with multiline commands, so putting newlines in +the string may not get you what you want. You may be able to evaluate +multiple commands in a single line by separating them with the command +separator character, if your shell supports that (e.g. C<;> on many Unix +shells; C<&> on the Windows NT C<cmd> shell). + +Beware that some command shells may place restrictions on the length +of the command line. You must ensure your strings don't exceed this +limit after any necessary interpolations. See the platform-specific +release notes for more details about your particular environment. + +Also realize that using this operator frequently leads to unportable +programs. + See L<"I/O Operators"> for more discussion. =item qw/STRING/ diff --git a/pod/perlre.pod b/pod/perlre.pod index 2b24379c8b..14892a8846 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -136,7 +136,7 @@ also work: \L lowercase till \E (think vi) \U uppercase till \E (think vi) \E end case modification (think vi) - \Q quote regexp metacharacters till \E + \Q quote (disable) regexp metacharacters till \E If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u> and <\U> is taken from the current locale. See L<perllocale>. @@ -226,19 +226,20 @@ you've used them once, use them at will, because you've already paid the price. You will note that all backslashed metacharacters in Perl are -alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular expression -languages, there are no backslashed symbols that aren't alphanumeric. -So anything that looks like \\, \(, \), \E<lt>, \E<gt>, \{, or \} is always -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 +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 +metacharacter. This was once used in a common idiom to disable or +quote the special meanings of regular expression metacharacters in a +string that you want to use for a pattern. Simply quote all the non-alphanumeric characters: $pattern =~ s/(\W)/\\$1/g; -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 +Now it is much more common to see either the quotemeta() function or +the \Q escape sequence used to disable the metacharacters special +meanings like this: /$unquoted\Q$quoted\E$unquoted/ @@ -515,7 +516,11 @@ in C<[]>, which will match any one of the characters in the list. If the first character after the "[" is "^", the class matches any character not 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. +inclusive. If you want "-" itself to be a member of a class, put it +at the start or end of the list, or escape it with a backslash. (The +following all specify the same class of three characters: C<[-az]>, +C<[az-]>, and C<[a\-z]>. All are different from C<[a-z]>, which +specifies a class containing twenty-six characters.) 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, diff --git a/pod/perlrun.pod b/pod/perlrun.pod index de7116d939..1e3279e374 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -224,33 +224,33 @@ runs the script under the control of a debugging or tracing module installed as Devel::foo. E.g., B<-d:DProf> executes the script using the Devel::DProf profiler. See L<perldebug>. -=item B<-D>I<number> +=item B<-D>I<letters> -=item B<-D>I<list> +=item B<-D>I<number> sets debugging flags. To watch how it executes your script, use -B<-D14>. (This works only if debugging is compiled into your -Perl.) Another nice value is B<-D1024>, which lists your compiled -syntax tree. And B<-D512> displays compiled regular expressions. As an -alternative specify a list of letters instead of numbers (e.g., B<-D14> is +B<-Dtls>. (This works only if debugging is compiled into your +Perl.) Another nice value is B<-Dx>, which lists your compiled +syntax tree. And B<-Dr> displays compiled regular expressions. As an +alternative, specify a number instead of list of letters (e.g., B<-D14> is equivalent to B<-Dtls>): - 1 p Tokenizing and Parsing - 2 s Stack Snapshots - 4 l Label Stack Processing - 8 t Trace Execution - 16 o Operator Node Construction - 32 c String/Numeric Conversions - 64 P Print Preprocessor Command for -P - 128 m Memory Allocation - 256 f Format Processing - 512 r Regular Expression Parsing - 1024 x Syntax Tree Dump - 2048 u Tainting Checks - 4096 L Memory Leaks (not supported anymore) - 8192 H Hash Dump -- usurps values() - 16384 X Scratchpad Allocation - 32768 D Cleaning Up + 1 p Tokenizing and parsing + 2 s Stack snapshots + 4 l Context (loop) stack processing + 8 t Trace execution + 16 o Method and overloading resolution + 32 c String/numeric conversions + 64 P Print preprocessor command for -P + 128 m Memory allocation + 256 f Format processing + 512 r Regular expression parsing and execution + 1024 x Syntax tree dump + 2048 u Tainting checks + 4096 L Memory leaks (not supported anymore) + 8192 H Hash dump -- usurps values() + 16384 X Scratchpad allocation + 32768 D Cleaning up =item B<-e> I<commandline> @@ -376,8 +376,10 @@ B<awk>: } Note that the lines are not printed by default. See B<-p> to have -lines printed. Here is an efficient way to delete all files older than -a week: +lines printed. If a file named by an argument cannot be opened for +some reason, Perl warns you about it, and moves on to the next file. + +Here is an efficient way to delete all files older than a week: find . -mtime +7 -print | perl -nle 'unlink;' @@ -396,11 +398,14 @@ makes it iterate over filename arguments somewhat like B<sed>: while (<>) { ... # your script goes here } continue { - print; + print or die "-p destination: $!\n"; } -Note that the lines are printed automatically. To suppress printing -use the B<-n> switch. A B<-p> overrides a B<-n> switch. +If a file named by an argument cannot be opened for some reason, Perl +warns you about it, and moves on to the next file. Note that the +lines are printed automatically. An error occuring during printing is +treated as fatal. To suppress printing use the B<-n> switch. A B<-p> +overrides a B<-n> switch. C<BEGIN> and C<END> blocks may be used to capture control before or after the implicit loop, just as in awk. @@ -426,9 +431,27 @@ prints "true" if and only if the script is invoked with a B<-xyz> switch. =item B<-S> makes Perl use the PATH environment variable to search for the -script (unless the name of the script starts with a slash). Typically -this is used to emulate #! startup on machines that don't support #!, -in the following manner: +script (unless the name of the script contains directory separators). +On some platforms, this also makes Perl append suffixes to the +filename while searching for it. For example, on Win32 platforms, +the ".bat" and ".cmd" suffixes are appended if a lookup for the +original name fails, and if the name does not already end in one +of those suffixes. If your Perl was compiled with DEBUGGING turned +on, using the -Dp switch to Perl shows how the search progresses. + +If the file supplied contains directory separators (i.e. it is an +absolute or relative pathname), and if the file is not found, +platforms that append file extensions will do so and try to look +for the file with those extensions added, one by one. + +On DOS-like platforms, if the script does not contain directory +separators, it will first be searched for in the current directory +before being searched for on the PATH. On Unix platforms, the +script will be searched for strictly on the PATH. + +Typically this is used to emulate #! startup on platforms that +don't support #!. This example works on many platforms that +have a shell compatible with Bourne shell: #!/usr/bin/perl eval 'exec /usr/bin/perl -S $0 ${1+"$@"}' diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 989c1efe01..74b0029d73 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -911,7 +911,7 @@ LIST, READLINE this, GETC this, DESTROY this =item Malloc enhancements --DDEBUGGING_MSTATS, -DEMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE +-DDEBUGGING_MSTATS, -DPERL_EMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE =item Miscellaneous efficiency enhancements diff --git a/pod/perltrap.pod b/pod/perltrap.pod index 786dcda607..9382789969 100644 --- a/pod/perltrap.pod +++ b/pod/perltrap.pod @@ -438,6 +438,12 @@ whether this should be classed as a bug or not. # perl4 prints: x=10 # perl5 prints: Can't find string terminator "'" anywhere before EOF +You can avoid this problem, and remain compatible with perl4, if you +always explicitly include the package name: + + $x = 10 ; + print "x=${main'x}\n" ; + Also see precedence traps, for parsing C<$:>. =item * BugFix @@ -923,7 +929,9 @@ Perl4-to-Perl5 traps involving precedence order. =item * Precedence -LHS vs. RHS when both sides are getting an op. +LHS vs. RHS of any assignment operator. LHS is evaluated first +in perl4, second in perl5; this can affect the relationship +between side-effects in sub-expressions. @arr = ( 'left', 'right' ); $a{shift @arr} = shift @arr; @@ -999,18 +1007,6 @@ concatenation precedence over filetest operator? # perl4 prints: no output # perl5 prints: Can't modify -e in concatenation -=item * Precedence - -Assignment to value takes precedence over assignment to key in -perl5 when using the shift operator on both sides. - - @arr = ( 'left', 'right' ); - $a{shift @arr} = shift @arr; - print join( ' ', keys %a ); - - # perl4 prints: left - # perl5 prints: right - =back =head2 General Regular Expression Traps using s///, etc. diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 198e5c12a3..6487fdda36 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -619,9 +619,39 @@ is identical to C<$Config{'osname'}>. =item $^P -The internal flag that the debugger clears so that it doesn't debug -itself. You could conceivably disable debugging yourself by clearing -it. +The internal variable for debugging support. Different bits mean the +following (subject to change): + +=over 6 + +=item 0x01 + +Debug subroutine enter/exit. + +=item 0x02 + +Line-by-line debugging. + +=item 0x04 + +Switch off optimizations. + +=item 0x08 + +Preserve more data for future interactive inspections. + +=item 0x10 + +Keep info about source lines on which a subroutine is defined. + +=item 0x20 + +Start with single-step on. + +=back + +Note that some bits may be relevent at compile-time only, some at +run-time only. This is a new mechanism and the details may change. =item $BASETIME @@ -753,7 +783,7 @@ L<perlfunc/die>, L<perlfunc/warn> and L<perlfunc/eval>. 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 +compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then $^M = 'a' x (1<<16); diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod index cdd4344b78..9ebfe82a97 100644 --- a/pod/perlxstut.pod +++ b/pod/perlxstut.pod @@ -529,12 +529,12 @@ and a new replacement subroutine too: sub MY::postamble { ' $(MYEXTLIB): mylib/Makefile - cd mylib && $(MAKE) + cd mylib && $(MAKE) $(PASTHRU) '; } (Note: Most makes will require that there be a tab character that indents -the line "cd mylib && $(MAKE)", similarly for the Makefile in the +the line C<cd mylib && $(MAKE) $(PASTHRU)>, similarly for the Makefile in the subdirectory.) Let's also fix the MANIFEST file so that it accurately reflects the contents diff --git a/pod/pod2man.PL b/pod/pod2man.PL index 2c1837a37a..46f47a8870 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -310,6 +310,7 @@ Tom Christiansen such that Larry probably doesn't recognize it anymore. $/ = ""; $cutting = 1; +@Indices = (); # We try first to get the version number from a local binary, in case we're # running an installed version of Perl to produce documentation from an @@ -555,13 +556,14 @@ END print <<"END"; .TH $name $section "$RP" "$date" "$center" -.IX Title "$name $section" .UC END +push(@Indices, qq{.IX Title "$name $section"}); + while (($name, $desc) = each %namedesc) { for ($name, $desc) { s/^\s+//; s/\s+$//; } - print qq(.IX Name "$name - $desc"\n); + push(@Indices, qq(.IX Name "$name - $desc"\n)); } print <<'END'; @@ -727,9 +729,9 @@ while (<>) { # trofficate backslashes; must do it before what happens below s/\\/noremap('\\e')/ge; -# protect leading periods and quotes against *roff -# mistaking them for directives -s/^(?:[A-Z]<)?[.']/\\&$&/gm; + # protect leading periods and quotes against *roff + # mistaking them for directives + s/^(?:[A-Z]<)?[.']/\\&$&/gm; # first hide the escapes in case we need to # intuit something and get it wrong due to fmting @@ -883,11 +885,11 @@ s/^(?:[A-Z]<)?[.']/\\&$&/gm; s/\s+$//; delete $wanna_see{$_} if exists $wanna_see{$_}; print qq{.SH "$_"\n}; - print qq{.IX Header "$_"\n}; + push(@Indices, qq{.IX Header "$_"\n}); } elsif ($Cmd eq 'head2') { print qq{.Sh "$_"\n}; - print qq{.IX Subsection "$_"\n}; + push(@Indices, qq{.IX Subsection "$_"\n}); } elsif ($Cmd eq 'over') { push(@indent,$indent); @@ -906,7 +908,7 @@ s/^(?:[A-Z]<)?[.']/\\&$&/gm; s/[^"]""([^"]+?)""[^"]/'$1'/g; # here do something about the $" in perlvar? print STDOUT qq{.Ip "$_" $indent\n}; - print qq{.IX Item "$_"\n}; + push(@Indices, qq{.IX Item "$_"\n}); } elsif ($Cmd eq 'pod') { # this is just a comment @@ -939,6 +941,8 @@ if (%wanna_see && !$lax) { $oops++; } +foreach (@Indices) { print "$_\n"; } + exit; #exit ($oops != 0); @@ -1042,7 +1046,7 @@ sub makespace { sub mkindex { my ($entry) = @_; my @entries = split m:\s*/\s*:, $entry; - print ".IX Xref "; + push @Indices, ".IX Xref " . join ' ', map {qq("$_")} @entries; for $entry (@entries) { print qq("$entry" ); } @@ -1101,6 +1105,7 @@ sub clear_noremap { sub internal_lrefs { local($_) = shift; + local $trailing_and = s/and\s+$// ? "and " : ""; s{L</([^>]+)>}{$1}g; my(@items) = split( /(?:,?\s+(?:and\s+)?)/ ); @@ -1114,6 +1119,7 @@ sub internal_lrefs { $retstr .= " entr" . ( @items > 1 ? "ies" : "y" ) . " elsewhere in this document "; # terminal space to avoid words running together (pattern used strips terminal spaces) + $retstr .= $trailing_and; return $retstr; diff --git a/pod/splitpod b/pod/splitpod index 889dfa215a..fd38e51acf 100755 --- a/pod/splitpod +++ b/pod/splitpod @@ -12,23 +12,29 @@ while (<>) { if (s/=item (\S+)/$1/) { #$cur = "POSIX::" . $1; + $next{$cur} = $1; $cur = $1; $syn{$cur} .= $_; next; } else { #s,L</,L<POSIX/,g; s,L</,L<perlfunc/,g; - push @{$pod{$cur} ||= []}, $_ if $cur; + push @{$pod{$cur}}, $_ if $cur; } } for $f ( keys %syn ) { - $type = $Type{$f} || next; + next unless $Type{$f}; $flavor = $Flavor{$f}; $orig = $f; ($name = $f) =~ s/\W//g; + + # deal with several functions sharing a description + $func = $orig; + $func = $next{$func} until $pod{$func}; + my $body = join "", @{$pod{$func}}; + # deal with unbalanced =over and =back cause by the split - my $body = $pod{$orig}; my $has_over = $body =~ /^=over/; my $has_back = $body =~ /^=back/; $body =~ s/^=over\s*//m if $has_over and !$has_back; |