Richard Wolff's changes:

pdb.doc		Updated to reflect better the various changes.

1 files changed, 185 insertions, 67 deletions

diff --git a/Lib/pdb.doc b/Lib/pdb.doc
index 6ae54e7..e8f0725 100644
--- a/Lib/pdb.doc
+++ b/Lib/pdb.doc
@@ -1,10 +1,10 @@
-The Python Debugger
-===================
+The Python Debugger Pdb
+=======================
 
 To use the debugger in its simplest form:
 
-        >>> import pdb
-        >>> pdb.run('<a statement>')
+	>>> import pdb
+	>>> pdb.run('<a statement>')
 
 The debugger's prompt is '(Pdb) '.  This will stop in the first
 function call in <a statement>.
@@ -13,10 +13,10 @@ Alternatively, if a statement terminated with an unhandled exception,
 you can use pdb's post-mortem facility to inspect the contents of the
 traceback:
 
-        >>> <a statement>
-        <exception traceback>
-        >>> import pdb
-        >>> pdb.pm()
+	>>> <a statement>
+	<exception traceback>
+	>>> import pdb
+	>>> pdb.pm()
 
 The commands recognized by the debugger are listed in the next
 section.  Most can be abbreviated as indicated; e.g., h(elp) means
@@ -24,8 +24,8 @@ that 'help' can be typed as 'h' or 'help' (but not as 'he' or 'hel',
 nor as 'H' or 'Help' or 'HELP').  Optional arguments are enclosed in
 square brackets.
 
-A blank line repeats the previous command literally.  (Except for
-'list', where it lists the next 11 lines.)
+A blank line repeats the previous command literally, except for
+'list', where it lists the next 11 lines.
 
 Commands that the debugger doesn't recognize are assumed to be Python
 statements and are executed in the context of the program being
@@ -35,90 +35,208 @@ debugged; it is even possible to change variables.  When an exception
 occurs in such a statement, the exception name is printed but the
 debugger's state is not changed.
 
-The debugger is not directly programmable; but it is implemented as a
-class from which you can derive your own debugger class, so you can
-make as fancy as you like.
+The debugger supports aliases, which can save typing.  And aliases
+can have parameters (see the alias help entry) which allows one a
+certain level of adaptability to the context under examination.
+
+Multiple commands may be entered on a single line, separated by
+semi-colons.  No intelligence is applied to separating the commands;
+the input is split at the first ';', even if it is in the middle of
+a quoted string.
+
+If a file ".pdbrc" exists in your home directory or in the current
+directory, it is read in and executed as if it had been typed at
+the debugger prompt.  This is particularly useful for aliases.
+If both files exist, the one in the home directory is read first
+and aliases defined there can be overriden by the local file.
+
+Aside from aliases, the debugger is not directly programmable; but
+it is implemented as a class from which you can derive your own
+debugger class, which you can make as fancy as you like.
 
 
 Debugger commands
 =================
 
 h(elp)
-        Without argument, print the list of available commands.
-        With a command name as argument, print help about that command
-        "help pdb" pipes the full documentation file to the $PAGER
-        "help exec" gives help on the ! command
+	Without argument, print the list of available commands.
+	With a command name as argument, print help about that command
+	(this is currently not implemented).
 
 w(here)
-        Print a stack trace, with the most recent frame at the bottom.
-        An arrow indicates the "current frame", which determines the
-        context of most commands.
+	Print a stack trace, with the most recent frame at the bottom.
+	An arrow indicates the "current frame", which determines the
+	context of most commands.
 
 d(own)
-        Move the current frame one level down in the stack trace
-        (to an older frame).
+	Move the current frame one level down in the stack trace
+	(to an older frame).
 
 u(p)
-        Move the current frame one level up in the stack trace
-        (to a newer frame).
-
-b(reak) ([file:]lineno | function) [, "condition"]
-        With a line number argument, set a break there in the current
-        file.  With a function name, set a break at the entry of that
-        function.  Without argument, list all breaks.  If a second
-        argument is present, it is a string specifying an expression
-        which must evaluate to true before the breakpoint is honored.
-
-        The line number may be prefixed with a filename and a colon,
-        to specify a breakpoint in another file (probably one that
-        hasn't been loaded yet).  The file is searched on sys.path.
-
-cl(ear) [lineno]
-        With a line number argument, clear that break in the current file.
-        Without argument, clear all breaks (but first ask confirmation).
-
-        The line number may be prefixed with a filename and a colon,
-        to specify a breakpoint in another file (probably one that
-        hasn't been loaded yet).  The file is searched on sys.path.
+	Move the current frame one level up in the stack trace
+	(to a newer frame).
+
+b(reak) [ ([filename:]lineno | function) [, "condition"] ]
+	With a filename:line number argument, set a break there.  If
+	filename is omitted, use the current file.  With a function name,
+	set a break at the first executable line of that function.
+	Without argument, list all breaks.  Each breakpoint is assigned
+	a number which is by all the other breakpoint commands refer to it.
+
+	The condition argument, if present, is a string which must
+	evaluate to true in order for the breakpoint to be honored.
+
+tbreak [ ([filename:]lineno | function) [, "condition"] ]
+	Temporary breakpoint, which is removed automatically when it is
+	first hit.  The arguments are the same as break.
+
+cl(ear) [bpnumber [bpnumber ...] ]
+	With a space separated list of breakpoint numbers, clear those
+	breakpoints.  Without argument, clear all breaks (but first
+	ask confirmation).
+
+disable bpnumber [bpnumber ...]
+	Disables the breakpoints given as a space separated list of
+	breakpoint numbers.  Disabling a breakpoint means it cannot cause
+	the program to stop execution, but unlike clearing a breakpoint, it
+	remains in the list of breakpoints and can be (re-)enabled.
+
+enable bpnumber [bpnumber ...]
+	Enables the breakpoints specified.
+
+ignore bpnumber count
+	Sets the ignore count for the given breakpoint number.  If
+	count is omitted, the ignore count is set to 0.  A breakpoint
+	becomes active when the ignore count is zero.  When non-zero,
+	the count is decremented each time the breakpoint is reached
+	and the breakpoint is not disabled and any associated condition
+	evaluates to true.
+
+condition bpnumber str_condition
+	str_condition is a string specifying an expression which
+	must evaluate to true before the breakpoint is honored.
+	If str_condition is absent, any existing condition is removed;
+	i.e., the breakpoint is made unconditional.
 
 s(tep)
-        Execute the current line, stop at the first possible occasion
-        (either in a function that is called or in the current function).
+	Execute the current line, stop at the first possible occasion
+	(either in a function that is called or in the current function).
 
 n(ext)
-        Continue execution until the next line in the current function
-        is reached or it returns.
+	Continue execution until the next line in the current function
+	is reached or it returns.
 
 r(eturn)
-        Continue execution until the current function returns.
+	Continue execution until the current function returns.
 
 c(ont(inue))
-        Continue execution, only stop when a breakpoint is encountered.
+	Continue execution, only stop when a breakpoint is encountered.
 
 l(ist) [first [,last]]
-        List source code for the current file.
-        Without arguments, list 11 lines around the current line
-        or continue the previous listing.
-        With one argument, list 11 lines starting at that line.
-        With two arguments, list the given range;
-        if the second argument is less than the first, it is a count.
+	List source code for the current file.
+	Without arguments, list 11 lines around the current line
+	or continue the previous listing.
+	With one argument, list 11 lines starting at that line.
+	With two arguments, list the given range;
+	if the second argument is less than the first, it is a count.
 
 a(rgs)
-        Print the argument list of the current function.
+	Print the argument list of the current function.
 
 p expression
-        Print the value of the expression.
+	Print the value of the expression.
 
 (!) statement
-        Execute the (one-line) statement in the context of
-        the current stack frame.
-        The exclamation point can be omitted unless the first word
-        of the statement resembles a debugger command.
-        To assign to a global variable you must always prefix the
-        command with a 'global' command, e.g.:
-        (Pdb) global list_options; list_options = ['-l']
-        (Pdb)
+	Execute the (one-line) statement in the context of the current
+	stack frame.  The exclamation point can be omitted unless the
+	first word of the statement resembles a debugger command.
+	To assign to a global variable you must always prefix the
+	command with a 'global' command, e.g.:
+	(Pdb) global list_options; list_options = ['-l']
+	(Pdb)
+
+
+whatis arg
+	 Prints the type of the argument.
+
+alias [name [command]]
+	Creates an alias called 'name' that executes 'command'.  The command
+	must *not* be enclosed in quotes.  Replaceable parameters can be
+	indicated by %1, %2, and so on, while %* is replaced by all the 
+	parameters.  If no command is given, the current alias for name
+	is shown. If no name is given, all aliases are listed.
+
+	Aliases may be nested and can contain anything that can be
+	legally typed at the pdb prompt.  Note!  You *can* override
+	internal pdb commands with aliases!  Those internal commands
+	are then hidden until the alias is removed.  Aliasing is recursively
+	applied to the first word of the command line; all other words
+	in the line are left alone.
+
+	As an example, here are two useful aliases (especially when placed
+	in the .pdbrc file):
+
+	#Print instance variables (usage "pi classInst")
+	alias pi for k in %1.__dict__.keys(): print "%1." + k + "=" + %1.__dict__[k]
+	#Print instance variables in self
+	alias ps pi self
+		
+unalias name
+	Deletes the specified alias.
 
 q(uit)
-        Quit from the debugger.
-        The program being executed is aborted.
+	Quit from the debugger.
+	The program being executed is aborted.
+
+
+How it works
+============
+
+Some changes were made to the interpreter:
+- sys.settrace(func) sets the global trace function
+- there can also a local trace function (see later)
+
+Trace functions have three arguments: (frame, event, arg)
+  - frame is the current stack frame
+  - event is a string: 'call', 'line', 'return' or 'exception'
+  - arg is dependent on the event type
+A trace function should return a new trace function or None.
+Class methods are accepted (and most useful!) as trace methods.
+
+The events have the following meaning:
+
+  'call':      A function is called (or some other code block entered).
+               The global trace function is called;
+               arg is the argument list to the function;
+               the return value specifies the local trace function.
+
+  'line':      The interpreter is about to execute a new line of code
+               (sometimes multiple line events on one line exist).
+               The local trace function is called; arg in None;
+               the return value specifies the new local trace function.
+
+  'return':    A function (or other code block) is about to return.
+               The local trace function is called;
+               arg is the value that will be returned.
+               The trace function's return value is ignored.
+
+  'exception': An exception has occurred.
+               The local trace function is called;
+               arg is a triple (exception, value, traceback);
+               the return value specifies the new local trace function
+
+Note that as an exception is propagated down the chain of callers, an
+'exception' event is generated at each level.
+
+Stack frame objects have the following read-only attributes:
+  f_code:      the code object being executed
+  f_lineno:    the current line number (-1 for 'call' events)
+  f_back:      the stack frame of the caller, or None
+  f_locals:    dictionary containing local name bindings
+  f_globals:   dictionary containing global name bindings
+
+Code objects have the following read-only attributes:
+  co_code:     the code string
+  co_names:    the list of names used by the code
+  co_consts:   the list of (literal) constants used by the code
+  co_filename: the filename from which the code was compiled