Perl has special debugging hooks at compile-time and run-time used
to create debugging environments. These hooks are not to be confused
-with the I<perl -Dxxx> command described in L<perlrun>, which is
-usable only if a special Perl is built per the instructions in the
-F<INSTALL> podpage in the Perl source tree.
+with the I<perl -Dxxx> command described in L<perlrun|perlrun/-Dletters>,
+which is usable only if a special Perl is built per the instructions in
+the F<INSTALL> podpage in the Perl source tree.
For example, whenever you call Perl's built-in C<caller> function
from the package C<DB>, the arguments that the corresponding stack
=item *
-Each scalar C<${"_<$filename"}> contains C<"_<$filename">. This is
+Each scalar C<${"_<$filename"}> contains C<$filename>. This is
also the case for evaluated strings that contain subroutines, or
-which are currently being executed. The $filename for C<eval>ed
+which are currently being executed. The C<$filename> for C<eval>ed
strings looks like C<(eval 34)>.
=item *
=item *
When execution of the program reaches a subroutine call, a call to
-C<&DB::sub>(I<args>) is made instead, with C<$DB::sub> holding the
-name of the called subroutine. (This doesn't happen if the subroutine
-was compiled in the C<DB> package.)
+C<&DB::sub>(I<args>) is made instead, with C<$DB::sub> set to identify
+the called subroutine. (This doesn't happen if the calling subroutine
+was compiled in the C<DB> package.) C<$DB::sub> normally holds the name
+of the called subroutine, if it has a name by which it can be looked up.
+Failing that, C<$DB::sub> will hold a reference to the called subroutine.
+Either way, the C<&DB::sub> subroutine can use C<$DB::sub> as a reference
+by which to call the called subroutine, which it will normally want to do.
X<&DB::lsub>If the call is to an lvalue subroutine, and C<&DB::lsub>
is defined C<&DB::lsub>(I<args>) is called instead, otherwise falling
=item *
-When execution of the program uses C<goto> to enter a non-XS
-subroutine and the 0x80 bit is set in C<$^P>, a call to C<&DB::goto>
-is made, with C<$DB::sub> holding the name of the subroutine being
-entered.
+When execution of the program uses C<goto> to enter a non-XS subroutine
+and the 0x80 bit is set in C<$^P>, a call to C<&DB::goto> is made, with
+C<$DB::sub> set to identify the subroutine being entered. The call to
+C<&DB::goto> does not replace the C<goto>; the requested subroutine will
+still be entered once C<&DB::goto> has returned. C<$DB::sub> normally
+holds the name of the subroutine being entered, if it has one. Failing
+that, C<$DB::sub> will hold a reference to the subroutine being entered.
+Unlike when C<&DB::sub> is called, it is not guaranteed that C<$DB::sub>
+can be used as a reference to operate on the subroutine being entered.
=back
There are two ways to enable debugging output for regular expressions.
If your perl is compiled with C<-DDEBUGGING>, you may use the
-B<-Dr> flag on the command line.
+B<-Dr> flag on the command line, and C<-Drv> for more verbose
+information.
-Otherwise, one can C<use re 'debug'>, which has effects at
+Otherwise, one can C<use re 'debug'>, which has effects at both
compile time and run time. Since Perl 5.9.5, this pragma is lexically
scoped.
=for regcomp.pl begin
- # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
+ # TYPE arg-description [regnode-struct-suffix] [longjump-len] DESCRIPTION
# Exit points
- END no End of program.
- SUCCEED no Return from a subroutine, basically.
+ END no End of program.
+ SUCCEED no Return from a subroutine, basically.
# Line Start Anchors:
- SBOL no Match "" at beginning of line: /^/, /\A/
- MBOL no Same, assuming multiline: /^/m
+ SBOL no Match "" at beginning of line: /^/, /\A/
+ MBOL no Same, assuming multiline: /^/m
# Line End Anchors:
- SEOL no Match "" at end of line: /$/
- MEOL no Same, assuming multiline: /$/m
- EOS no Match "" at end of string: /\z/
+ SEOL no Match "" at end of line: /$/
+ MEOL no Same, assuming multiline: /$/m
+ EOS no Match "" at end of string: /\z/
# Match Start Anchors:
- GPOS no Matches where last m//g left off.
+ GPOS no Matches where last m//g left off.
# Word Boundary Opcodes:
- BOUND no Like BOUNDA for non-utf8, otherwise match ""
- between any Unicode \w\W or \W\w
- BOUNDL no Like BOUND/BOUNDU, but \w and \W are defined
- by current locale
- BOUNDU no Match "" at any boundary of a given type
- using Unicode rules
- BOUNDA no Match "" at any boundary between \w\W or
- \W\w, where \w is [_a-zA-Z0-9]
- NBOUND no Like NBOUNDA for non-utf8, otherwise match
- "" between any Unicode \w\w or \W\W
- NBOUNDL no Like NBOUND/NBOUNDU, but \w and \W are
- defined by current locale
- NBOUNDU no Match "" at any non-boundary of a given type
- using using Unicode rules
- NBOUNDA no Match "" betweeen any \w\w or \W\W, where \w
- is [_a-zA-Z0-9]
+ BOUND no Like BOUNDA for non-utf8, otherwise like
+ BOUNDU
+ BOUNDL no Like BOUND/BOUNDU, but \w and \W are
+ defined by current locale
+ BOUNDU no Match "" at any boundary of a given type
+ using /u rules.
+ BOUNDA no Match "" at any boundary between \w\W or
+ \W\w, where \w is [_a-zA-Z0-9]
+ NBOUND no Like NBOUNDA for non-utf8, otherwise like
+ BOUNDU
+ NBOUNDL no Like NBOUND/NBOUNDU, but \w and \W are
+ defined by current locale
+ NBOUNDU no Match "" at any non-boundary of a given
+ type using using /u rules.
+ NBOUNDA no Match "" betweeen any \w\w or \W\W, where
+ \w is [_a-zA-Z0-9]
# [Special] alternatives:
- REG_ANY no Match any one character (except newline).
- SANY no Match any one character.
- ANYOF sv 1 Match character in (or not in) this class,
- single char match only
- ANYOFD sv 1 Like ANYOF, but /d is in effect
- ANYOFL sv 1 Like ANYOF, but /l is in effect
+ REG_ANY no Match any one character (except newline).
+ SANY no Match any one character.
+ ANYOF sv Match character in (or not in) this class,
+ charclass single char match only
+ ANYOFD sv Like ANYOF, but /d is in effect
+ charclass
+ ANYOFL sv Like ANYOF, but /l is in effect
+ charclass
+ ANYOFPOSIXL sv Like ANYOFL, but matches [[:posix:]]
+ charclass_ classes
+ posixl
+
+ ANYOFH sv 1 Like ANYOF, but only has "High" matches,
+ none in the bitmap; the flags field
+ contains the lowest matchable UTF-8 start
+ byte
+ ANYOFHb sv 1 Like ANYOFH, but all matches share the same
+ UTF-8 start byte, given in the flags field
+ ANYOFHr sv 1 Like ANYOFH, but the flags field contains
+ packed bounds for all matchable UTF-8 start
+ bytes.
+ ANYOFHs sv 1 Like ANYOFHb, but has a string field that
+ gives the leading matchable UTF-8 bytes;
+ flags field is len
+ ANYOFR packed 1 Matches any character in the range given by
+ its packed args: upper 12 bits is the max
+ delta from the base lower 20; the flags
+ field contains the lowest matchable UTF-8
+ start byte
+ ANYOFRb packed 1 Like ANYOFR, but all matches share the same
+ UTF-8 start byte, given in the flags field
+
+ ANYOFM byte 1 Like ANYOF, but matches an invariant byte
+ as determined by the mask and arg
+ NANYOFM byte 1 complement of ANYOFM
# POSIX Character Classes:
- POSIXD none Some [[:class:]] under /d; the FLAGS field
- gives which one
- POSIXL none Some [[:class:]] under /l; the FLAGS field
- gives which one
- POSIXU none Some [[:class:]] under /u; the FLAGS field
- gives which one
- POSIXA none Some [[:class:]] under /a; the FLAGS field
- gives which one
- NPOSIXD none complement of POSIXD, [[:^class:]]
- NPOSIXL none complement of POSIXL, [[:^class:]]
- NPOSIXU none complement of POSIXU, [[:^class:]]
- NPOSIXA none complement of POSIXA, [[:^class:]]
-
- CLUMP no Match any extended grapheme cluster sequence
+ POSIXD none Some [[:class:]] under /d; the FLAGS field
+ gives which one
+ POSIXL none Some [[:class:]] under /l; the FLAGS field
+ gives which one
+ POSIXU none Some [[:class:]] under /u; the FLAGS field
+ gives which one
+ POSIXA none Some [[:class:]] under /a; the FLAGS field
+ gives which one
+ NPOSIXD none complement of POSIXD, [[:^class:]]
+ NPOSIXL none complement of POSIXL, [[:^class:]]
+ NPOSIXU none complement of POSIXU, [[:^class:]]
+ NPOSIXA none complement of POSIXA, [[:^class:]]
+
+ CLUMP no Match any extended grapheme cluster
+ sequence
# Alternation
# pointer of each individual branch points; each branch
# starts with the operand node of a BRANCH node.
#
- BRANCH node Match this alternative, or the next...
+ BRANCH node Match this alternative, or the next...
# Literals
- EXACT str Match this string (preceded by length).
- EXACTL str Like EXACT, but /l is in effect (used so
- locale-related warnings can be checked for).
- EXACTF str Match this non-UTF-8 string (not guaranteed
- to be folded) using /id rules (w/len).
- EXACTFL str Match this string (not guaranteed to be
- folded) using /il rules (w/len).
- EXACTFU str Match this string (folded iff in UTF-8,
- length in folding doesn't change if not in
- UTF-8) using /iu rules (w/len).
- EXACTFA str Match this string (not guaranteed to be
- folded) using /iaa rules (w/len).
-
- EXACTFU_SS str Match this string (folded iff in UTF-8,
- length in folding may change even if not in
- UTF-8) using /iu rules (w/len).
- EXACTFLU8 str Rare cirucmstances: like EXACTFU, but is
- under /l, UTF-8, folded, and everything in
- it is above 255.
- EXACTFA_NO_TRIE str Match this string (which is not trie-able;
- not guaranteed to be folded) using /iaa
- rules (w/len).
+ EXACT str Match this string (flags field is the
+ length).
+
+ # In a long string node, the U32 argument is the length, and is
+ # immediately followed by the string.
+ LEXACT len:str 1 Match this long string (preceded by length;
+ flags unused).
+ EXACTL str Like EXACT, but /l is in effect (used so
+ locale-related warnings can be checked for)
+ EXACTF str Like EXACT, but match using /id rules;
+ (string not UTF-8, ASCII folded; non-ASCII
+ not)
+ EXACTFL str Like EXACT, but match using /il rules;
+ (string not likely to be folded)
+ EXACTFU str Like EXACT, but match using /iu rules;
+ (string folded)
+
+ EXACTFAA str Like EXACT, but match using /iaa rules;
+ (string folded except MICRO in non-UTF8
+ patterns; doesn't contain SHARP S unless
+ UTF-8; folded length <= unfolded)
+ EXACTFAA_NO_TRIE str Like EXACTFAA, (string not UTF-8, folded
+ except: MICRO, SHARP S; folded length <=
+ unfolded, not currently trie-able)
+
+ EXACTFUP str Like EXACT, but match using /iu rules;
+ (string not UTF-8, folded except MICRO:
+ hence Problematic)
+
+ EXACTFLU8 str Like EXACTFU, but use /il, UTF-8, (string
+ is folded, and everything in it is above
+ 255
+
+ EXACT_REQ8 str Like EXACT, but only UTF-8 encoded targets
+ can match
+ LEXACT_REQ8 len:str 1 Like LEXACT, but only UTF-8 encoded targets
+ can match
+ EXACTFU_REQ8 str Like EXACTFU, but only UTF-8 encoded
+ targets can match
+
+ EXACTFU_S_EDGE str /di rules, but nothing in it precludes /ui,
+ except begins and/or ends with [Ss];
+ (string not UTF-8; compile-time only)
+
+ # New charclass like patterns
+ LNBREAK none generic newline pattern
+
+ # Trie Related
+
+ # Behave the same as A|LIST|OF|WORDS would. The '..C' variants
+ # have inline charclass data (ascii only), the 'C' store it in the
+ # structure.
+
+ TRIE trie 1 Match many EXACT(F[ALU]?)? at once.
+ flags==type
+ TRIEC trie Same as TRIE, but with embedded charclass
+ charclass data
+
+ AHOCORASICK trie 1 Aho Corasick stclass. flags==type
+ AHOCORASICKC trie Same as AHOCORASICK, but with embedded
+ charclass charclass data
# Do nothing types
- NOTHING no Match empty string.
+ NOTHING no Match empty string.
# A variant of above which delimits a group, thus stops optimizations
- TAIL no Match empty string. Can jump here from
- outside.
+ TAIL no Match empty string. Can jump here from
+ outside.
# Loops
# (one character per match) are implemented with STAR
# and PLUS for speed and to minimize recursive plunges.
#
- STAR node Match this (simple) thing 0 or more times.
- PLUS node Match this (simple) thing 1 or more times.
+ STAR node Match this (simple) thing 0 or more times.
+ PLUS node Match this (simple) thing 1 or more times.
- CURLY sv 2 Match this simple thing {n,m} times.
- CURLYN no 2 Capture next-after-this simple thing
- CURLYM no 2 Capture this medium-complex thing {n,m}
- times.
- CURLYX sv 2 Match this complex thing {n,m} times.
+ CURLY sv 2 Match this simple thing {n,m} times.
+ CURLYN no 2 Capture next-after-this simple thing
+ CURLYM no 2 Capture this medium-complex thing {n,m}
+ times.
+ CURLYX sv 2 Match this complex thing {n,m} times.
# This terminator creates a loop structure for CURLYX
- WHILEM no Do curly processing and see if rest matches.
+ WHILEM no Do curly processing and see if rest
+ matches.
# Buffer related
# OPEN,CLOSE,GROUPP ...are numbered at compile time.
- OPEN num 1 Mark this point in input as start of #n.
- CLOSE num 1 Analogous to OPEN.
-
- REF num 1 Match some already matched string
- REFF num 1 Match already matched string, folded using
- native charset rules for non-utf8
- REFFL num 1 Match already matched string, folded in loc.
- REFFU num 1 Match already matched string, folded using
- unicode rules for non-utf8
- REFFA num 1 Match already matched string, folded using
- unicode rules for non-utf8, no mixing ASCII,
- non-ASCII
+ OPEN num 1 Mark this point in input as start of #n.
+ CLOSE num 1 Close corresponding OPEN of #n.
+ SROPEN none Same as OPEN, but for script run
+ SRCLOSE none Close preceding SROPEN
+
+ REF num 1 Match some already matched string
+ REFF num 1 Match already matched string, using /di
+ rules.
+ REFFL num 1 Match already matched string, using /li
+ rules.
+ REFFU num 1 Match already matched string, usng /ui.
+ REFFA num 1 Match already matched string, using /aai
+ rules.
# Named references. Code in regcomp.c assumes that these all are after
# the numbered references
- NREF no-sv 1 Match some already matched string
- NREFF no-sv 1 Match already matched string, folded using
- native charset rules for non-utf8
- NREFFL no-sv 1 Match already matched string, folded in loc.
- NREFFU num 1 Match already matched string, folded using
- unicode rules for non-utf8
- NREFFA num 1 Match already matched string, folded using
- unicode rules for non-utf8, no mixing ASCII,
- non-ASCII
+ REFN no-sv 1 Match some already matched string
+ REFFN no-sv 1 Match already matched string, using /di
+ rules.
+ REFFLN no-sv 1 Match already matched string, using /li
+ rules.
+ REFFUN num 1 Match already matched string, using /ui
+ rules.
+ REFFAN num 1 Match already matched string, using /aai
+ rules.
# Support for long RE
- LONGJMP off 1 1 Jump far away.
- BRANCHJ off 1 1 BRANCH with long offset.
+ LONGJMP off 1 1 Jump far away.
+ BRANCHJ off 1 1 BRANCH with long offset.
# Special Case Regops
- IFMATCH off 1 2 Succeeds if the following matches.
- UNLESSM off 1 2 Fails if the following matches.
- SUSPEND off 1 1 "Independent" sub-RE.
- IFTHEN off 1 1 Switch, should be preceded by switcher.
- GROUPP num 1 Whether the group matched.
+ IFMATCH off 1 1 Succeeds if the following matches; non-zero
+ flags "f", next_off "o" means lookbehind
+ assertion starting "f..(f-o)" characters
+ before current
+ UNLESSM off 1 1 Fails if the following matches; non-zero
+ flags "f", next_off "o" means lookbehind
+ assertion starting "f..(f-o)" characters
+ before current
+ SUSPEND off 1 1 "Independent" sub-RE.
+ IFTHEN off 1 1 Switch, should be preceded by switcher.
+ GROUPP num 1 Whether the group matched.
# The heavy worker
- EVAL evl/flags Execute some Perl code.
- 2L
+ EVAL evl/flags Execute some Perl code.
+ 2L
# Modifiers
- MINMOD no Next operator is not greedy.
- LOGICAL no Next opcode should set the flag only.
+ MINMOD no Next operator is not greedy.
+ LOGICAL no Next opcode should set the flag only.
# This is not used yet
- RENUM off 1 1 Group with independently numbered parens.
-
- # Trie Related
-
- # Behave the same as A|LIST|OF|WORDS would. The '..C' variants
- # have inline charclass data (ascii only), the 'C' store it in the
- # structure.
-
- TRIE trie 1 Match many EXACT(F[ALU]?)? at once.
- flags==type
- TRIEC trie Same as TRIE, but with embedded charclass
- charclass data
-
- AHOCORASICK trie 1 Aho Corasick stclass. flags==type
- AHOCORASICKC trie Same as AHOCORASICK, but with embedded
- charclass charclass data
+ RENUM off 1 1 Group with independently numbered parens.
# Regex Subroutines
- GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs arg2
+ GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs arg2
# Special conditionals
- NGROUPP no-sv 1 Whether the group matched.
- INSUBP num 1 Whether we are in a specific recurse.
- DEFINEP none 1 Never execute directly.
+ GROUPPN no-sv 1 Whether the group matched.
+ INSUBP num 1 Whether we are in a specific recurse.
+ DEFINEP none 1 Never execute directly.
# Backtracking Verbs
- ENDLIKE none Used only for the type field of verbs
- OPFAIL no-sv 1 Same as (?!), but with verb arg
- ACCEPT no-sv/num Accepts the current matched string, with
- 2L verbar
+ ENDLIKE none Used only for the type field of verbs
+ OPFAIL no-sv 1 Same as (?!), but with verb arg
+ ACCEPT no-sv/num Accepts the current matched string, with
+ 2L verbar
# Verbs With Arguments
- VERB no-sv 1 Used only for the type field of verbs
- PRUNE no-sv 1 Pattern fails at this startpoint if no-
- backtracking through this
- MARKPOINT no-sv 1 Push the current location for rollback by
- cut.
- SKIP no-sv 1 On failure skip forward (to the mark) before
- retrying
- COMMIT no-sv 1 Pattern fails outright if backtracking
- through this
- CUTGROUP no-sv 1 On failure go to the next alternation in the
- group
+ VERB no-sv 1 Used only for the type field of verbs
+ PRUNE no-sv 1 Pattern fails at this startpoint if no-
+ backtracking through this
+ MARKPOINT no-sv 1 Push the current location for rollback by
+ cut.
+ SKIP no-sv 1 On failure skip forward (to the mark)
+ before retrying
+ COMMIT no-sv 1 Pattern fails outright if backtracking
+ through this
+ CUTGROUP no-sv 1 On failure go to the next alternation in
+ the group
# Control what to keep in $&.
- KEEPS no $& begins here.
-
- # New charclass like patterns
- LNBREAK none generic newline pattern
+ KEEPS no $& begins here.
# SPECIAL REGOPS
# This is not really a node, but an optimized away piece of a "long"
# node. To simplify debugging output, we mark it as if it were a node
- OPTIMIZED off Placeholder for dump.
+ OPTIMIZED off Placeholder for dump.
# Special opcode with the property that no opcode in a compiled program
# will ever be of this type. Thus it can be used as a flag value that
# no other opcode has been seen. END is used similarly, in that an END
# node cant be optimized. So END implies "unoptimizable" and PSEUDO
# mean "not seen anything to optimize yet".
- PSEUDO off Pseudo opcode for internal use.
+ PSEUDO off Pseudo opcode for internal use.
+
+ REGEX_SET depth p Regex set, temporary node used in pre-
+ optimization compilation
=for regcomp.pl end
=head1 SEE ALSO
L<perldebug>,
+L<perl5db.pl>,
L<perlguts>,
-L<perlrun>
+L<perlrun>,
L<re>,
and
L<Devel::DProf>.
https://perl5.git.perl.org / perl5.git / blobdiff