summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perldebguts.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perldebguts.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perldebguts.pod1000
1 files changed, 0 insertions, 1000 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perldebguts.pod b/Master/tlpkg/tlperl/lib/pods/perldebguts.pod
deleted file mode 100644
index 8ae6e7baa96..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perldebguts.pod
+++ /dev/null
@@ -1,1000 +0,0 @@
-=head1 NAME
-
-perldebguts - Guts of Perl debugging
-
-=head1 DESCRIPTION
-
-This is not L<perldebug>, which tells you how to use
-the debugger. This manpage describes low-level details concerning
-the debugger's internals, which range from difficult to impossible
-to understand for anyone who isn't incredibly intimate with Perl's guts.
-Caveat lector.
-
-=head1 Debugger Internals
-
-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.
-
-For example, whenever you call Perl's built-in C<caller> function
-from the package C<DB>, the arguments that the corresponding stack
-frame was called with are copied to the C<@DB::args> array. These
-mechanisms are enabled by calling Perl with the B<-d> switch.
-Specifically, the following additional features are enabled
-(cf. L<perlvar/$^P>):
-
-=over 4
-
-=item *
-
-Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require
-'perl5db.pl'}> if not present) before the first line of your program.
-
-=item *
-
-Each array C<@{"_<$filename"}> holds the lines of $filename for a
-file compiled by Perl. The same is also true for C<eval>ed strings
-that contain subroutines, or which are currently being executed.
-The $filename for C<eval>ed strings looks like C<(eval 34)>.
-Code assertions in regexes look like C<(re_eval 19)>.
-
-Values in this array are magical in numeric context: they compare
-equal to zero only if the line is not breakable.
-
-=item *
-
-Each hash C<%{"_<$filename"}> contains breakpoints and actions keyed
-by line number. Individual entries (as opposed to the whole hash)
-are settable. Perl only cares about Boolean true here, although
-the values used by F<perl5db.pl> have the form
-C<"$break_condition\0$action">.
-
-The same holds for evaluated strings that contain subroutines, or
-which are currently being executed. The $filename for C<eval>ed strings
-looks like C<(eval 34)> or C<(re_eval 19)>.
-
-=item *
-
-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
-strings looks like C<(eval 34)> or C<(re_eval 19)>.
-
-=item *
-
-After each C<require>d file is compiled, but before it is executed,
-C<DB::postponed(*{"_<$filename"})> is called if the subroutine
-C<DB::postponed> exists. Here, the $filename is the expanded name of
-the C<require>d file, as found in the values of %INC.
-
-=item *
-
-After each subroutine C<subname> is compiled, the existence of
-C<$DB::postponed{subname}> is checked. If this key exists,
-C<DB::postponed(subname)> is called if the C<DB::postponed> subroutine
-also exists.
-
-=item *
-
-A hash C<%DB::sub> is maintained, whose keys are subroutine names
-and whose values have the form C<filename:startline-endline>.
-C<filename> has the form C<(eval 34)> for subroutines defined inside
-C<eval>s, or C<(re_eval 19)> for those within regex code assertions.
-
-=item *
-
-When the execution of your program reaches a point that can hold a
-breakpoint, the C<DB::DB()> subroutine is called if any of the variables
-C<$DB::trace>, C<$DB::single>, or C<$DB::signal> is true. These variables
-are not C<local>izable. This feature is disabled when executing
-inside C<DB::DB()>, including functions called from it
-unless C<< $^D & (1<<30) >> is true.
-
-=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.)
-
-=back
-
-Note that if C<&DB::sub> needs external data for it to work, no
-subroutine call is possible without it. As an example, the standard
-debugger's C<&DB::sub> depends on the C<$DB::deep> variable
-(it defines how many levels of recursion deep into the debugger you can go
-before a mandatory break). If C<$DB::deep> is not defined, subroutine
-calls are not possible, even though C<&DB::sub> exists.
-
-=head2 Writing Your Own Debugger
-
-=head3 Environment Variables
-
-The C<PERL5DB> environment variable can be used to define a debugger.
-For example, the minimal "working" debugger (it actually doesn't do anything)
-consists of one line:
-
- sub DB::DB {}
-
-It can easily be defined like this:
-
- $ PERL5DB="sub DB::DB {}" perl -d your-script
-
-Another brief debugger, slightly more useful, can be created
-with only the line:
-
- sub DB::DB {print ++$i; scalar <STDIN>}
-
-This debugger prints a number which increments for each statement
-encountered and waits for you to hit a newline before continuing
-to the next statement.
-
-The following debugger is actually useful:
-
- {
- package DB;
- sub DB {}
- sub sub {print ++$i, " $sub\n"; &$sub}
- }
-
-It prints the sequence number of each subroutine call and the name of the
-called subroutine. Note that C<&DB::sub> is being compiled into the
-package C<DB> through the use of the C<package> directive.
-
-When it starts, the debugger reads your rc file (F<./.perldb> or
-F<~/.perldb> under Unix), which can set important options.
-(A subroutine (C<&afterinit>) can be defined here as well; it is executed
-after the debugger completes its own initialization.)
-
-After the rc file is read, the debugger reads the PERLDB_OPTS
-environment variable and uses it to set debugger options. The
-contents of this variable are treated as if they were the argument
-of an C<o ...> debugger command (q.v. in L<perldebug/"Configurable Options">).
-
-=head3 Debugger Internal Variables
-
-In addition to the file and subroutine-related variables mentioned above,
-the debugger also maintains various magical internal variables.
-
-=over 4
-
-=item *
-
-C<@DB::dbline> is an alias for C<@{"::_<current_file"}>, which
-holds the lines of the currently-selected file (compiled by Perl), either
-explicitly chosen with the debugger's C<f> command, or implicitly by flow
-of execution.
-
-Values in this array are magical in numeric context: they compare
-equal to zero only if the line is not breakable.
-
-=item *
-
-C<%DB::dbline> is an alias for C<%{"::_<current_file"}>, which
-contains breakpoints and actions keyed by line number in
-the currently-selected file, either explicitly chosen with the
-debugger's C<f> command, or implicitly by flow of execution.
-
-As previously noted, individual entries (as opposed to the whole hash)
-are settable. Perl only cares about Boolean true here, although
-the values used by F<perl5db.pl> have the form
-C<"$break_condition\0$action">.
-
-=back
-
-=head3 Debugger Customization Functions
-
-Some functions are provided to simplify customization.
-
-=over 4
-
-=item *
-
-See L<perldebug/"Configurable Options"> for a description of options parsed by
-C<DB::parse_options(string)>.
-
-=item *
-
-C<DB::dump_trace(skip[,count])> skips the specified number of frames
-and returns a list containing information about the calling frames (all
-of them, if C<count> is missing). Each entry is reference to a hash
-with keys C<context> (either C<.>, C<$>, or C<@>), C<sub> (subroutine
-name, or info about C<eval>), C<args> (C<undef> or a reference to
-an array), C<file>, and C<line>.
-
-=item *
-
-C<DB::print_trace(FH, skip[, count[, short]])> prints
-formatted info about caller frames. The last two functions may be
-convenient as arguments to C<< < >>, C<< << >> commands.
-
-=back
-
-Note that any variables and functions that are not documented in
-this manpages (or in L<perldebug>) are considered for internal
-use only, and as such are subject to change without notice.
-
-=head1 Frame Listing Output Examples
-
-The C<frame> option can be used to control the output of frame
-information. For example, contrast this expression trace:
-
- $ perl -de 42
- Stack dump during die enabled outside of evals.
-
- Loading DB routines from perl5db.pl patch level 0.94
- Emacs support available.
-
- Enter h or 'h h' for help.
-
- main::(-e:1): 0
- DB<1> sub foo { 14 }
-
- DB<2> sub bar { 3 }
-
- DB<3> t print foo() * bar()
- main::((eval 172):3): print foo() + bar();
- main::foo((eval 168):2):
- main::bar((eval 170):2):
- 42
-
-with this one, once the C<o>ption C<frame=2> has been set:
-
- DB<4> o f=2
- frame = '2'
- DB<5> t print foo() * bar()
- 3: foo() * bar()
- entering main::foo
- 2: sub foo { 14 };
- exited main::foo
- entering main::bar
- 2: sub bar { 3 };
- exited main::bar
- 42
-
-By way of demonstration, we present below a laborious listing
-resulting from setting your C<PERLDB_OPTS> environment variable to
-the value C<f=n N>, and running I<perl -d -V> from the command line.
-Examples using various values of C<n> are shown to give you a feel
-for the difference between settings. Long though it may be, this
-is not a complete listing, but only excerpts.
-
-=over 4
-
-=item 1
-
- entering main::BEGIN
- entering Config::BEGIN
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- Package lib/Config.pm.
- entering Config::TIEHASH
- entering Exporter::import
- entering Exporter::export
- entering Config::myconfig
- entering Config::FETCH
- entering Config::FETCH
- entering Config::FETCH
- entering Config::FETCH
-
-=item 2
-
- entering main::BEGIN
- entering Config::BEGIN
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- exited Config::BEGIN
- Package lib/Config.pm.
- entering Config::TIEHASH
- exited Config::TIEHASH
- entering Exporter::import
- entering Exporter::export
- exited Exporter::export
- exited Exporter::import
- exited main::BEGIN
- entering Config::myconfig
- entering Config::FETCH
- exited Config::FETCH
- entering Config::FETCH
- exited Config::FETCH
- entering Config::FETCH
-
-=item 3
-
- in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
-
-=item 4
-
- in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- out $=Config::BEGIN() from lib/Config.pm:0
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- out $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- out $=main::BEGIN() from /dev/null:0
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
-
-=item 5
-
- in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- out $=Config::BEGIN() from lib/Config.pm:0
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- out $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- out $=main::BEGIN() from /dev/null:0
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
- out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
- in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
- out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
-
-=item 6
-
- in $=CODE(0x15eca4)() from /dev/null:0
- in $=CODE(0x182528)() from lib/Config.pm:2
- Package lib/Exporter.pm.
- out $=CODE(0x182528)() from lib/Config.pm:0
- scalar context return from CODE(0x182528): undef
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:628
- out $=Config::TIEHASH('Config') from lib/Config.pm:628
- scalar context return from Config::TIEHASH: empty hash
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
- scalar context return from Exporter::export: ''
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- scalar context return from Exporter::import: ''
-
-=back
-
-In all cases shown above, the line indentation shows the call tree.
-If bit 2 of C<frame> is set, a line is printed on exit from a
-subroutine as well. If bit 4 is set, the arguments are printed
-along with the caller info. If bit 8 is set, the arguments are
-printed even if they are tied or references. If bit 16 is set, the
-return value is printed, too.
-
-When a package is compiled, a line like this
-
- Package lib/Carp.pm.
-
-is printed with proper indentation.
-
-=head1 Debugging Regular Expressions
-
-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.
-
-Otherwise, one can C<use re 'debug'>, which has effects at
-compile time and run time. Since Perl 5.9.5, this pragma is lexically
-scoped.
-
-=head2 Compile-time Output
-
-The debugging output at compile time looks like this:
-
- Compiling REx '[bc]d(ef*g)+h[ij]k$'
- size 45 Got 364 bytes for offset annotations.
- first at 1
- rarest char g at 0
- rarest char d at 0
- 1: ANYOF[bc](12)
- 12: EXACT <d>(14)
- 14: CURLYX[0] {1,32767}(28)
- 16: OPEN1(18)
- 18: EXACT <e>(20)
- 20: STAR(23)
- 21: EXACT <f>(0)
- 23: EXACT <g>(25)
- 25: CLOSE1(27)
- 27: WHILEM[1/1](0)
- 28: NOTHING(29)
- 29: EXACT <h>(31)
- 31: ANYOF[ij](42)
- 42: EXACT <k>(44)
- 44: EOL(45)
- 45: END(0)
- anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
- stclass 'ANYOF[bc]' minlen 7
- Offsets: [45]
- 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
- 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
- 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
- 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
- Omitting $` $& $' support.
-
-The first line shows the pre-compiled form of the regex. The second
-shows the size of the compiled form (in arbitrary units, usually
-4-byte words) and the total number of bytes allocated for the
-offset/length table, usually 4+C<size>*8. The next line shows the
-label I<id> of the first node that does a match.
-
-The
-
- anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
- stclass 'ANYOF[bc]' minlen 7
-
-line (split into two lines above) contains optimizer
-information. In the example shown, the optimizer found that the match
-should contain a substring C<de> at offset 1, plus substring C<gh>
-at some offset between 3 and infinity. Moreover, when checking for
-these substrings (to abandon impossible matches quickly), Perl will check
-for the substring C<gh> before checking for the substring C<de>. The
-optimizer may also use the knowledge that the match starts (at the
-C<first> I<id>) with a character class, and no string
-shorter than 7 characters can possibly match.
-
-The fields of interest which may appear in this line are
-
-=over 4
-
-=item C<anchored> I<STRING> C<at> I<POS>
-
-=item C<floating> I<STRING> C<at> I<POS1..POS2>
-
-See above.
-
-=item C<matching floating/anchored>
-
-Which substring to check first.
-
-=item C<minlen>
-
-The minimal length of the match.
-
-=item C<stclass> I<TYPE>
-
-Type of first matching node.
-
-=item C<noscan>
-
-Don't scan for the found substrings.
-
-=item C<isall>
-
-Means that the optimizer information is all that the regular
-expression contains, and thus one does not need to enter the regex engine at
-all.
-
-=item C<GPOS>
-
-Set if the pattern contains C<\G>.
-
-=item C<plus>
-
-Set if the pattern starts with a repeated char (as in C<x+y>).
-
-=item C<implicit>
-
-Set if the pattern starts with C<.*>.
-
-=item C<with eval>
-
-Set if the pattern contain eval-groups, such as C<(?{ code })> and
-C<(??{ code })>.
-
-=item C<anchored(TYPE)>
-
-If the pattern may match only at a handful of places, with C<TYPE>
-being C<BOL>, C<MBOL>, or C<GPOS>. See the table below.
-
-=back
-
-If a substring is known to match at end-of-line only, it may be
-followed by C<$>, as in C<floating 'k'$>.
-
-The optimizer-specific information is used to avoid entering (a slow) regex
-engine on strings that will not definitely match. If the C<isall> flag
-is set, a call to the regex engine may be avoided even when the optimizer
-found an appropriate place for the match.
-
-Above the optimizer section is the list of I<nodes> of the compiled
-form of the regex. Each line has format
-
-C< >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>)
-
-=head2 Types of Nodes
-
-Here are the possible types, with short descriptions:
-
- # TYPE arg-description [num-args] [longjump-len] DESCRIPTION
-
- # Exit points
- END no End of program.
- SUCCEED no Return from a subroutine, basically.
-
- # Anchors:
-
- BOL no Match "" at beginning of line.
- MBOL no Same, assuming multiline.
- SBOL no Same, assuming singleline.
- EOS no Match "" at end of string.
- EOL no Match "" at end of line.
- MEOL no Same, assuming multiline.
- SEOL no Same, assuming singleline.
- BOUND no Match "" at any word boundary using native charset
- semantics for non-utf8
- BOUNDL no Match "" at any locale word boundary
- BOUNDU no Match "" at any word boundary using Unicode semantics
- BOUNDA no Match "" at any word boundary using ASCII semantics
- NBOUND no Match "" at any word non-boundary using native charset
- semantics for non-utf8
- NBOUNDL no Match "" at any locale word non-boundary
- NBOUNDU no Match "" at any word non-boundary using Unicode semantics
- NBOUNDA no Match "" at any word non-boundary using ASCII semantics
- GPOS no Matches where last m//g left off.
-
- # [Special] alternatives:
-
- REG_ANY no Match any one character (except newline).
- SANY no Match any one character.
- CANY no Match any one byte.
- ANYOF sv Match character in (or not in) this class, single char
- match only
- ANYOFV sv Match character in (or not in) this class, can
- match-multiple chars
- ALNUM no Match any alphanumeric character using native charset
- semantics for non-utf8
- ALNUML no Match any alphanumeric char in locale
- ALNUMU no Match any alphanumeric char using Unicode semantics
- ALNUMA no Match [A-Za-z_0-9]
- NALNUM no Match any non-alphanumeric character using native charset
- semantics for non-utf8
- NALNUML no Match any non-alphanumeric char in locale
- NALNUMU no Match any non-alphanumeric char using Unicode semantics
- NALNUMA no Match [^A-Za-z_0-9]
- SPACE no Match any whitespace character using native charset
- semantics for non-utf8
- SPACEL no Match any whitespace char in locale
- SPACEU no Match any whitespace char using Unicode semantics
- SPACEA no Match [ \t\n\f\r]
- NSPACE no Match any non-whitespace character using native charset
- semantics for non-utf8
- NSPACEL no Match any non-whitespace char in locale
- NSPACEU no Match any non-whitespace char using Unicode semantics
- NSPACEA no Match [^ \t\n\f\r]
- DIGIT no Match any numeric character using native charset semantics
- for non-utf8
- DIGITL no Match any numeric character in locale
- DIGITA no Match [0-9]
- NDIGIT no Match any non-numeric character using native charset
- i semantics for non-utf8
- NDIGITL no Match any non-numeric character in locale
- NDIGITA no Match [^0-9]
- CLUMP no Match any extended grapheme cluster sequence
-
- # Alternation
-
- # BRANCH The set of branches constituting a single choice are hooked
- # together with their "next" pointers, since precedence prevents
- # anything being concatenated to any individual branch. The
- # "next" pointer of the last BRANCH in a choice points to the
- # thing following the whole choice. This is also where the
- # final "next" 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...
-
- # Back pointer
-
- # BACK Normal "next" pointers all implicitly point forward; BACK
- # exists to make loop structures possible.
- # not used
- BACK no Match "", "next" ptr points backward.
-
- # Literals
-
- EXACT str Match this string (preceded by length).
- EXACTF str Match this string, folded, native charset semantics for
- non-utf8 (prec. by length).
- EXACTFL str Match this string, folded in locale (w/len).
- EXACTFU str Match this string, folded, Unicode semantics for non-utf8
- (prec. by length).
- EXACTFA str Match this string, folded, Unicode semantics for non-utf8,
- but no ASCII-range character matches outside ASCII (prec.
- by length),.
-
- # Do nothing types
-
- 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.
-
- # Loops
-
- # STAR,PLUS '?', and complex '*' and '+', are implemented as circular
- # BRANCH structures using BACK. Simple cases (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.
-
- 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.
-
- # 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
- semantics for non-utf8
- REFFL num 1 Match already matched string, folded in loc.
- REFFU num 1 Match already matched string, folded using unicode
- semantics for non-utf8
- REFFA num 1 Match already matched string, folded using unicode
- semantics for non-utf8, no mixing ASCII, non-ASCII
-
- # 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
- semantics for non-utf8
- NREFFL no-sv 1 Match already matched string, folded in loc.
- NREFFU num 1 Match already matched string, folded using unicode
- semantics for non-utf8
- NREFFA num 1 Match already matched string, folded using unicode
- semantics for non-utf8, no mixing ASCII, non-ASCII
-
- 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.
-
- # Support for long RE
-
- LONGJMP off 1 1 Jump far away.
- BRANCHJ off 1 1 BRANCH with long offset.
-
- # The heavy worker
-
- EVAL evl 1 Execute some Perl code.
-
- # Modifiers
-
- 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.
- # NOTE: the relative order of the TRIE-like regops is significant
-
- TRIE trie 1 Match many EXACT(F[ALU]?)? at once. flags==type
- TRIEC charclass Same as TRIE, but with embedded charclass data
-
- # For start classes, contains an added fail table.
- AHOCORASICK trie 1 Aho Corasick stclass. flags==type
- AHOCORASICKC charclass Same as AHOCORASICK, but with embedded charclass data
-
- # Regex Subroutines
- GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs arg2
- GOSTART no recurse to start of pattern
-
- # 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.
-
- # Backtracking Verbs
- ENDLIKE none Used only for the type field of verbs
- OPFAIL none Same as (?!)
- ACCEPT parno 1 Accepts the current matched string.
-
-
- # 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
-
- # Control what to keep in $&.
- KEEPS no $& begins here.
-
- # New charclass like patterns
- LNBREAK none generic newline pattern
- VERTWS none vertical whitespace (Perl 6)
- NVERTWS none not vertical whitespace (Perl 6)
- HORIZWS none horizontal whitespace (Perl 6)
- NHORIZWS none not horizontal whitespace (Perl 6)
-
- FOLDCHAR codepoint 1 codepoint with tricky case folding properties.
-
- # 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.
-
- # 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.
-
-=for unprinted-credits
-Next section M-J. Dominus (mjd-perl-patch+@plover.com) 20010421
-
-Following the optimizer information is a dump of the offset/length
-table, here split across several lines:
-
- Offsets: [45]
- 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
- 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
- 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
- 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
-
-The first line here indicates that the offset/length table contains 45
-entries. Each entry is a pair of integers, denoted by C<offset[length]>.
-Entries are numbered starting with 1, so entry #1 here is C<1[4]> and
-entry #12 is C<5[1]>. C<1[4]> indicates that the node labeled C<1:>
-(the C<1: ANYOF[bc]>) begins at character position 1 in the
-pre-compiled form of the regex, and has a length of 4 characters.
-C<5[1]> in position 12
-indicates that the node labeled C<12:>
-(the C<< 12: EXACT <d> >>) begins at character position 5 in the
-pre-compiled form of the regex, and has a length of 1 character.
-C<12[1]> in position 14
-indicates that the node labeled C<14:>
-(the C<< 14: CURLYX[0] {1,32767} >>) begins at character position 12 in the
-pre-compiled form of the regex, and has a length of 1 character---that
-is, it corresponds to the C<+> symbol in the precompiled regex.
-
-C<0[0]> items indicate that there is no corresponding node.
-
-=head2 Run-time Output
-
-First of all, when doing a match, one may get no run-time output even
-if debugging is enabled. This means that the regex engine was never
-entered and that all of the job was therefore done by the optimizer.
-
-If the regex engine was entered, the output may look like this:
-
- Matching '[bc]d(ef*g)+h[ij]k$' against 'abcdefg__gh__'
- Setting an EVAL scope, savestack=3
- 2 <ab> <cdefg__gh_> | 1: ANYOF
- 3 <abc> <defg__gh_> | 11: EXACT <d>
- 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767}
- 4 <abcd> <efg__gh_> | 26: WHILEM
- 0 out of 1..32767 cc=effff31c
- 4 <abcd> <efg__gh_> | 15: OPEN1
- 4 <abcd> <efg__gh_> | 17: EXACT <e>
- 5 <abcde> <fg__gh_> | 19: STAR
- EXACT <f> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 6 <bcdef> <g__gh__> | 22: EXACT <g>
- 7 <bcdefg> <__gh__> | 24: CLOSE1
- 7 <bcdefg> <__gh__> | 26: WHILEM
- 1 out of 1..32767 cc=effff31c
- Setting an EVAL scope, savestack=12
- 7 <bcdefg> <__gh__> | 15: OPEN1
- 7 <bcdefg> <__gh__> | 17: EXACT <e>
- restoring \1 to 4(4)..7
- failed, try continuation...
- 7 <bcdefg> <__gh__> | 27: NOTHING
- 7 <bcdefg> <__gh__> | 28: EXACT <h>
- failed...
- failed...
-
-The most significant information in the output is about the particular I<node>
-of the compiled regex that is currently being tested against the target string.
-The format of these lines is
-
-C< >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>> |I<ID>: I<TYPE>
-
-The I<TYPE> info is indented with respect to the backtracking level.
-Other incidental information appears interspersed within.
-
-=head1 Debugging Perl Memory Usage
-
-Perl is a profligate wastrel when it comes to memory use. There
-is a saying that to estimate memory usage of Perl, assume a reasonable
-algorithm for memory allocation, multiply that estimate by 10, and
-while you still may miss the mark, at least you won't be quite so
-astonished. This is not absolutely true, but may provide a good
-grasp of what happens.
-
-Assume that an integer cannot take less than 20 bytes of memory, a
-float cannot take less than 24 bytes, a string cannot take less
-than 32 bytes (all these examples assume 32-bit architectures, the
-result are quite a bit worse on 64-bit architectures). If a variable
-is accessed in two of three different ways (which require an integer,
-a float, or a string), the memory footprint may increase yet another
-20 bytes. A sloppy malloc(3) implementation can inflate these
-numbers dramatically.
-
-On the opposite end of the scale, a declaration like
-
- sub foo;
-
-may take up to 500 bytes of memory, depending on which release of Perl
-you're running.
-
-Anecdotal estimates of source-to-compiled code bloat suggest an
-eightfold increase. This means that the compiled form of reasonable
-(normally commented, properly indented etc.) code will take
-about eight times more space in memory than the code took
-on disk.
-
-The B<-DL> command-line switch is obsolete since circa Perl 5.6.0
-(it was available only if Perl was built with C<-DDEBUGGING>).
-The switch was used to track Perl's memory allocations and possible
-memory leaks. These days the use of malloc debugging tools like
-F<Purify> or F<valgrind> is suggested instead. See also
-L<perlhacktips/PERL_MEM_LOG>.
-
-One way to find out how much memory is being used by Perl data
-structures is to install the Devel::Size module from CPAN: it gives
-you the minimum number of bytes required to store a particular data
-structure. Please be mindful of the difference between the size()
-and total_size().
-
-If Perl has been compiled using Perl's malloc you can analyze Perl
-memory usage by setting $ENV{PERL_DEBUG_MSTATS}.
-
-=head2 Using C<$ENV{PERL_DEBUG_MSTATS}>
-
-If your perl is using Perl's malloc() and was compiled with the
-necessary switches (this is the default), then it will print memory
-usage statistics after compiling your code when C<< $ENV{PERL_DEBUG_MSTATS}
-> 1 >>, and before termination of the program when C<<
-$ENV{PERL_DEBUG_MSTATS} >= 1 >>. The report format is similar to
-the following example:
-
- $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
- Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
- 14216 free: 130 117 28 7 9 0 2 2 1 0 0
- 437 61 36 0 5
- 60924 used: 125 137 161 55 7 8 6 16 2 0 1
- 74 109 304 84 20
- Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
- Memory allocation statistics after execution: (buckets 4(4)..8188(8192)
- 30888 free: 245 78 85 13 6 2 1 3 2 0 1
- 315 162 39 42 11
- 175816 used: 265 176 1112 111 26 22 11 27 2 1 1
- 196 178 1066 798 39
- Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
-
-It is possible to ask for such a statistic at arbitrary points in
-your execution using the mstat() function out of the standard
-Devel::Peek module.
-
-Here is some explanation of that format:
-
-=over 4
-
-=item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>
-
-Perl's malloc() uses bucketed allocations. Every request is rounded
-up to the closest bucket size available, and a bucket is taken from
-the pool of buckets of that size.
-
-The line above describes the limits of buckets currently in use.
-Each bucket has two sizes: memory footprint and the maximal size
-of user data that can fit into this bucket. Suppose in the above
-example that the smallest bucket were size 4. The biggest bucket
-would have usable size 8188, and the memory footprint would be 8192.
-
-In a Perl built for debugging, some buckets may have negative usable
-size. This means that these buckets cannot (and will not) be used.
-For larger buckets, the memory footprint may be one page greater
-than a power of 2. If so, the corresponding power of two is
-printed in the C<APPROX> field above.
-
-=item Free/Used
-
-The 1 or 2 rows of numbers following that correspond to the number
-of buckets of each size between C<SMALLEST> and C<GREATEST>. In
-the first row, the sizes (memory footprints) of buckets are powers
-of two--or possibly one page greater. In the second row, if present,
-the memory footprints of the buckets are between the memory footprints
-of two buckets "above".
-
-For example, suppose under the previous example, the memory footprints
-were
-
- free: 8 16 32 64 128 256 512 1024 2048 4096 8192
- 4 12 24 48 80
-
-With a non-C<DEBUGGING> perl, the buckets starting from C<128> have
-a 4-byte overhead, and thus an 8192-long bucket may take up to
-8188-byte allocations.
-
-=item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS>
-
-The first two fields give the total amount of memory perl sbrk(2)ed
-(ess-broken? :-) and number of sbrk(2)s used. The third number is
-what perl thinks about continuity of returned chunks. So long as
-this number is positive, malloc() will assume that it is probable
-that sbrk(2) will provide continuous memory.
-
-Memory allocated by external libraries is not counted.
-
-=item C<pad: 0>
-
-The amount of sbrk(2)ed memory needed to keep buckets aligned.
-
-=item C<heads: 2192>
-
-Although memory overhead of bigger buckets is kept inside the bucket, for
-smaller buckets, it is kept in separate areas. This field gives the
-total size of these areas.
-
-=item C<chain: 0>
-
-malloc() may want to subdivide a bigger bucket into smaller buckets.
-If only a part of the deceased bucket is left unsubdivided, the rest
-is kept as an element of a linked list. This field gives the total
-size of these chunks.
-
-=item C<tail: 6144>
-
-To minimize the number of sbrk(2)s, malloc() asks for more memory. This
-field gives the size of the yet unused part, which is sbrk(2)ed, but
-never touched.
-
-=back
-
-=head1 SEE ALSO
-
-L<perldebug>,
-L<perlguts>,
-L<perlrun>
-L<re>,
-and
-L<Devel::DProf>.