From: Fred Drake <fdrake@acm.org>
Date: Thu, 27 Dec 2001 05:09:45 +0000 (+0000)
Subject: Elaborate the descriptions for onecmd(), precmd(), and postcmd() so they are
X-Git-Tag: v2.1.2c1~23
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8f2d8a7c83a5e5902314de819b0849114fb93bd3;p=thirdparty%2FPython%2Fcpython.git

Elaborate the descriptions for onecmd(), precmd(), and postcmd() so they are
useful.  Includes one correction in the precmd() description.
---

diff --git a/Doc/lib/libcmd.tex b/Doc/lib/libcmd.tex
index e38fc241c76b..f24add37f4c7 100644
--- a/Doc/lib/libcmd.tex
+++ b/Doc/lib/libcmd.tex
@@ -56,8 +56,11 @@ any undocumented commands.
 \end{methoddesc}
 
 \begin{methoddesc}{onecmd}{str}
-Interpret the argument as though it had been typed in in
-response to the prompt.
+Interpret the argument as though it had been typed in response to the
+prompt.  This may be overridden, but should not normally need to be;
+see the \method{precmd()} and \method{postcmd()} methods for useful
+execution hooks.  The return value is a flag indicating whether
+interpretation of commands by the interpreter should stop.
 \end{methoddesc}
 
 \begin{methoddesc}{emptyline}{}
@@ -73,15 +76,25 @@ error message and returns.
 \end{methoddesc}
 
 \begin{methoddesc}{precmd}{}
-Hook method executed just before the input prompt is issued.  This
+Hook method executed just before the command line \var{line} is
+interpreted, but after the input prompt is generated and issued.  This
 method is a stub in \class{Cmd}; it exists to be overridden by
-subclasses.
+subclasses.  The return value is used as the command which will be
+executed by the \method{onecmd()} method; the \method{precmd()}
+implementation may re-write the command or simply return \var{line}
+unchanged.
 \end{methoddesc}
 
-\begin{methoddesc}{postcmd}{}
+\begin{methoddesc}{postcmd}{stop, line}
 Hook method executed just after a command dispatch is finished.  This
 method is a stub in \class{Cmd}; it exists to be overridden by
-subclasses.
+subclasses.  \var{line} is the command line which was executed, and
+\var{stop} is a flag which indicates whether execution will be
+terminated after the call to \method{postcmd()}; this will be the
+return value of the \method{onecmd()} method.  The return value of
+this method will be used as the new value for the internal flag which
+corresponds to \var{stop}; returning false will cause interpretation
+to continue.
 \end{methoddesc}
 
 \begin{methoddesc}{preloop}{}