patch for LWP 5.05 to make it play with both 5.003 and 5.003_20 + overload patch
authorIlya Zakharevich <ilya@math.ohio-state.edu>
Mon, 20 Jan 1997 22:26:32 +0000 (10:26 +1200)
committerChip Salzenberg <chip@atlantic.net>
Sat, 25 Jan 1997 03:58:00 +0000 (15:58 +1200)
gv.c
lib/diagnostics.pm
lib/overload.pm
pod/perldebug.pod
pod/perldiag.pod
pod/perlfunc.pod
pod/perlop.pod
pod/perlre.pod
pod/perlxs.pod

diff --git a/gv.c b/gv.c
index 89533ff..3b09463 100644 (file)
--- a/gv.c
+++ b/gv.c
@@ -912,8 +912,8 @@ HV* stash;
   AMT *amtp=mg ? (AMT*)mg->mg_ptr: NULL;
   AMT amt;
 
-  if (mg && (amtp=((AMT*)(mg->mg_ptr)))->was_ok_am == amagic_generation &&
-             amtp->was_ok_sub == sub_generation)
+  if (mg && amtp->was_ok_am == amagic_generation
+      && amtp->was_ok_sub == sub_generation)
       return AMT_AMAGIC(amtp);
   if (amtp && AMT_AMAGIC(amtp)) {      /* Have table. */
     int i;
@@ -997,10 +997,10 @@ HV* stash;
 
     if ( cp = (char *)AMG_names[0] ) {
        /* Try to find via inheritance. */
-       gv = gv_fetchmeth(stash, "()", 2, 0); /* A cooky: "()". */
+       gv = gv_fetchmeth(stash, "()", 2, -1); /* A cooky: "()". */
        if (gv) sv = GvSV(gv);
 
-       if (!sv) /* Empty */;
+       if (!gv) goto notable;
        else if (SvTRUE(sv)) amt.fallback=AMGfallYES;
        else if (SvOK(sv)) amt.fallback=AMGfallNEVER;
     }
@@ -1057,6 +1057,7 @@ HV* stash;
     }
   }
   /* Here we have no table: */
+ notable:
   AMT_AMAGIC_off(&amt);
   sv_magic((SV*)stash, 0, 'c', (char*)&amt, sizeof(AMTS));
   return FALSE;
@@ -1222,8 +1223,9 @@ int flags;
        notfound = 1; lr = 1;
       } else {
         if (off==-1) off=method;
-       sprintf(buf, "Operation `%s': no method found,\n\tleft argument %s%.256s,\n\tright argument %s%.256s",
+       sprintf(buf, "Operation `%s': no method found,%sargument %s%.256s%s%.256s",
                      AMG_names[method + assignshift],
+                     (flags & AMGf_unary ? " " : "\n\tleft "),
                      SvAMAGIC(left)? 
                        "in overloaded package ":
                        "has no overloaded magic",
@@ -1231,8 +1233,10 @@ int flags;
                        HvNAME(SvSTASH(SvRV(left))):
                        "",
                      SvAMAGIC(right)? 
-                       "in overloaded package ":
-                       "has no overloaded magic",
+                       ",\n\tright argument in overloaded package ":
+                       (flags & AMGf_unary 
+                        ? ""
+                        : ",\n\tright argument has no overloaded magic"),
                      SvAMAGIC(right)? 
                        HvNAME(SvSTASH(SvRV(right))):
                        "");
index b00349f..05d1178 100644 (file)
@@ -326,8 +326,9 @@ EOFUNC
                #$lhs =~ s/\377([^\377]*)$/\Q$1\E\$/;
                $lhs =~ s/\377([^\377]*)$/\Q$1\E/;
                $lhs =~ s/\377//g;
+               $lhs =~ s/\.\*\?$/.*/; # Allow %s at the end to eat it all
            } 
-           $transmo .= "    s{^$lhs}\n     {\Q$rhs\E}\n\t&& return 1;\n";
+           $transmo .= "    s{^$lhs}\n     {\Q$rhs\E}s\n\t&& return 1;\n";
        } else {
            $transmo .= "    m{^\Q$header\E} && return 1;\n";
        } 
