From: Rafael Garcia-Suarez Date: Sun, 10 Aug 2003 12:32:47 +0000 (+0000) Subject: Add the perlreref manpage, by Iain Truskett X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=30487ceba2ac5c35e693d7aba544e73d6a7dc3f0;p=p5sagit%2Fp5-mst-13.2.git Add the perlreref manpage, by Iain Truskett (regular expressions quick reference.) Regenerate the table of contents. p4raw-id: //depot/perl@20593 --- diff --git a/MANIFEST b/MANIFEST index 035594c..0fc4582 100644 --- a/MANIFEST +++ b/MANIFEST @@ -2360,6 +2360,7 @@ pod/perlre.pod Regular expression info pod/perlref.pod References info pod/perlreftut.pod Mark's references tutorial pod/perlrequick.pod Quick start guide for Perl regular expressions +pod/perlreref.pod Perl regular expressions reference pod/perlretut.pod Tutorial for Perl regular expressions pod/perlrun.pod Execution info pod/perlsec.pod Security info diff --git a/pod/buildtoc.PL b/pod/buildtoc.PL index 3585b7d..5c61a60 100644 --- a/pod/buildtoc.PL +++ b/pod/buildtoc.PL @@ -137,6 +137,7 @@ if (-d "pod") { perlretut perlre + perlreref perlref perlform diff --git a/pod/perl.pod b/pod/perl.pod index 0ec1407..e858fb5 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -71,6 +71,7 @@ For ease of access, the Perl manual has been split up into several sections. perldebug Perl debugging perlvar Perl predefined variables perlre Perl regular expressions, the rest of the story + perlreref Perl regular expressions quick reference perlref Perl references, the rest of the story perlform Perl formats perlobj Perl objects diff --git a/pod/perlreref.pod b/pod/perlreref.pod new file mode 100644 index 0000000..8aad327 --- /dev/null +++ b/pod/perlreref.pod @@ -0,0 +1,284 @@ +=head1 NAME + +perlreref - Perl Regular Expressions Reference + +=head1 DESCRIPTION + +This is a quick reference to Perl's regular expressions. +For full information see L and L, as well +as the L section in this document. + +=head1 OPERATORS + + =~ determines to which variable the regex is applied. + In its absence, C<$_> is used. + + $var =~ /foo/; + + m/pattern/igmsoxc searches a string for a pattern match, + applying the given options. + + i case-Insensitive + g Global - all occurrences + m Multiline mode - ^ and $ match internal lines + s match as a Single line - . matches \n + o compile pattern Once + x eXtended legibility - free whitespace and comments + c don't reset pos on fails when using /g + + If C is an empty string, the last I match + regex is used. Delimiters other than C may be used for both this + operator and the following ones. + + qr/pattern/imsox lets you store a regex in a variable, + or pass one around. Modifiers as for C and are stored + within the regex. + + s/pattern/replacement/igmsoxe substitutes matches of + C with C. Modifiers as for C + with addition of C: + + e Evaluate replacement as an expression + + 'e' may be specified multiple times. 'replacement' is interpreted + as a double quoted string unless a single-quote (') is the delimiter. + + ?pattern? is like C but matches only once. No alternate + delimiters can be used. Must be reset with 'reset'. + +=head1 SYNTAX + + \ Escapes the character(s) immediately following it + . Matches any single character except a newline (unless /s is used) + ^ Matches at the beginning of the string (or line, if /m is used) + $ Matches at the end of the string (or line, if /m is used) + * Matches the preceding element 0 or more times + + Matches the preceding element 1 or more times + ? Matches the preceding element 0 or 1 times + {...} Specifies a range of occurrences for the element preceding it + [...] Matches any one of the characters contained within the brackets + (...) Groups regular expressions + | Matches either the expression preceding or following it + \1, \2 ... The text from the Nth group + +=head2 ESCAPE SEQUENCES + +These work as in normal strings. + + \a Alarm (beep) + \e Escape + \f Formfeed + \n Newline + \r Carriage return + \t Tab + \038 Any octal ASCII value + \x7f Any hexadecimal ASCII value + \x{263a} A wide hexadecimal value + \cx Control-x + \N{name} A named character + + \l Lowercase until next character + \u Uppercase until next character + \L Lowercase until \E + \U Uppercase until \E + \Q Disable pattern metacharacters until \E + \E End case modification + +This one works differently from normal strings: + + \b An assertion, not backspace, except in a character class + +=head2 CHARACTER CLASSES + + [amy] Match 'a', 'm' or 'y' + [f-j] Dash specifies "range" + [f-j-] Dash escaped or at start or end means 'dash' + [^f-j] Caret indicates "match char any _except_ these" + +The following work within or without a character class: + + \d A digit, same as [0-9] + \D A nondigit, same as [^0-9] + \w A word character (alphanumeric), same as [a-zA-Z_0-9] + \W A non-word character, [^a-zA-Z_0-9] + \s A whitespace character, same as [ \t\n\r\f] + \S A non-whitespace character, [^ \t\n\r\f] + \C Match a byte (with Unicode. '.' matches char) + \pP Match P-named (Unicode) property + \p{...} Match Unicode property with long name + \PP Match non-P + \P{...} Match lack of Unicode property with long name + \X Match extended unicode sequence + +POSIX character classes and their Unicode and Perl equivalents: + + alnum IsAlnum Alphanumeric + alpha IsAlpha Alphabetic + ascii IsASCII Any ASCII char + blank IsSpace [ \t] Horizontal whitespace (GNU) + cntrl IsCntrl Control characters + digit IsDigit \d Digits + graph IsGraph Alphanumeric and punctuation + lower IsLower Lowercase chars (locale aware) + print IsPrint Alphanumeric, punct, and space + punct IsPunct Punctuation + space IsSpace [\s\ck] Whitespace + IsSpacePerl \s Perl's whitespace definition + upper IsUpper Uppercase chars (locale aware) + word IsWord \w Alphanumeric plus _ (Perl) + xdigit IsXDigit [\dA-Fa-f] Hexadecimal digit + +Within a character class: + + POSIX traditional Unicode + [:digit:] \d \p{IsDigit} + [:^digit:] \D \P{IsDigit} + +=head2 ANCHORS + +All are zero-width assertions. + + ^ Match string start (or line, if /m is used) + $ Match string end (or line, if /m is used) or before newline + \b Match word boundary (between \w and \W) + \B Match except at word boundary + \A Match string start (regardless of /m) + \Z Match string end (preceding optional newline) + \z Match absolute string end + \G Match where previous m//g left off + \c Suppresses resetting of search position when used with /g. + Without \c, search pattern is reset to the beginning of the string + +=head2 QUANTIFIERS + +Quantifiers are greedy by default --- match the B leftmost. + + Maximal Minimal Allowed range + ------- ------- ------------- + {n,m} {n,m}? Must occur at least n times but no more than m times + {n,} {n,}? Must occur at least n times + {n} {n}? Must match exactly n times + * *? 0 or more times (same as {0,}) + + +? 1 or more times (same as {1,}) + ? ?? 0 or 1 time (same as {0,1}) + +=head2 EXTENDED CONSTRUCTS + + (?#text) A comment + (?:...) Cluster without capturing + (?imxs-imsx:...) Enable/disable option (as per m//) + (?=...) Zero-width positive lookahead assertion + (?!...) Zero-width negative lookahead assertion + (?<...) Zero-width positive lookbehind assertion + (?...) Grab what we can, prohibit backtracking + (?{ code }) Embedded code, return value becomes $^R + (??{ code }) Dynamic regex, return value used as regex + (?(cond)yes|no) cond being int corresponding to capturing parens + (?(cond)yes) or a lookaround/eval zero-width assertion + +=head1 VARIABLES + + $_ Default variable for operators to use + $* Enable multiline matching (deprecated; not in 5.8.1+) + + $& Entire matched string + $` Everything prior to matched string + $' Everything after to matched string + +The use of those last three will slow down B regex use +within your program. Consult L for C<@LAST_MATCH_START> +to see equivalent expressions that won't cause slow down. +See also L. + + $1, $2 ... hold the Xth captured expr + $+ Last parenthesized pattern match + $^N Holds the most recently closed capture + $^R Holds the result of the last (?{...}) expr + @- Offsets of starts of groups. [0] holds start of whole match + @+ Offsets of ends of groups. [0] holds end of whole match + +Capture groups are numbered according to their I paren. + +=head1 FUNCTIONS + + lc Lowercase a string + lcfirst Lowercase first char of a string + uc Uppercase a string + ucfirst Titlecase first char of a string + pos Return or set current match position + quotemeta Quote metacharacters + reset Reset ?pattern? status + study Analyze string for optimizing matching + + split Use regex to split a string into parts + +=head1 AUTHOR + +Iain Truskett. + +This document may be distributed under the same terms as Perl itself. + +=head1 SEE ALSO + +=over 4 + +=item * + +L for a tutorial on regular expressions. + +=item * + +L for a rapid tutorial. + +=item * + +L for more details. + +=item * + +L for details on the variables. + +=item * + +L for details on the operators. + +=item * + +L for details on the functions. + +=item * + +L for FAQs on regular expressions. + +=item * + +The L module to alter behaviour and aid +debugging. + +=item * + +L + +=item * + +L, L, L and L +for details on regexes and internationalisation. + +=item * + +I by Jeffrey Friedl +(F) for a thorough grounding and +reference on the topic. + +=back + +=head1 THANKS + +David P.C. Wollmann, +Richard Soderberg, +Sean M. Burke, +Tom Christiansen, +and +Jeffrey Goff +for useful advice. diff --git a/pod/perltoc.pod b/pod/perltoc.pod index f7cd79a..a1751bb 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -1347,6 +1347,42 @@ C<(?(condition)yes-pattern|no-pattern)> =back +=head2 perlreref - Perl Regular Expressions Reference + +=over 4 + +=item DESCRIPTION + +=item OPERATORS + +=item SYNTAX + +=over 4 + +=item ESCAPE SEQUENCES + +=item CHARACTER CLASSES + +=item ANCHORS + +=item QUANTIFIERS + +=item EXTENDED CONSTRUCTS + +=back + +=item VARIABLES + +=item FUNCTIONS + +=item AUTHOR + +=item SEE ALSO + +=item THANKS + +=back + =head2 perlref - Perl references and nested data structures =over 4 @@ -1907,8 +1943,6 @@ string =back -=item Native threads - =item What kind of threads are Perl threads? =item Thread-Safe Modules @@ -1923,8 +1957,6 @@ string =item Creating Threads -=item Giving up control - =item Waiting For A Thread To Exit =item Ignoring A Thread @@ -1959,6 +1991,8 @@ string =item cond_wait() and cond_signal() +=item Giving up control + =back =item General Thread Utility Routines @@ -1977,6 +2011,8 @@ string =item A Complete Example +=item Different implementations of threads + =item Performance considerations =item Process-scope Changes @@ -2680,23 +2716,23 @@ vmsish, warnings, warnings::register AnyDBM_File, Attribute::Handlers, AutoLoader, AutoSplit, B, B::Asmdata, B::Assembler, B::Bblock, B::Bytecode, B::C, B::CC, B::Concise, B::Debug, B::Deparse, B::Disassembler, B::Lint, B::Showlex, B::Stackobj, B::Stash, -B::Terse, B::Xref, Benchmark, CGI, CGI::Apache, CGI::Carp, CGI::Cookie, -CGI::Fast, CGI::Pretty, CGI::Push, CGI::Switch, CGI::Util, CPAN, -CPAN::FirstTime, CPAN::Nox, Carp, Carp::Heavy, Class::ISA, Class::Struct, -Config, Cwd, DB, DB_File, Data::Dumper, Devel::DProf, Devel::PPPort, -Devel::Peek, Devel::SelfStubber, Digest, Digest::MD5, DirHandle, Dumpvalue, -DynaLoader, Encode, Encode::Alias, Encode::Byte, Encode::CJKConstants, -Encode::CN, Encode::CN::HZ, Encode::Config, Encode::EBCDIC, -Encode::Encoder, Encode::Encoding, Encode::Guess, Encode::JP, -Encode::JP::H2Z, Encode::JP::JIS7, Encode::KR, Encode::KR::2022_KR, -Encode::MIME::Header, Encode::PerlIO, Encode::Supported, Encode::Symbol, -Encode::TW, Encode::Unicode, Encode::Unicode::UTF7, English, Env, Errno, -Exporter, Exporter::Heavy, ExtUtils::Command, ExtUtils::Command::MM, -ExtUtils::Constant, ExtUtils::Embed, ExtUtils::Install, -ExtUtils::Installed, ExtUtils::Liblist, ExtUtils::MM, ExtUtils::MM_Any, -ExtUtils::MM_BeOS, ExtUtils::MM_Cygwin, ExtUtils::MM_DOS, -ExtUtils::MM_MacOS, ExtUtils::MM_NW5, ExtUtils::MM_OS2, ExtUtils::MM_UWIN, -ExtUtils::MM_Unix, ExtUtils::MM_VMS, ExtUtils::MM_Win32, +B::Terse, B::Xref, Benchmark, ByteLoader, CGI, CGI::Apache, CGI::Carp, +CGI::Cookie, CGI::Fast, CGI::Pretty, CGI::Push, CGI::Switch, CGI::Util, +CPAN, CPAN::FirstTime, CPAN::Nox, Carp, Carp::Heavy, Class::ISA, +Class::Struct, Config, Cwd, DB, DB_File, Data::Dumper, Devel::DProf, +Devel::PPPort, Devel::Peek, Devel::SelfStubber, Digest, Digest::MD5, +DirHandle, Dumpvalue, DynaLoader, Encode, Encode::Alias, Encode::Byte, +Encode::CJKConstants, Encode::CN, Encode::CN::HZ, Encode::Config, +Encode::EBCDIC, Encode::Encoder, Encode::Encoding, Encode::Guess, +Encode::JP, Encode::JP::H2Z, Encode::JP::JIS7, Encode::KR, +Encode::KR::2022_KR, Encode::MIME::Header, Encode::PerlIO, +Encode::Supported, Encode::Symbol, Encode::TW, Encode::Unicode, +Encode::Unicode::UTF7, English, Env, Errno, Exporter, Exporter::Heavy, +ExtUtils::Command, ExtUtils::Command::MM, ExtUtils::Constant, +ExtUtils::Embed, ExtUtils::Install, ExtUtils::Installed, ExtUtils::Liblist, +ExtUtils::MM, ExtUtils::MM_Any, ExtUtils::MM_BeOS, ExtUtils::MM_Cygwin, +ExtUtils::MM_DOS, ExtUtils::MM_MacOS, ExtUtils::MM_NW5, ExtUtils::MM_OS2, +ExtUtils::MM_UWIN, ExtUtils::MM_Unix, ExtUtils::MM_VMS, ExtUtils::MM_Win32, ExtUtils::MM_Win95, ExtUtils::MY, ExtUtils::MakeMaker, ExtUtils::MakeMaker::FAQ, ExtUtils::MakeMaker::Tutorial, ExtUtils::MakeMaker::bytes, ExtUtils::MakeMaker::vmsish, @@ -2997,8 +3033,8 @@ Scheme, or Tcl? =back -=head2 perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.20 $, -$Date: 2003/01/26 17:50:56 $) +=head2 perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.21 $, +$Date: 2003/07/30 05:48:24 $) =over 4 @@ -4794,6 +4830,8 @@ Set_ptrcnt =item Implementing PerlIO Layers +C implementations, Perl implementations + =item Core Layers "unix", "perlio", "stdio", "crlf", "mmap", "pending", "raw", "utf8" @@ -12926,7 +12964,7 @@ makemakerdflt_target special_targets -POD2MAN_EXE_macro +POD2MAN_macro test_via_harness @@ -13831,6 +13869,18 @@ B =back +=head2 ExtUtils::Miniperl, writemain - write the C code for perlmain.c + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +=back + =head2 ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader =over 4 @@ -20190,8 +20240,9 @@ timers gettimeofday (), usleep ( $useconds ), ualarm ( $useconds [, $interval_useconds ] ), tv_interval, time (), sleep ( $floating_seconds ), -alarm ( $floating_seconds [, $interval_floating_seconds ] ), setitimer, -getitimer ( $which ) +alarm ( $floating_seconds [, $interval_floating_seconds ] ), setitimer ( +$which, $floating_seconds [, $interval_floating_seconds ] ), getitimer ( +$which ) =item EXAMPLES