for the assignment form C<*=> of multiplication.
Arguments of this directive come in (key, value) pairs. Legal values
-are values legal inside a C<&{ ... }> call, so the name of a subroutine,
-a reference to a subroutine, or an anonymous subroutine will all work.
-Legal keys are listed below.
+are values legal inside a C<&{ ... }> call, so the name of a
+subroutine, a reference to a subroutine, or an anonymous subroutine
+will all work. Note that values specified as strings are
+interpreted as methods, not subroutines. Legal keys are listed below.
The subroutine C<add> will be called to execute C<$a+$b> if $a
is a reference to an object blessed into the package C<Number>, or if $a is
methods refer to methods triggered by an overloaded mathematical
operator.)
+Since overloading respects @ISA hierarchy, in fact the above
+declaration would also trigger overloading of C<+> and C<*=> in all
+the packages which inherit from C<Number>.
+
=head2 Calling Conventions for Binary Operations
The functions specified in the C<use overload ...> directive are called
See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
+=head2 Inheritance and overloading
+
+There are two ways how inheritance interacts with overloading.
+
+=over
+
+=item Strings as values of C<use overload> directive
+
+If the value of
+
+ use overload key => value;
+
+directive is a string, it is interpreted as a method name.
+
+=item Overloading of an operation is inherited by derived classes
+
+If any of ancestors is overloaded, so is the derived class. The set of
+overloaded methods is the union of overloaded methods of all the
+ancestors. If some method is overloaded in several ancestor, then
+which description will be used is decided by the usual inheritance
+rules:
+
+If C<A> inherits from C<B> and C<C> (in this order), and C<B>
+overloads C<+> by C<\&D::plus_sub>, C<C> overloads C<+> by
+C<"plus_meth">, then the subroutine C<D::plus_sub> will be called to
+implement operation C<+> for an object in package C<A>.
+
+=back
+
+Note that since the value of C<fallback> key is not a subroutine, its
+inheritance is not governed by the above rules. Current implementation
+is that the value of C<fallback> in the first overloaded ancestor is
+taken, but this may be subject to change.
+
=head1 SPECIAL SYMBOLS FOR C<use overload>
Three keys are recognized by Perl that are not covered by the above
=back
+B<Note.> C<"fallback"> inheritance via @ISA is not carved in stone
+yet, see L<"Inheritance and overloading">.
+
=head2 Copy Constructor
The value for C<"="> is a reference to a function with three
What follows is subject to change RSN.
-The table of methods for all operations is cached as magic in the
-symbol table hash for the package. The table is rechecked for changes due to
-C<use overload>, C<no overload>, and @ISA only during
-C<bless>ing; so if they are changed dynamically, you'll need an
-additional fake C<bless>ing to update the table.
-
-(Every SVish thing has a magic queue, and magic is an entry in that queue.
-This is how a single variable may participate in multiple forms of magic
-simultaneously. For instance, environment variables regularly have two
-forms at once: their %ENV magic and their taint magic.)
+The table of methods for all operations is cached in magic for the
+symbol table hash for the package. The cache is invalidated during
+processing of C<use overload>, C<no overload>, new function
+definitions, and changes in @ISA. However, this invalidation remains
+unprocessed until the next C<bless>ing into the package. Hence if you
+want to change overloading structure dynamically, you'll need an
+additional (fake) C<bless>ing to update the table.
+
+(Every SVish thing has a magic queue, and magic is an entry in that
+queue. This is how a single variable may participate in multiple
+forms of magic simultaneously. For instance, environment variables
+regularly have two forms at once: their %ENV magic and their taint
+magic. However, the magic which implements overloading is applied to
+the stashes, which are rarely used directly, thus should not slow down
+Perl.)
If an object belongs to a package using overload, it carries a special
flag. Thus the only speed penalty during arithmetic operations without
In fact, if C<use overload> is not present, there is almost no overhead for
overloadable operations, so most programs should not suffer measurable
performance penalties. A considerable effort was made to minimize the overhead
-when overload is used and the current operation is overloadable but
+when overload is used in some package, but
the arguments in question do not belong to packages using overload. When
in doubt, test your speed with C<use overload> and without it. So far there
have been no reports of substantial speed degradation if Perl is compiled
with optimization turned on.
-There is no size penalty for data if overload is not used.
+There is no size penalty for data if overload is not used. The only
+size penalty if overload is used in some package is that I<all> the
+packages acquire a magic during the next C<bless>ing into the
+package. This magic is three-words-long for packages without
+overloading, and carries the cache tabel if the package is overloaded.
Copying (C<$a=$b>) is shallow; however, a one-level-deep copying is
carried out before any operation that can imply an assignment to the
When Perl is run with the B<-Do> switch or its equivalent, overloading
induces diagnostic messages.
+Using the C<m> command of Perl debugger (see L<perldebug>) one can
+deduce which operations are overloaded (and which ancestor triggers
+this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
+is shown by debugger. The method C<()> corresponds to the C<fallback>
+key (in fact a presence of this method shows that this package has
+overloading enabled, and it is what is used by the C<Overloaded>
+function).
+
=head1 BUGS
Because it is used for overloading, the per-package associative array
DB> |h
+You may change the pager which is used via C<O pager=...> command.
+
=item p expr
Same as C<print {$DB::OUT} expr> in the current package. In particular,
because this is just Perl's own B<print> function, this means that nested
data structures and objects are not dumped, unlike with the C<x> command.
+The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
+where STDOUT may be redirected to.
+
=item x expr
Evaluates its expression in list context and dumps out the result
statement, descending into subroutine calls. If an expression is
supplied that includes function calls, it too will be single-stepped.
-=item n
+=item n [expr]
Next. Executes over subroutine calls, until it reaches the beginning
-of the next statement.
+of the next statement. If an expression is
+supplied that includes function calls, it too will be executed with
+stops before each statement.
=item E<lt>CRE<gt>
=item l min-max
-List lines C<min> through C<max>.
+List lines C<min> through C<max>. C<l -> is synonymous to C<->.
=item l line
=item f filename
-Switch to viewing a different file.
+Switch to viewing a different file or eval statement. If C<filename>
+is not a full filename as found in values of %INC, it is considered as
+a regexp.
=item /pattern/
=item b load filename
-Set breakpoint at the first executed line of the file.
+Set breakpoint at the first executed line of the file. Filename should
+be a full name as found in values of %INC.
+
+=item b compile subname
+
+Sets breakpoint at the first statement executed after the subroutine
+is compiled.
=item d [line]
=over 12
-=item recallCommand, ShellBang
+=item C<recallCommand>, C<ShellBang>
The characters used to recall command or spawn shell. By
default, these are both set to C<!>.
-=item pager
+=item C<pager>
Program to use for output of pager-piped commands (those
beginning with a C<|> character.) By default,
C<$ENV{PAGER}> will be used.
-=item tkRunning
+=item C<tkRunning>
Run Tk while prompting (with ReadLine).
-=item signalLevel, warnLevel, dieLevel
+=item C<signalLevel>, C<warnLevel>, C<dieLevel>
+
+Level of verbosity. By default the debugger is in a sane verbose mode,
+thus it will print backtraces on all the warnings and die-messages
+which are going to be printed out, and will print a message when
+interesting uncaught signals arrive.
-Level of verbosity.
+To disable this behaviour, set these values to 0. If C<dieLevel> is 2,
+then the messages which will be caught by surrounding C<eval> are also
+printed.
-=item AutoTrace
+=item C<AutoTrace>
-Where to print all the breakable points in the executed program
-(similar to C<t> command, but can be put into C<PERLDB_OPTS>).
+Trace mode (similar to C<t> command, but can be put into
+C<PERLDB_OPTS>).
-=item LineInfo
+=item C<LineInfo>
-File or pipe to print line number info to. If it is a
-pipe, then a short, "emacs like" message is used.
+File or pipe to print line number info to. If it is a pipe (say,
+C<|visual_perl_db>), then a short, "emacs like" message is used.
=item C<inhibit_exit>
on exit may be useful if inter(di)spersed with other messages.)
If C<frame & 4>, arguments to functions are printed as well as the
-context and caller info.
+context and caller info. If C<frame & 8>, overloaded C<stringify> and
+C<tie>d C<FETCH> are enabled on the printed arguments. The length at
+which the argument list is truncated is governed by the next option:
+
+=item C<maxTraceLen>
+
+length at which the argument list is truncated when C<frame> option's
+bit 4 is set.
=back
=over 12
-=item arrayDepth, hashDepth
+=item C<arrayDepth>, C<hashDepth>
Print only first N elements ('' for all).
-=item compactDump, veryCompact
+=item C<compactDump>, C<veryCompact>
-Change style of array and hash dump.
+Change style of array and hash dump. If C<compactDump>, short array
+may be printed on one line.
-=item globPrint
+=item C<globPrint>
Whether to print contents of globs.
-=item DumpDBFiles
+=item C<DumpDBFiles>
Dump arrays holding debugged files.
-=item DumpPackages
+=item C<DumpPackages>
Dump symbol tables of packages.
-=item quote, HighBit, undefPrint
+=item C<quote>, C<HighBit>, C<undefPrint>
+
+Change style of string dump. Default value of C<quote> is C<auto>, one
+can enable either double-quotish dump, or single-quotish by setting it
+to C<"> or C<'>. By default, characters with high bit set are printed
+I<as is>.
+
+=item C<UsageOnly>
-Change style of string dump.
+I<very> rudimentally per-package memory usage dump. Calculates total
+size of strings in variables in the package.
=back
Example rc file:
- &parse_options("NonStop=1 LineInfo=db.out AutoTrace");
+ &parse_options("NonStop=1 LineInfo=db.out AutoTrace");
The script will run without human intervention, putting trace information
into the file I<db.out>. (If you interrupt it, you would better reset
The TTY to use for debugging I/O.
-=item noTTY
-
-If set, goes in C<NonStop> mode. On interrupt if TTY is not set uses the
-value of C<noTTY> or "/tmp/perldbtty$$" to find TTY using
-C<Term::Rendezvous>. Current variant is to have the name of TTY in this
-file.
-
=item C<noTTY>
If set, goes in C<NonStop> mode, and would not connect to a TTY. If
Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
- $ PERLDB_OPTS="N f=2" perl -d myprogram
+ $ PERLDB_OPTS="N f=2" perl -d myprogram
will run the script C<myprogram> without human intervention, printing
out the call tree with entry and exit points. Note that C<N f=2> is
Other examples may include
- $ PERLDB_OPTS="N f A L=listing" perl -d myprogram
+ $ PERLDB_OPTS="N f A L=listing" perl -d myprogram
- runs script non-interactively, printing info on each entry into a
subroutine and each executed line into the file F<listing>. (If you
"interactive"!)
- $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram
+ $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram
may be useful for debugging a program which uses C<Term::ReadLine>
itself. Do not forget detach shell from the TTY in the window which
corresponds to F</dev/ttyc>, say, by issuing a command like
- $ sleep 1000000
+ $ sleep 1000000
See L<"Debugger Internals"> below for more details.
=item = [alias value]
-Define a command alias, or list current aliases.
+Define a command alias, like
+
+ = quit q
+
+or list current aliases.
=item command
Execute command as a Perl statement. A missing semicolon will be
supplied.
-=item p expr
+=item m expr
-Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to
-/dev/tty, regardless of where STDOUT may be redirected to.
+The expression is evaluated, and the methods which may be applied to
+the result are listed.
+
+=item m package
+
+The methods which may be applied to objects in the C<package> are listed.
=back
+=head2 Debugger input/output
+
+=over 8
+
+=item Prompt
+
The debugger prompt is something like
DB<8>
function call that itself also has a breakpoint, or you step into an
expression via C<s/n/t expression> command.
+=item Multi-line commands
+
If you want to enter a multi-line command, such as a subroutine
-definition with several statements, you may escape the newline that would
-normally end the debugger command with a backslash. Here's an example:
+definition with several statements, or a format, you may escape the
+newline that would normally end the debugger command with a backslash.
+Here's an example:
DB<1> for (1..4) { \
cont: print "ok\n"; \
Note that this business of escaping a newline is specific to interactive
commands typed into the debugger.
-Here's an example of what a stack back-trace might look like:
+=item Stack backtrace
+
+Here's an example of what a stack back-trace via C<T> command might
+look like:
$ = main::infested called from file `Ambulation.pm' line 10
@ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
C<main::pests> was called in a scalar context, also from I<camel_flea>,
but from line 4.
+Note that if you execute C<T> command from inside an active C<use>
+statement, the backtrace will contain both C<L<perlfunc/require>>
+frame and an C<L<perlfunc/eval EXPR>>) frame.
+
+=item Listing
+
+Listing given via different flavors of C<l> command looks like this:
+
+ DB<<13>> l
+ 101: @i{@i} = ();
+ 102:b @isa{@i,$pack} = ()
+ 103 if(exists $i{$prevpack} || exists $isa{$pack});
+ 104 }
+ 105
+ 106 next
+ 107==> if(exists $isa{$pack});
+ 108
+ 109:a if ($extra-- > 0) {
+ 110: %isa = ($pack,1);
+
+Note that the breakable lines are marked with C<:>, lines with
+breakpoints are marked by C<b>, with actions by C<a>, and the
+next executed line is marked by C<==E<gt>>.
+
+=item Frame listing
+
+When C<frame> option is set, debugger would print entered (and
+optionally exited) subroutines in different styles.
+
+What follows is the start of the listing of
+
+ env "PERLDB_OPTS=f=1 N" perl -d -V
+
+=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 4
+
+ in $=main::BEGIN() from /dev/nul: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/nul:0
+ in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
+ in @=Config::myconfig() from /dev/nul: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), 'PATCHLEVEL') from lib/Config.pm:574
+ in $=Config::FETCH(ref(Config), '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 6
+
+ in $=main::BEGIN() from /dev/nul: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/nul: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/nul:0
+ out $=main::BEGIN() from /dev/nul:0
+ in @=Config::myconfig() from /dev/nul: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), 'PATCHLEVEL') from lib/Config.pm:574
+ out $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
+ in $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574
+
+=item 14
+
+ in $=main::BEGIN() from /dev/nul: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/nul: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/nul:0
+ out $=main::BEGIN() from /dev/nul:0
+ in @=Config::myconfig() from /dev/nul: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
+
+=back
+
+In all the cases indentation of lines shows the call tree, if bit 2 of
+C<frame> is set, then a line is printed on exit from a subroutine as
+well, if bit 4 is set, then the arguments are printed as well as the
+caller info, if bit 8 is set, the arguments are printed even if they
+are tied or references.
+
+When a package is compiled, a line like this
+
+ Package lib/Carp.pm.
+
+is printed with proper indentation.
+
+=back
+
+=head2 Debugging compile-time statements
+
If you have any compile-time executable statements (code within a BEGIN
block or a C<use> statement), these will C<NOT> be stopped by debugger,
although C<require>s will (and compile-time statements can be traced
command. The C<$DB::trace> variable should be set to 1 to simulate
having typed the C<t> command.
+Another way to debug compile-time code is to start debugger, set a
+breakpoint on I<load> of some module thusly
+
+ DB<7> b load f:/perllib/lib/Carp.pm
+ Will stop on load of `f:/perllib/lib/Carp.pm'.
+
+and restart debugger by C<R> command (if possible). One can use C<b
+compile subname> for the same purpose.
+
=head2 Debugger Customization
Most probably you not want to modify the debugger, it contains enough
have full editing capabilities much like GNU I<readline>(3) provides.
Look for these in the F<modules/by-module/Term> directory on CPAN.
+A rudimentary command-line completion is also available.
+Unfortunately, the names of lexical variables are not available for
+completion.
+
=head2 Editor Support for Debugging
If you have GNU B<emacs> installed on your system, it can interact with
=head2 Debugger support in perl
-When you call the B<caller> function from package DB, Perl sets the
-C<@DB::args> array to contain the arguments that stack frame was called
-with.
+When you call the B<caller> function (see L<perlfunc/caller>) from the
+package DB, Perl sets the array @DB::args to contain the arguments the
+corresponding stack frame was called with.
If perl is run with B<-d> option, the following additional features
are enabled:
variables $DB::trace, $DB::single, or $DB::signal is true. (Note that
these variables are not C<local>izable.) This feature is disabled when
the control is inside C<DB::DB()> or functions called from it (unless
-C<$^D & 1 E<lt>E<lt> 30>).
+C<$^D & (1E<lt>E<lt>30)>).
=item *
=back
Note that no subroutine call is possible until C<&DB::sub> is defined
-(for subroutines outside of package C<DB>). (In fact, for the
-standard debugger the same is true if C<$DB::deep> (how many levels of
-recursion deep into the debugger you can go before a mandatory break)
-is not defined.)
+(for subroutines outside of package C<DB>). (This restriction is
+recently lifted.)
+
+(In fact, for the standard debugger the same is true if C<$DB::deep>
+(how many levels of recursion deep into the debugger you can go before
+a mandatory break) is not defined.)
+
+With the recent updates the minimal possible debugger consists of one
+line
+
+ sub DB::DB {}
+
+which is quite handy as contents of C<PERL5DB> environment
+variable:
+
+ env "PERL5DB=sub DB::DB {}" perl -d your-script
+
+Another (a little bit more useful) minimal debugger can be created
+with the only line being
+
+ sub DB::DB {print ++$i; scalar <STDIN>}
+
+This debugger would print the sequential number of encountered
+statement, and would wait for your C<CR> to continue.
+
+The following debugger is quite functional:
+
+ {
+ package DB;
+ sub DB {}
+ sub sub {print ++$i, " $sub\n"; &$sub}
+ }
+
+It prints the sequential number of subroutine call and the name of the
+called subroutine. Note that C<&DB::sub> should be compiled into the
+package C<DB>.
=head2 Debugger Internals
projects / p5sagit/p5-mst-13.2.git / commitdiff