@@ -506,7 +507,7 @@ sub unescape {
 
 sub shorten {
     my $line = $_[0];
-    if (length $line > 79) {
+    if (length $line > 79 and index $line, "\n" == -1) {
        my $space_place = rindex($line, ' ', 79);
        if ($space_place != -1) {
            substr($line, $space_place, 1) = "\n\t";
index 0495459..2bbb639 100644 (file)
@@ -149,9 +149,10 @@ the "class" C<Number> (or one of its base classes)
 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
@@ -161,6 +162,10 @@ C<$a+=7>, or C<$a++>.  See L<MAGIC AUTOGENERATION>.  (Mathemagical
 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
@@ -269,6 +274,40 @@ see L<SPECIAL SYMBOLS FOR C<use overload>>.
 
 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
@@ -321,6 +360,9 @@ C<"nomethod"> value, and if this is missing, raises an exception.
 
 =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
@@ -484,16 +526,21 @@ Returns C<undef> or a reference to the method that implements C<op>.
 
 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
@@ -502,13 +549,17 @@ overloading is the checking of this flag.
 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
@@ -527,6 +578,14 @@ Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
 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
index 77502f2..8e595f5 100644 (file)
@@ -60,12 +60,17 @@ it's run through your pager, as in
 
     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 
@@ -105,10 +110,12 @@ Single step.  Executes until it reaches the beginning of another
 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>
 
@@ -129,7 +136,7 @@ List C<incr+1> lines starting at C<min>.
 
 =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
 
@@ -154,7 +161,9 @@ print it out.
 
 =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/
 
@@ -235,7 +244,13 @@ Set breakpoint at first line of subroutine after it is compiled.
 
 =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]
 
@@ -273,34 +288,41 @@ be abbreviated.  Several options can be listed.
 
 =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>
 
@@ -317,7 +339,14 @@ C<frame & 2> is false, messages are printed on entry only. (Printing
 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
 
@@ -326,29 +355,38 @@ commands:
 
 =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
 
@@ -358,7 +396,7 @@ C<ReadLine>, and C<NonStop> there.
 
 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
@@ -370,13 +408,6 @@ C<LineInfo> to something "interactive"!)
 
 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
@@ -405,7 +436,7 @@ programmatically by setting $DB::signal or $DB::single.
 
 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
@@ -416,7 +447,7 @@ C<Dump*> options).
 
 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
@@ -424,13 +455,13 @@ interrupt it, you would better reset C<LineInfo> to something
 "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.
 
@@ -527,20 +558,34 @@ output, such as
 
 =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>
@@ -557,9 +602,12 @@ you'd already at a breakpoint and then printed out the result of a
 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";   \
@@ -572,7 +620,10 @@ normally end the debugger command with a backslash.  Here's an example:
 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
@@ -589,6 +640,160 @@ I<camel_flea> file with four arguments.  The last stack frame shows that
 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
@@ -604,6 +809,15 @@ just typed the C<n> command, whereas a value of 1 means the C<s>
 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
@@ -647,6 +861,10 @@ the Term::ReadKey and Term::ReadLine modules from CPAN, you will
 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
@@ -683,9 +901,9 @@ in that profile.
 
 =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:
@@ -752,7 +970,7 @@ a breakpoint, a call to C<DB::DB()> is performed if any one of
 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 *
 
@@ -764,10 +982,42 @@ in the package C<DB>.)
 =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
 
index d08d2dc..68cc69d 100644 (file)
@@ -799,6 +799,12 @@ Perhaps you need to copy the value to a temporary, and repeat that.
 (F) The create routine failed for some reason while trying to process
 a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
 
+=item Cannot resolve method `%s' overloading `%s' in package `%s'
+
+(F|P) Error resolving overloading specified by a method name (as
+opposed to a subroutine reference): no such method callable via the
+package. If method name is C<???>, this is an internal error.
+
 =item chmod: mode argument is missing initial 0
 
 (W) A novice will sometimes say
@@ -823,6 +829,10 @@ the return value of your socket() call?  See L<perlfunc/connect>.
 inlining.  See L<perlsub/"Constant Functions"> for commentary and
 workarounds.
 
+=item Copy method did not return a reference
+
+(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>.
+
 =item Corrupt malloc ptr 0x%lx at 0x%lx
 
 (P) The malloc package that comes with Perl had an internal failure.
@@ -1177,7 +1187,7 @@ assume that an unbackslashed @ interpolates an array.)
 =item Method for operation %s not found in package %s during blessing
 
 (F) An attempt was made to specify an entry in an overloading table that
-doesn't somehow point to a valid method.  See L<overload>.
+doesn't resolve to a valid subroutine.  See L<overload>.
 
 =item Might be a runaway multi-line %s string starting on line %d
 
@@ -1420,7 +1430,7 @@ subroutine), but found a reference to something else instead.  You can
 use the ref() function to find out what kind of ref it really was.
 See also L<perlref>.
 
-=item Not a subroutine reference in %OVERLOAD
+=item Not a subroutine reference in overload table
 
 (F) An attempt was made to specify an entry in an overloading table that
 doesn't somehow point to a valid subroutine.  See L<overload>.
@@ -1487,21 +1497,13 @@ will extend the buffer and zero pad the new area.
 
 (S) An internal warning that the grammar is screwed up.
 
-=item Operation `%s' %s: no method found,
-
-(F) An attempt was made to use an entry in an overloading table that
-somehow no longer points to a valid method.  See L<overload>.
-
-=item Stub found while resolving method `%s' overloading `%s' in package `%s'
-
-(P) Overloading resolution over @ISA tree may be broken by importing stubs.
-Stubs should never be implicitely created, but explicit calls to C<can>
-may break this.
+=item Operation `%s': no method found,%s
 
-=item Cannot resolve method `%s' overloading `%s' in package `s'
-
-(P) Internal error trying to resolve overloading specified by a method
-name (as opposed to a subroutine reference).
+(F) An attempt was made to perform an overloaded operation for which
+no handler was defined.  While some handlers can be autogenerated in
+terms of other handlers, there is no default handler for any
+operation, unless C<fallback> overloading key is specified to be
+true.  See L<overload>.
 
 =item Operator or semicolon missing before %s
 
@@ -2002,6 +2004,12 @@ there was a failure.  You probably wanted to use system() instead,
 which does return.  To suppress this warning, put the exec() in a block
 by itself.
 
+=item Stub found while resolving method `%s' overloading `%s' in package `%s'
+
+(P) Overloading resolution over @ISA tree may be broken by importation stubs.
+Stubs should never be implicitely created, but explicit calls to C<can>
+may break this.
+
 =item Subroutine %s redefined
 
 (W) You redefined a subroutine.  To suppress this warning, say
index 488c797..34d9281 100644 (file)
@@ -408,8 +408,17 @@ With EXPR, it returns some extra information that the debugger uses to
 print a stack trace.  The value of EXPR indicates how many call frames
 to go back before the current one.
 
-    ($package, $filename, $line,
-     $subroutine, $hasargs, $wantarray) = caller($i);
+    ($package, $filename, $line, $subroutine, 
+     $hasargs, $wantarray, $evaltext, $is_require) = caller($i);
+
+Here $subroutine may be C<"(eval)"> if the frame is not a subroutine
+call, but C<L<eval>>. In such a case additional elements $evaltext and
+$is_require are set: $is_require is true if the frame is created by
+C<L<require>> or C<L<use>> statement, $evaltext contains the text of
+C<L<eval EXPR>> statement. In particular, for C<L<eval BLOCK>>
+statement $filename is C<"(eval)">, but $evaltext is undefined. (Note
+also that C<L<use>> statement creates a C<L<require>> frame inside
+an C<L<eval EXPR>>) frame.
 
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable @DB::args to be the
index dd3aeab..55108f0 100644 (file)
@@ -737,6 +737,32 @@ The last example should print:
 Note how C<m//g> matches change the value reported by C<pos()>, but the
 non-global match doesn't.
 
+A useful idiom for C<lex>-like scanners is C</\G.../g>. You can
+combine several regexps like this to process a string part-by-part,
+doing different actions depending on which regexp matched.  The next
+regexp would step in at the place the previous one left off.
+
+    $_ = <<'EOL';
+      $url = new URI::URL "http://www/";   die if $url eq "xXx";
+EOL
+  LOOP:
+    {
+      print(" digits"),                redo LOOP if /\G\d+\b[,.;]?\s*/g;
+      print(" lowercase"),     redo LOOP if /\G[a-z]+\b[,.;]?\s*/g;
+      print(" UPPERCASE"),     redo LOOP if /\G[A-Z]+\b[,.;]?\s*/g;
+      print(" Capitalized"),   redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/g;
+      print(" MiXeD"),         redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/g;
+      print(" alphanumeric"),  redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/g;
+      print(" line-noise"),    redo LOOP if /\G[^A-Za-z0-9]+/g;
+      print ". That's all!\n";
+    }
+
+Here is the output (split into several lines):
+
+ line-noise lowercase line-noise lowercase UPPERCASE line-noise
+ UPPERCASE line-noise lowercase line-noise lowercase line-noise
+ lowercase lowercase line-noise lowercase lowercase line-noise
+ MiXeD line-noise. That's all!
 
 =item q/STRING/
 
index a4c0a7d..cb3ce03 100644 (file)
@@ -175,7 +175,11 @@ just like "^" and "$" except that they won't match multiple times when the
 C</m> modifier is used, while "^" and "$" will match at every internal line
 boundary.  To match the actual end of the string, not ignoring newline,
 you can use C<\Z(?!\n)>.  The C<\G> assertion can be used to mix global
-matches (using C<m//g>) and non-global ones, as described in L<perlop>.
+matches (using C<m//g>) and non-global ones, as described in 
+L<perlop/"Regexp Quote-Like Operators">.
+It is also useful when writing C<lex>-like scanners, when you have several
+regexps which you want to match against consequent substrings of your
+string, see the previous reference.
 The actual location where C<\G> will match can also be influenced
 by using C<pos()> as an lvalue.  See L<perlfunc/pos>.
 
index 26418b5..35d74e9 100644 (file)
@@ -167,7 +167,21 @@ be received by Perl as the return value of the XSUB.
 
 If the XSUB has a return type of C<void> then the compiler will
 not supply a RETVAL variable for that function.  When using
-the PPCODE: directive the RETVAL variable may not be needed.
+the PPCODE: directive the RETVAL variable is not needed, unless used
+explicitly.
+
+If PPCODE: directive is not used, C<void> return value should be used
+only for subroutines which do not return a value, I<even if> CODE:
+directive is used which sets ST(0) explicitly. 
+
+Older versions of this document recommended to use C<void> return
+value in such cases. It was discovered that this could lead to
+segfaults in cases when XSUB was I<truely> C<void>. This practice is
+now deprecated, and may be not supported at some future version. Use
+the return value C<SV *> in such cases. (Currently C<xsubpp> contains
+some heuristic code which tries to disambiguate between "truely-void"
+and "old-practice-declared-as-void" functions. Hence your code is at
+mercy of this heuristics unless you use C<SV *> as return value.)
 
 =head2 The MODULE Keyword
 
@@ -570,13 +584,13 @@ of $timep will either be undef or it will be a valid time.
 
      $timep = rpcb_gettime( "localhost" );
 
-The following XSUB uses the C<void> return type to disable the generation of
-the RETVAL variable and uses a CODE: block to indicate to the compiler
+The following XSUB uses the C<SV *> return type as a mneumonic only,
+and uses a CODE: block to indicate to the compiler
 that the programmer has supplied all the necessary code.  The
 sv_newmortal() call will initialize the return value to undef, making that
 the default return value.
 
-     void
+     SV *
      rpcb_gettime(host)
           char *  host
          PREINIT:
@@ -590,7 +604,7 @@ the default return value.
 The next example demonstrates how one would place an explicit undef in the
 return value, should the need arise.
 
-     void
+     SV *
      rpcb_gettime(host)
           char *  host
          PREINIT:
@@ -1102,7 +1116,7 @@ File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
 
      MODULE = RPC  PACKAGE = RPC
 
-     void
+     SV *
      rpcb_gettime(host="localhost")
           char *host
          PREINIT: