From: Robin Barker Date: Fri, 22 Dec 2000 12:17:38 +0000 (+0000) Subject: ; was Re: Perlbug 20000322.006 status +update X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=551e1d922a333f90a45a26904eb4d9882f7bd5d4;p=p5sagit%2Fp5-mst-13.2.git ; was Re: Perlbug 20000322.006 status +update Message-Id: <200012221217.MAA21332@tempest.npl.co.uk> p4raw-id: //depot/perl@8228 --- diff --git a/lib/CGI.pm b/lib/CGI.pm index 617c605..6b87054 100644 --- a/lib/CGI.pm +++ b/lib/CGI.pm @@ -3530,12 +3530,18 @@ have several choices: =over 4 -=item 1. Use another name for the argument, if one is available. For -example, -value is an alias for -values. +=item 1. + +Use another name for the argument, if one is available. +For example, -value is an alias for -values. -=item 2. Change the capitalization, e.g. -Values +=item 2. -=item 3. Put quotes around the argument name, e.g. '-values' +Change the capitalization, e.g. -Values + +=item 3. + +Put quotes around the argument name, e.g. '-values' =back @@ -5669,6 +5675,7 @@ field. The second argument (-src) is also required and specifies the URL =item 3. + The third option (-align, optional) is an alignment type, and may be TOP, BOTTOM or MIDDLE @@ -6102,6 +6109,7 @@ Returns either the remote host name or IP address. if the former is unavailable. =item B + Return the script name as a partial URL, for self-refering scripts. @@ -6220,7 +6228,9 @@ Call B with a non-zero parameter at any point after using CGI.pm in your CGI->nph(1) -=item By using B<-nph> parameters in the B and B statements: +=item By using B<-nph> parameters + +in the B and B statements: print $q->header(-nph=>1); diff --git a/lib/CPAN.pm b/lib/CPAN.pm index daa34e8..ca89b50 100644 --- a/lib/CPAN.pm +++ b/lib/CPAN.pm @@ -6625,8 +6625,10 @@ Your milage may vary... =over -=item 1) I installed a new version of module X but CPAN keeps saying, - I have the old version installed +=item 1) + +I installed a new version of module X but CPAN keeps saying, +I have the old version installed Most probably you B have the old version installed. This can happen if a module installs itself into a different directory in the @@ -6638,14 +6640,18 @@ many people add this argument permanently by configuring o conf make_install_arg UNINST=1 -=item 2) So why is UNINST=1 not the default? +=item 2) + +So why is UNINST=1 not the default? Because there are people who have their precise expectations about who may install where in the @INC path and who uses which @INC array. In fine tuned environments C can cause damage. -=item 3) I want to clean up my mess, and install a new perl along with - all modules I have. How do I go about it? +=item 3) + +I want to clean up my mess, and install a new perl along with +all modules I have. How do I go about it? Run the autobundle command for your old perl and optionally rename the resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl @@ -6659,8 +6665,10 @@ Install the bundle file you produced in the first step with something like and you're done. -=item 4) When I install bundles or multiple modules with one command - there is too much output to keep track of +=item 4) + +When I install bundles or multiple modules with one command +there is too much output to keep track of. You may want to configure something like @@ -6670,8 +6678,9 @@ You may want to configure something like so that STDOUT is captured in a file for later inspection. -=item 5) I am not root, how can I install a module in a personal - directory? +=item 5) + +I am not root, how can I install a module in a personal directory? You will most probably like something like this: @@ -6694,14 +6703,17 @@ or setting the PERL5LIB environment variable. Another thing you should bear in mind is that the UNINST parameter should never be set if you are not root. -=item 6) How to get a package, unwrap it, and make a change before - building it? +=item 6) + +How to get a package, unwrap it, and make a change before building it? look Sybase::Sybperl -=item 7) I installed a Bundle and had a couple of fails. When I - retried, everything resolved nicely. Can this be fixed to work - on first try? +=item 7) + +I installed a Bundle and had a couple of fails. When I +retried, everything resolved nicely. Can this be fixed to work +on first try? The reason for this is that CPAN does not know the dependencies of all modules when it starts out. To decide about the additional items to @@ -6718,21 +6730,27 @@ definition file manually. It is planned to improve the metadata situation for dependencies on CPAN in general, but this will still take some time. -=item 8) In our intranet we have many modules for internal use. How - can I integrate these modules with CPAN.pm but without uploading - the modules to CPAN? +=item 8) + +In our intranet we have many modules for internal use. How +can I integrate these modules with CPAN.pm but without uploading +the modules to CPAN? Have a look at the CPAN::Site module. -=item 9) When I run CPAN's shell, I get error msg about line 1 to 4, - setting meta input/output via the /etc/inputrc file. +=item 9) + +When I run CPAN's shell, I get error msg about line 1 to 4, +setting meta input/output via the /etc/inputrc file. Some versions of readline are picky about capitalization in the /etc/inputrc file and specifically RedHat 6.2 comes with a /etc/inputrc that contains the word C in lowercase. Change the occurrences of C to C and the bug should disappear. -=item 10) Some authors have strange characters in their names. +=item 10) + +Some authors have strange characters in their names. Internally CPAN.pm uses the UTF-8 charset. If your terminal is expecting ISO-8859-1 charset, a converter can be activated by setting diff --git a/lib/Pod/Select.pm b/lib/Pod/Select.pm index d86d823..e7c820f 100644 --- a/lib/Pod/Select.pm +++ b/lib/Pod/Select.pm @@ -109,33 +109,39 @@ Some example section specifications follow. =over 4 -=item +=item * + Match the C and C sections and all of their subsections: C -=item +=item * + Match only the C and C subsections of the C section: C -=item +=item * + Match the C subsection of I sections: C -=item +=item * + Match all subsections of C I for C: C -=item +=item * + Match the C section but do I match any of its subsections: C -=item +=item * + Match all top level sections but none of their subsections: C diff --git a/lib/Text/ParseWords.pm b/lib/Text/ParseWords.pm index 2a6afc3..23eace9 100644 --- a/lib/Text/ParseWords.pm +++ b/lib/Text/ParseWords.pm @@ -214,21 +214,27 @@ demonstrating: =over 4 =item 0 + a simple word =item 1 + multiple spaces are skipped because of our $delim =item 2 + use of quotes to include a space in a word =item 3 + use of a backslash to include a space in a word =item 4 + use of a backslash to remove the special meaning of a double-quote =item 5 + another simple word (note the lack of effect of the backslashed double-quote) diff --git a/lib/Win32.pod b/lib/Win32.pod index 64361f8..303374b 100644 --- a/lib/Win32.pod +++ b/lib/Win32.pod @@ -175,7 +175,9 @@ function. system boot. Resolution is limited to system timer ticks (about 10ms on WinNT and 55ms on Win9X). -=item Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT) +=item + +Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT) [EXT] Shutsdown the specified MACHINE, notifying users with the supplied MESSAGE, within the specified TIMEOUT interval. Forces diff --git a/pod/perl.pod b/pod/perl.pod index aa4e77f..0d2c1c3 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -192,56 +192,83 @@ rewrite that provides the following additional benefits: =over 4 -=item * modularity and reusability using innumerable modules +=item * + +modularity and reusability using innumerable modules Described in L, L, and L. -=item * embeddable and extensible +=item * + +embeddable and extensible Described in L, L, L, L, L, and L. -=item * roll-your-own magic variables (including multiple simultaneous DBM implementations) +=item * + +roll-your-own magic variables (including multiple simultaneous DBM implementations) Described in L and L. -=item * subroutines can now be overridden, autoloaded, and prototyped +=item * + +subroutines can now be overridden, autoloaded, and prototyped Described in L. -=item * arbitrarily nested data structures and anonymous functions +=item * + +arbitrarily nested data structures and anonymous functions Described in L, L, L, and L. -=item * object-oriented programming +=item * + +object-oriented programming Described in L, L, and L. -=item * compilability into C code or Perl bytecode +=item * + +compilability into C code or Perl bytecode Described in L and L. -=item * support for light-weight processes (threads) +=item * + +support for light-weight processes (threads) Described in L and L. -=item * support for internationalization, localization, and Unicode +=item * + +support for internationalization, localization, and Unicode Described in L and L. -=item * lexical scoping +=item * + +lexical scoping Described in L. -=item * regular expression enhancements +=item * + +regular expression enhancements Described in L, with additional examples in L. -=item * enhanced debugger and interactive Perl environment, with integrated editor support +=item * + +enhanced debugger and interactive Perl environment, +with integrated editor support Described in L. -=item * POSIX 1003.1 compliant library +=item * + +POSIX 1003.1 compliant library Described in L. diff --git a/pod/perl5004delta.pod b/pod/perl5004delta.pod index 7151d86..429cba9 100644 --- a/pod/perl5004delta.pod +++ b/pod/perl5004delta.pod @@ -1432,7 +1432,7 @@ 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' +=item Stub found while resolving method `%s' overloading `%s' in %s (P) Overloading resolution over @ISA tree may be broken by importing stubs. Stubs should never be implicitly created, but explicit calls to C diff --git a/pod/perl5005delta.pod b/pod/perl5005delta.pod index d863453..4b50f40 100644 --- a/pod/perl5005delta.pod +++ b/pod/perl5005delta.pod @@ -63,11 +63,15 @@ the new features in this release. =over 4 -=item Core sources now require ANSI C compiler +=item * + +Core sources now require ANSI C compiler An ANSI C compiler is now B to build perl. See F. -=item All Perl global variables must now be referenced with an explicit prefix +=item * + +All Perl global variables must now be referenced with an explicit prefix All Perl global variables that are visible for use by extensions now have a C prefix. New extensions should C refer to perl globals @@ -87,7 +91,9 @@ support may cease in a future release. See L. -=item Enabling threads has source compatibility issues +=item * + +Enabling threads has source compatibility issues Perl built with threading enabled requires extensions to use the new C macro to initialize the handle to access per-thread data. @@ -859,7 +865,7 @@ are outside the range which can be represented by integers internally. One possible workaround is to force Perl to use magical string increment by prepending "0" to your numbers. -=item Recursive inheritance detected while looking for method '%s' in package '%s' +=item Recursive inheritance detected while looking for method '%s' %s (F) More than 100 levels of inheritance were encountered while invoking a method. Probably indicates an unintended loop in your inheritance hierarchy. diff --git a/pod/perl56delta.pod b/pod/perl56delta.pod index d11f908..a0c4b06 100644 --- a/pod/perl56delta.pod +++ b/pod/perl56delta.pod @@ -2631,7 +2631,9 @@ but still allowed it. In Perl 5.6.0 and later, C<"$$1"> always means C<"${$1}">. -=item delete(), values() and C<\(%h)> operate on aliases to values, not copies +=item + +delete(), values() and C<\(%h)> operate on aliases to values, not copies delete(), each(), values() and hashes in a list context return the actual values in the hash, instead of copies (as they used to in earlier diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 8ea61b3..3c26282 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -314,7 +314,7 @@ distribution. map() that changes the size of the list should now work faster. =item * - + sort() has been changed to use mergesort internally as opposed to the earlier quicksort. For very small lists this may result in slightly slower sorting times, but in general the speedup should be at least @@ -469,7 +469,7 @@ Regular expressions on references and overloaded scalars now work. scalar() now forces scalar context even when used in void context. =item * - + sort() arguments are now compiled in the right wantarray context (they were accidentally using the context of the sort() itself). diff --git a/pod/perldiag.pod b/pod/perldiag.pod index a27dde7..abbdea7 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -1785,7 +1785,7 @@ instead on the filehandle.) values cannot be returned in subroutines used in lvalue context. See L. -=item Lookbehind longer than %d not implemented before << HERE in reges m/%s/ +=item Lookbehind longer than %d not implemented before << HERE %s (F) There is currently a limit on the length of string which lookbehind can handle. This restriction may be eased in a future release. The << HERE shows in @@ -2770,7 +2770,7 @@ declared or defined with a different function prototype. {min,max} construct. The << HERE shows in the regular expression about where the problem was discovered. See L. -=item Quantifier unexpected on zero-length expression before << HERE in regex m/%s/ +=item Quantifier unexpected on zero-length expression before << HERE %s (W regexp) You applied a regular expression quantifier in a place where it makes no sense, such as on a zero-width assertion. Try putting the @@ -2961,18 +2961,18 @@ before now. Check your control flow. shows in the regular expression about where the problem was discovered. See L. -=item Sequence (?{...}) not terminated or not {}-balanced in regex m/%s/ +=item Sequence (?{...}) not terminated or not {}-balanced in %s (F) If the contents of a (?{...}) clause contains braces, they must balance for Perl to properly detect the end of the clause. See L. -=item Sequence (?%s...) not implemented before << HERE mark in regex m/%s/ +=item Sequence (?%s...) not implemented before << HERE mark in %s (F) A proposed regular expression extension has the character reserved but has not yet been written. The << HERE shows in the regular expression about where the problem was discovered. See L. -=item Sequence (?%s...) not recognized before << HERE mark in regex m/%s/ +=item Sequence (?%s...) not recognized before << HERE mark in %s (F) You used a regular expression extension that doesn't make sense. The << HERE shows in the regular expression about @@ -3163,7 +3163,7 @@ assignment or as a subroutine argument for example). (F) Your Perl was compiled with B<-D>SETUID_SCRIPTS_ARE_SECURE_NOW, but a version of the setuid emulator somehow got run anyway. -=item Switch (?(condition)... contains too many branches before << HERE in regex m/%s/ +=item Switch (?(condition)... contains too many branches before << HE%s (F) A (?(condition)if-clause|else-clause) construct can have at most two branches (the if-clause and the else-clause). If you want one or both to @@ -3813,7 +3813,7 @@ anonymous, using the C syntax. When inner anonymous subs that reference variables in outer subroutines are called or referenced, they are automatically rebound to the current values of such variables. -=item Variable length lookbehind not implemented before << HERE in regex m/%s/ +=item Variable length lookbehind not implemented before << HERE in %s (F) Lookbehind is allowed only for subexpressions whose length is fixed and known at compile time. The << HERE shows in the regular expression about where diff --git a/pod/perlembed.pod b/pod/perlembed.pod index 6e3db32..57d1bdb 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -37,25 +37,45 @@ Read on... =over 5 -=item Compiling your C program +=item * -=item Adding a Perl interpreter to your C program +Compiling your C program -=item Calling a Perl subroutine from your C program +=item * -=item Evaluating a Perl statement from your C program +Adding a Perl interpreter to your C program -=item Performing Perl pattern matches and substitutions from your C program +=item * -=item Fiddling with the Perl stack from your C program +Calling a Perl subroutine from your C program -=item Maintaining a persistent interpreter +=item * -=item Maintaining multiple interpreter instances +Evaluating a Perl statement from your C program -=item Using Perl modules, which themselves use C libraries, from your C program +=item * -=item Embedding Perl under Win32 +Performing Perl pattern matches and substitutions from your C program + +=item * + +Fiddling with the Perl stack from your C program + +=item * + +Maintaining a persistent interpreter + +=item * + +Maintaining multiple interpreter instances + +=item * + +Using Perl modules, which themselves use C libraries, from your C program + +=item * + +Embedding Perl under Win32 =back diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod index 23bc666..1198f18 100644 --- a/pod/perlfaq4.pod +++ b/pod/perlfaq4.pod @@ -948,7 +948,9 @@ ordered and whether you wish to preserve the ordering. =over 4 -=item a) If @in is sorted, and you want @out to be sorted: +=item a) + +If @in is sorted, and you want @out to be sorted: (this assumes all true values in the array) $prev = 'nonesuch'; @@ -959,22 +961,30 @@ uniq(1)'s behavior of removing only adjacent duplicates. The ", 1" guarantees that the expression is true (so that grep picks it up) even if the $_ is 0, "", or undef. -=item b) If you don't know whether @in is sorted: +=item b) + +If you don't know whether @in is sorted: undef %saw; @out = grep(!$saw{$_}++, @in); -=item c) Like (b), but @in contains only small integers: +=item c) + +Like (b), but @in contains only small integers: @out = grep(!$saw[$_]++, @in); -=item d) A way to do (b) without any loops or greps: +=item d) + +A way to do (b) without any loops or greps: undef %saw; @saw{@in} = (); @out = sort keys %saw; # remove sort if undesired -=item e) Like (d), but @in contains only small positive integers: +=item e) + +Like (d), but @in contains only small positive integers: undef @ary; @ary[@in] = @in; diff --git a/pod/perllocale.pod b/pod/perllocale.pod index f0c64c7..d37664c 100644 --- a/pod/perllocale.pod +++ b/pod/perllocale.pod @@ -678,16 +678,22 @@ the locale: =over 4 -=item B (C, C, C, C and C): +=item * + +B (C, C, C, C and C): Scalar true/false (or less/equal/greater) result is never tainted. -=item B (with C<\l>, C<\L>, C<\u> or C<\U>) +=item * + +B (with C<\l>, C<\L>, C<\u> or C<\U>) Result string containing interpolated material is tainted if C is in effect. -=item B (C): +=item * + +B (C): Scalar true/false result never tainted. @@ -700,7 +706,9 @@ expression contains C<\w> (to match an alphanumeric character), C<\W> C is in effect and the regular expression contains C<\w>, C<\W>, C<\s>, or C<\S>. -=item B (C): +=item * + +B (C): Has the same behavior as the match operator. Also, the left operand of C<=~> becomes tainted when C in effect @@ -708,22 +716,30 @@ if modified as a result of a substitution based on a regular expression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of case-mapping with C<\l>, C<\L>,C<\u> or C<\U>. -=item B (printf() and write()): +=item * + +B (printf() and write()): Results are never tainted because otherwise even output from print, for example C, should be tainted if C is in effect. -=item B (lc(), lcfirst(), uc(), ucfirst()): +=item * + +B (lc(), lcfirst(), uc(), ucfirst()): Results are tainted if C is in effect. -=item B (localeconv(), strcoll(), +=item * + +B (localeconv(), strcoll(), strftime(), strxfrm()): Results are never tainted. -=item B (isalnum(), isalpha(), isdigit(), +=item * + +B (isalnum(), isalpha(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()): diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod index 1810e00..d0bd1c9 100644 --- a/pod/perlmodlib.pod +++ b/pod/perlmodlib.pod @@ -802,66 +802,87 @@ modules are: =over =item * + Language Extensions and Documentation Tools =item * + Development Support =item * + Operating System Interfaces =item * + Networking, Device Control (modems) and InterProcess Communication =item * + Data Types and Data Type Utilities =item * + Database Interfaces =item * + User Interfaces =item * + Interfaces to / Emulations of Other Programming Languages =item * + File Names, File Systems and File Locking (see also File Handles) =item * + String Processing, Language Text Processing, Parsing, and Searching =item * + Option, Argument, Parameter, and Configuration File Processing =item * + Internationalization and Locale =item * + Authentication, Security, and Encryption =item * + World Wide Web, HTML, HTTP, CGI, MIME =item * + Server and Daemon Utilities =item * + Archiving and Compression =item * + Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing =item * + Mail and Usenet News =item * + Control Flow Utilities (callbacks and exceptions etc) =item * + File Handle and Input/Output Stream Utilities =item * + Miscellaneous Modules =back @@ -1430,18 +1451,28 @@ Don't delete the original .pl file till the new .pm one works! =over 4 -=item Complete applications rarely belong in the Perl Module Library. +=item * + +Complete applications rarely belong in the Perl Module Library. -=item Many applications contain some Perl code that could be reused. +=item * + +Many applications contain some Perl code that could be reused. Help save the world! Share your code in a form that makes it easy to reuse. -=item Break-out the reusable code into one or more separate module files. +=item * + +Break-out the reusable code into one or more separate module files. -=item Take the opportunity to reconsider and redesign the interfaces. +=item * + +Take the opportunity to reconsider and redesign the interfaces. + +=item * -=item In some cases the 'application' can then be reduced to a small +In some cases the 'application' can then be reduced to a small fragment of code built on top of the reusable modules. In these cases the application could invoked as: diff --git a/pod/perlrequick.pod b/pod/perlrequick.pod index a14229c..3e29a4a 100644 --- a/pod/perlrequick.pod +++ b/pod/perlrequick.pod @@ -166,24 +166,31 @@ Perl has several abbreviations for common character classes: =over 4 =item * + \d is a digit and represents [0-9] =item * + \s is a whitespace character and represents [\ \t\r\n\f] =item * + \w is a word character (alphanumeric or _) and represents [0-9a-zA-Z_] =item * + \D is a negated \d; it represents any character but a digit [^0-9] =item * + \S is a negated \s; it represents any non-whitespace character [^\s] =item * + \W is a negated \w; it represents any non-word character [^\w] =item * + The period '.' matches any character but "\n" =back diff --git a/pod/perlretut.pod b/pod/perlretut.pod index 2c449f8..a77b87e 100644 --- a/pod/perlretut.pod +++ b/pod/perlretut.pod @@ -368,24 +368,31 @@ has several abbreviations for common character classes: =over 4 =item * + \d is a digit and represents [0-9] =item * + \s is a whitespace character and represents [\ \t\r\n\f] =item * + \w is a word character (alphanumeric or _) and represents [0-9a-zA-Z_] =item * + \D is a negated \d; it represents any character but a digit [^0-9] =item * + \S is a negated \s; it represents any non-whitespace character [^\s] =item * + \W is a negated \w; it represents any non-word character [^\w] =item * + The period '.' matches any character but "\n" =back @@ -451,22 +458,26 @@ and C<$> are able to match. Here are the four possible combinations: =over 4 =item * + no modifiers (//): Default behavior. C<'.'> matches any character except C<"\n">. C<^> matches only at the beginning of the string and C<$> matches only at the end or before a newline at the end. =item * + s modifier (//s): Treat string as a single long line. C<'.'> matches any character, even C<"\n">. C<^> matches only at the beginning of the string and C<$> matches only at the end or before a newline at the end. =item * + m modifier (//m): Treat string as a set of multiple lines. C<'.'> matches any character except C<"\n">. C<^> and C<$> are able to match at the start or end of I line within the string. =item * + both s and m modifiers (//sm): Treat string as a single long line, but detect multiple lines. C<'.'> matches any character, even C<"\n">. C<^> and C<$>, however, are able to match at the start or end @@ -602,32 +613,52 @@ of what perl does when it tries to match the regexp =over 4 -=item 0 Start with the first letter in the string 'a'. +=item 0 + +Start with the first letter in the string 'a'. + +=item 1 -=item 1 Try the first alternative in the first group 'abd'. +Try the first alternative in the first group 'abd'. -=item 2 Match 'a' followed by 'b'. So far so good. +=item 2 -=item 3 'd' in the regexp doesn't match 'c' in the string - a dead +Match 'a' followed by 'b'. So far so good. + +=item 3 + +'d' in the regexp doesn't match 'c' in the string - a dead end. So backtrack two characters and pick the second alternative in the first group 'abc'. -=item 4 Match 'a' followed by 'b' followed by 'c'. We are on a roll +=item 4 + +Match 'a' followed by 'b' followed by 'c'. We are on a roll and have satisfied the first group. Set $1 to 'abc'. -=item 5 Move on to the second group and pick the first alternative +=item 5 + +Move on to the second group and pick the first alternative 'df'. -=item 6 Match the 'd'. +=item 6 -=item 7 'f' in the regexp doesn't match 'e' in the string, so a dead +Match the 'd'. + +=item 7 + +'f' in the regexp doesn't match 'e' in the string, so a dead end. Backtrack one character and pick the second alternative in the second group 'd'. -=item 8 'd' matches. The second grouping is satisfied, so set $2 to +=item 8 + +'d' matches. The second grouping is satisfied, so set $2 to 'd'. -=item 9 We are at the end of the regexp, so we are done! We have +=item 9 + +We are at the end of the regexp, so we are done! We have matched 'abcd' out of the string "abcde". =back @@ -770,18 +801,30 @@ meanings: =over 4 -=item * C = match 'a' 1 or 0 times +=item * -=item * C = match 'a' 0 or more times, i.e., any number of times +C = match 'a' 1 or 0 times -=item * C = match 'a' 1 or more times, i.e., at least once +=item * + +C = match 'a' 0 or more times, i.e., any number of times + +=item * -=item * C = match at least C times, but not more than C +C = match 'a' 1 or more times, i.e., at least once + +=item * + +C = match at least C times, but not more than C times. -=item * C = match at least C or more times +=item * + +C = match at least C or more times + +=item * -=item * C = match exactly C times +C = match exactly C times =back @@ -845,19 +888,23 @@ the principles above to predict which way the regexp will match: =over 4 =item * + Principle 0: Taken as a whole, any regexp will be matched at the earliest possible position in the string. =item * + Principle 1: In an alternation C, the leftmost alternative that allows a match for the whole regexp will be the one used. =item * + Principle 2: The maximal matching quantifiers C, C<*>, C<+> and C<{n,m}> will in general match as much of the string as possible while still allowing the whole regexp to match. =item * + Principle 3: If there are two or more elements in a regexp, the leftmost greedy quantifier, if any, will match as much of the string as possible while still allowing the whole regexp to match. The next @@ -925,21 +972,33 @@ following meanings: =over 4 -=item * C = match 'a' 0 or 1 times. Try 0 first, then 1. +=item * + +C = match 'a' 0 or 1 times. Try 0 first, then 1. -=item * C = match 'a' 0 or more times, i.e., any number of times, +=item * + +C = match 'a' 0 or more times, i.e., any number of times, but as few times as possible -=item * C = match 'a' 1 or more times, i.e., at least once, but +=item * + +C = match 'a' 1 or more times, i.e., at least once, but as few times as possible -=item * C = match at least C times, not more than C +=item * + +C = match at least C times, not more than C times, as few times as possible -=item * C = match at least C times, but as few times as +=item * + +C = match at least C times, but as few times as possible -=item * C = match exactly C times. Because we match exactly +=item * + +C = match exactly C times. Because we match exactly C times, C is equivalent to C and is just there for notational consistency. @@ -998,6 +1057,7 @@ quantifiers: =over 4 =item * + Principle 3: If there are two or more elements in a regexp, the leftmost greedy (non-greedy) quantifier, if any, will match as much (little) of the string as possible while still allowing the whole @@ -1019,23 +1079,37 @@ backtracking. Here is a step-by-step analysis of the example =over 4 -=item 0 Start with the first letter in the string 't'. +=item 0 + +Start with the first letter in the string 't'. -=item 1 The first quantifier '.*' starts out by matching the whole +=item 1 + +The first quantifier '.*' starts out by matching the whole string 'the cat in the hat'. -=item 2 'a' in the regexp element 'at' doesn't match the end of the +=item 2 + +'a' in the regexp element 'at' doesn't match the end of the string. Backtrack one character. -=item 3 'a' in the regexp element 'at' still doesn't match the last +=item 3 + +'a' in the regexp element 'at' still doesn't match the last letter of the string 't', so backtrack one more character. -=item 4 Now we can match the 'a' and the 't'. +=item 4 + +Now we can match the 'a' and the 't'. -=item 5 Move on to the third element '.*'. Since we are at the end of +=item 5 + +Move on to the third element '.*'. Since we are at the end of the string and '.*' can match 0 times, assign it the empty string. -=item 6 We are done! +=item 6 + +We are done! =back @@ -1180,15 +1254,25 @@ This is our final regexp. To recap, we built a regexp by =over 4 -=item * specifying the task in detail, +=item * + +specifying the task in detail, -=item * breaking down the problem into smaller parts, +=item * + +breaking down the problem into smaller parts, + +=item * -=item * translating the small parts into regexps, +translating the small parts into regexps, -=item * combining the regexps, +=item * + +combining the regexps, + +=item * -=item * and optimizing the final combined regexp. +and optimizing the final combined regexp. =back diff --git a/pod/perlsub.pod b/pod/perlsub.pod index ae128ce..cef8050 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -699,7 +699,9 @@ I use C instead of C. =over 4 -=item 1. You need to give a global variable a temporary value, especially $_. +=item 1. + +You need to give a global variable a temporary value, especially $_. The global variables, like C<@ARGV> or the punctuation variables, must be Cized with C. This block reads in F, and splits @@ -716,7 +718,9 @@ in C<@Fields>. It particular, it's important to Cize $_ in any routine that assigns to it. Look out for implicit assignments in C conditionals. -=item 2. You need to create a local file or directory handle or a local function. +=item 2. + +You need to create a local file or directory handle or a local function. A function that needs a filehandle of its own must use C on a complete typeglob. This can be used to create new symbol @@ -746,7 +750,9 @@ a local alias. See L for more about manipulating functions by name in this way. -=item 3. You want to temporarily change just one element of an array or hash. +=item 3. + +You want to temporarily change just one element of an array or hash. You can Cize just one element of an aggregate. Usually this is done on dynamics: