This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add release date of 5.20.1-RC1
[perl5.git] / pod / perlreguts.pod
index 125a9f9..eac08f5 100644 (file)
@@ -20,7 +20,7 @@ the regex engine, or understand how the regex engine works. Readers of
 this document are expected to understand perl's regex syntax and its
 usage in detail. If you want to learn about the basics of Perl's
 regular expressions, see L<perlre>. And if you want to replace the
-regex engine with your own see see L<perlreapi>.
+regex engine with your own, see L<perlreapi>.
 
 =head1 OVERVIEW
 
@@ -168,23 +168,29 @@ multiple of four bytes:
 
 =item C<regnode_charclass>
 
-Character classes are represented by C<regnode_charclass> structures,
-which have a four-byte argument and then a 32-byte (256-bit) bitmap
-indicating which characters are included in the class.
+Bracketed character classes are represented by C<regnode_charclass>
+structures, which have a four-byte argument and then a 32-byte (256-bit)
+bitmap indicating which characters in the Latin1 range are included in
+the class.
 
     regnode_charclass        U32 arg1;
                              char bitmap[ANYOF_BITMAP_SIZE];
 
-=item C<regnode_charclass_class>
+Various flags whose names begin with C<ANYOF_> are used for special
+situations.  Above Latin1 matches and things not known until run-time
+are stored in L</Perl's pprivate structure>.
+
+=item C<regnode_charclass_posixl>
 
 There is also a larger form of a char class structure used to represent
-POSIX char classes called C<regnode_charclass_class> which has an
-additional 4-byte (32-bit) bitmap indicating which POSIX char classes
+POSIX char classes under C</l> matching,
+called C<regnode_charclass_posixl> which has an
+additional 32-bit bitmap indicating which POSIX char classes
 have been included.
 
-    regnode_charclass_class  U32 arg1;
-                             char bitmap[ANYOF_BITMAP_SIZE];
-                             char classflags[ANYOF_CLASSBITMAP_SIZE];
+   regnode_charclass_posixl U32 arg1;
+                            char bitmap[ANYOF_BITMAP_SIZE];
+                            U32 classflags;
 
 =back
 
@@ -222,7 +228,7 @@ always be so.
 =item *
 
 There is the "next regop" from a given regop/regnode. This is the
-regop physically located after the the current one, as determined by
+regop physically located after the current one, as determined by
 the size of the current regop. This is often useful, such as when
 dumping the structure we use this order to traverse. Sometimes the code
 assumes that the "next regnode" is the same as the "next regop", or in
@@ -354,20 +360,23 @@ simpler form.
 
 The call graph looks like this:
 
-    reg()                        # parse a top level regex, or inside of parens
-        regbranch()              # parse a single branch of an alternation
-            regpiece()           # parse a pattern followed by a quantifier
-                regatom()        # parse a simple pattern
-                    regclass()   #   used to handle a class
-                    reg()        #   used to handle a parenthesised subpattern
-                    ....
-            ...
-            regtail()            # finish off the branch
-        ...
-        regtail()                # finish off the branch sequence. Tie each
-                                 # branch's tail to the tail of the sequence
-                                 # (NEW) In Debug mode this is
-                                 # regtail_study().
+ reg()                        # parse a top level regex, or inside of
+                              # parens
+     regbranch()              # parse a single branch of an alternation
+         regpiece()           # parse a pattern followed by a quantifier
+             regatom()        # parse a simple pattern
+                 regclass()   #   used to handle a class
+                 reg()        #   used to handle a parenthesised
+                              #   subpattern
+                 ....
+         ...
+         regtail()            # finish off the branch
+     ...
+     regtail()                # finish off the branch sequence. Tie each
+                              # branch's tail to the tail of the
+                              # sequence
+                              # (NEW) In Debug mode this is
+                              # regtail_study().
 
 A grammar form might be something like this:
 
@@ -383,9 +392,55 @@ A grammar form might be something like this:
     piece : _piece
           | _piece quant
 
+=head3 Parsing complications
+
+The implication of the above description is that a pattern containing nested
+parentheses will result in a call graph which cycles through C<reg()>,
+C<regbranch()>, C<regpiece()>, C<regatom()>, C<reg()>, C<regbranch()> I<etc>
+multiple times, until the deepest level of nesting is reached. All the above
+routines return a pointer to a C<regnode>, which is usually the last regnode
+added to the program. However, one complication is that reg() returns NULL
+for parsing C<(?:)> syntax for embedded modifiers, setting the flag
+C<TRYAGAIN>. The C<TRYAGAIN> propagates upwards until it is captured, in
+some cases by C<regatom()>, but otherwise unconditionally by
+C<regbranch()>. Hence it will never be returned by C<regbranch()> to
+C<reg()>. This flag permits patterns such as C<(?i)+> to be detected as
+errors (I<Quantifier follows nothing in regex; marked by <-- HERE in m/(?i)+
+<-- HERE />).
+
+Another complication is that the representation used for the program differs
+if it needs to store Unicode, but it's not always possible to know for sure
+whether it does until midway through parsing. The Unicode representation for
+the program is larger, and cannot be matched as efficiently. (See L</Unicode
+and Localisation Support> below for more details as to why.)  If the pattern
+contains literal Unicode, it's obvious that the program needs to store
+Unicode. Otherwise, the parser optimistically assumes that the more
+efficient representation can be used, and starts sizing on this basis.
+However, if it then encounters something in the pattern which must be stored
+as Unicode, such as an C<\x{...}> escape sequence representing a character
+literal, then this means that all previously calculated sizes need to be
+redone, using values appropriate for the Unicode representation. Currently,
+all regular expression constructions which can trigger this are parsed by code
+in C<regatom()>.
+
+To avoid wasted work when a restart is needed, the sizing pass is abandoned
+- C<regatom()> immediately returns NULL, setting the flag C<RESTART_UTF8>.
+(This action is encapsulated using the macro C<REQUIRE_UTF8>.) This restart
+request is propagated up the call chain in a similar fashion, until it is
+"caught" in C<Perl_re_op_compile()>, which marks the pattern as containing
+Unicode, and restarts the sizing pass. It is also possible for constructions
+within run-time code blocks to turn out to need Unicode representation.,
+which is signalled by C<S_compile_runtime_code()> returning false to
+C<Perl_re_op_compile()>.
+
+The restart was previously implemented using a C<longjmp> in C<regatom()>
+back to a C<setjmp> in C<Perl_re_op_compile()>, but this proved to be
+problematic as the latter is a large function containing many automatic
+variables, which interact badly with the emergent control flow of C<setjmp>.
+
 =head3 Debug Output
 
-In the 5.9.x development version of perl you can C<<use re Debug => 'PARSE'>>
+In the 5.9.x development version of perl you can C<< use re Debug => 'PARSE' >>
 to see some trace information about the parse process. We will start with some
 simple patterns and build up to more complex patterns.
 
@@ -489,11 +544,11 @@ Now for something much more complex: C</x(?:foo*|b[a][rR])(foo|bar)$/>
                                       atom
  >)$<             34              tail~ BRANCH (28)
                   36              tsdy~ BRANCH (END) (31)
-                                      ~ attach to CLOSE1 (34) offset to 3
+                                     ~ attach to CLOSE1 (34) offset to 3
                                   tsdy~ EXACT <foo> (EXACT) (29)
-                                      ~ attach to CLOSE1 (34) offset to 5
+                                     ~ attach to CLOSE1 (34) offset to 5
                                   tsdy~ EXACT <bar> (EXACT) (32)
-                                      ~ attach to CLOSE1 (34) offset to 2
+                                     ~ attach to CLOSE1 (34) offset to 2
  >$<                        tail~ BRANCH (3)
                                 ~ BRANCH (9)
                                 ~ TAIL (25)
@@ -617,20 +672,20 @@ finding the start point in the string where we should match from,
 and the second being running the regop interpreter.
 
 If we can tell that there is no valid start point then we don't bother running
-interpreter at all. Likewise, if we know from the analysis phase that we
+the interpreter at all. Likewise, if we know from the analysis phase that we
 cannot detect a short-cut to the start position, we go straight to the
 interpreter.
 
 The two entry points are C<re_intuit_start()> and C<pregexec()>. These routines
 have a somewhat incestuous relationship with overlap between their functions,
 and C<pregexec()> may even call C<re_intuit_start()> on its own. Nevertheless
-other parts of the the perl source code may call into either, or both.
+other parts of the perl source code may call into either, or both.
 
 Execution of the interpreter itself used to be recursive, but thanks to the
 efforts of Dave Mitchell in the 5.9.x development track, that has changed: now an
 internal stack is maintained on the heap and the routine is fully
 iterative. This can make it tricky as the code is quite conservative
-about what state it stores, with the result that that two consecutive lines in the
+about what state it stores, with the result that two consecutive lines in the
 code can actually be running in totally different contexts due to the
 simulated recursion.
 
@@ -685,7 +740,7 @@ that is a permissive version of Unicode's UTF-8 encoding[2]. This uses single
 bytes to represent characters from the ASCII character set, and sequences
 of two or more bytes for all other characters. (See L<perlunitut>
 for more information about the relationship between UTF-8 and perl's
-encoding, utf8 -- the difference isn't important for this discussion.)
+encoding, utf8. The difference isn't important for this discussion.)
 
 No matter how you look at it, Unicode support is going to be a pain in a
 regex engine. Tricks that might be fine when you have 256 possible
@@ -712,40 +767,10 @@ Care must be taken when making changes to make sure that you handle
 UTF-8 properly, both at compile time and at execution time, including
 when the string and pattern are mismatched.
 
-The following comment in F<regcomp.h> gives an example of exactly how
-tricky this can be:
-
-    Two problematic code points in Unicode casefolding of EXACT nodes:
-
-    U+0390 - GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS
-    U+03B0 - GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS
-
-    which casefold to
-
-    Unicode                      UTF-8
-
-    U+03B9 U+0308 U+0301         0xCE 0xB9 0xCC 0x88 0xCC 0x81
-    U+03C5 U+0308 U+0301         0xCF 0x85 0xCC 0x88 0xCC 0x81
-
-    This means that in case-insensitive matching (or "loose matching",
-    as Unicode calls it), an EXACTF of length six (the UTF-8 encoded
-    byte length of the above casefolded versions) can match a target
-    string of length two (the byte length of UTF-8 encoded U+0390 or
-    U+03B0). This would rather mess up the minimum length computation.
-
-    What we'll do is to look for the tail four bytes, and then peek
-    at the preceding two bytes to see whether we need to decrease
-    the minimum length by four (six minus two).
-
-    Thanks to the design of UTF-8, there cannot be false matches:
-    A sequence of valid UTF-8 bytes cannot be a subsequence of
-    another valid sequence of UTF-8 bytes.
-
-
 =head2 Base Structures
 
 The C<regexp> structure described in L<perlreapi> is common to all
-regex engines. Two of its fields that are intended for the private use
+regex engines. Two of its fields are intended for the private use
 of the regex engine that compiled the pattern. These are the
 C<intflags> and pprivate members. The C<pprivate> is a void pointer to
 an arbitrary structure whose use and management is the responsibility
@@ -762,10 +787,10 @@ the engine currently being. used and some of its fields read by perl to
 implement things such as the stringification of C<qr//>.
 
 
-The other structure is pointed to be the C<regexp> struct's
+The other structure is pointed to by the C<regexp> struct's
 C<pprivate> and is in addition to C<intflags> in the same struct
 considered to be the property of the regex engine which compiled the
-regular expression; 
+regular expression;
 
 The regexp structure contains all the data that perl needs to be aware of
 to properly work with the regular expression. It includes data about
@@ -792,32 +817,24 @@ The following structure is used as the C<pprivate> struct by perl's
 regex engine. Since it is specific to perl it is only of curiosity
 value to other engine implementations.
 
-    typedef struct regexp_internal {
-            regexp_paren_ofs *swap; /* Swap copy of *startp / *endp */
-            U32 *offsets;           /* offset annotations 20001228 MJD 
-                                       data about mapping the program to the 
-                                       string*/
-            regnode *regstclass;    /* Optional startclass as identified or constructed
-                                       by the optimiser */
-            struct reg_data *data;  /* Additional miscellaneous data used by the program.
-                                       Used to make it easier to clone and free arbitrary
-                                       data that the regops need. Often the ARG field of
-                                       a regop is an index into this structure */
-            regnode program[1];     /* Unwarranted chumminess with compiler. */
-    } regexp_internal;
+ typedef struct regexp_internal {
+         U32 *offsets;           /* offset annotations 20001228 MJD
+                                  * data about mapping the program to
+                                  * the string*/
+         regnode *regstclass;    /* Optional startclass as identified or
+                                  * constructed by the optimiser */
+         struct reg_data *data;  /* Additional miscellaneous data used
+                                  * by the program.  Used to make it
+                                  * easier to clone and free arbitrary
+                                  * data that the regops need. Often the
+                                  * ARG field of a regop is an index
+                                  * into this structure */
+         regnode program[1];     /* Unwarranted chumminess with
+                                  * compiler. */
+ } regexp_internal;
 
 =over 5
 
-=item C<swap>
-
-C<swap> is an extra set of startp/endp stored in a C<regexp_paren_ofs>
-struct. This is used when the last successful match was from the same pattern
-as the current pattern, so that a partial match doesn't overwrite the
-previous match's results. When this field is data filled the matching
-engine will swap buffers before every match attempt. If the match fails,
-then it swaps them back. If it's successful it leaves them. This field
-is populated on demand and is by default null.
-
 =item C<offsets>
 
 Offsets holds a mapping of offset in the C<program>
@@ -836,7 +853,7 @@ an independent synthetic regop that has been constructed by the optimiser.
 
 =item C<data>
 
-This field points at a reg_data structure, which is defined as follows
+This field points at a C<reg_data> structure, which is defined as follows
 
     struct reg_data {
         U32 count;