Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libcmd.tex @ 15842:f6cd36498a50 legacy-trunk
Document extensions to .pth files.
| author | Martin v. Löwis <martin@v.loewis.de> |
|---|---|
| date | Sat, 13 Jan 2001 09:54:41 +0000 |
| parents | 563dee598d3a |
| children | b3dce06868d6 |
| rev | line source |
|---|---|
| 8918 | 1 \section{\module{cmd} --- |
|
15142
563dee598d3a
Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents:
13560
diff
changeset
|
2 Support for line-oriented command interpreters} |
|
563dee598d3a
Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents:
13560
diff
changeset
|
3 |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
8619
diff
changeset
|
4 \declaremodule{standard}{cmd} |
| 8918 | 5 \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} |
|
15142
563dee598d3a
Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents:
13560
diff
changeset
|
6 \modulesynopsis{Build line-oriented command interpreters.} |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
8619
diff
changeset
|
7 |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
8 |
| 8619 | 9 The \class{Cmd} class provides a simple framework for writing |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
10 line-oriented command interpreters. These are often useful for |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
11 test harnesses, administrative tools, and prototypes that will |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
12 later be wrapped in a more sophisticated interface. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
13 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
14 \begin{classdesc}{Cmd}{} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
15 A \class{Cmd} instance or subclass instance is a line-oriented |
| 8619 | 16 interpreter framework. There is no good reason to instantiate |
| 17 \class{Cmd} itself; rather, it's useful as a superclass of an | |
| 18 interpreter class you define yourself in order to inherit | |
| 19 \class{Cmd}'s methods and encapsulate action methods. | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
20 \end{classdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
21 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
22 \subsection{Cmd Objects} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
23 \label{Cmd-objects} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
24 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
25 A \class{Cmd} instance has the following methods: |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
26 |
| 8619 | 27 \begin{methoddesc}{cmdloop}{\optional{intro}} |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
28 Repeatedly issue a prompt, accept input, parse an initial prefix off |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
29 the received input, and dispatch to action methods, passing them the |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
30 remainder of the line as argument. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
31 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
32 The optional argument is a banner or intro string to be issued before the |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
33 first prompt (this overrides the \member{intro} class member). |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
34 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
35 If the \module{readline} module is loaded, input will automatically |
| 8619 | 36 inherit \program{bash}-like history-list editing (e.g. \kbd{Ctrl-P} |
| 37 scrolls back to the last command, \kbd{Ctrl-N} forward to the next | |
| 38 one, \kbd{Ctrl-F} moves the cursor to the right non-destructively, | |
| 39 \kbd{Ctrl-B} moves the cursor to the left non-destructively, etc.). | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
40 |
| 8619 | 41 An end-of-file on input is passed back as the string \code{'EOF'}. |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
42 |
| 8619 | 43 An interpreter instance will recognize a command name \samp{foo} if |
| 44 and only if it has a method \method{do_foo()}. As a special case, | |
|
13560
6987e9450619
Resynchronize the TeX docs with (a) the module docstring, and (b) my recent
Eric S. Raymond <esr@thyrsus.com>
parents:
8918
diff
changeset
|
45 a line beginning with the character \character{?} is dispatched to |
| 8619 | 46 the method \method{do_help()}. As another special case, a line |
|
13560
6987e9450619
Resynchronize the TeX docs with (a) the module docstring, and (b) my recent
Eric S. Raymond <esr@thyrsus.com>
parents:
8918
diff
changeset
|
47 beginning with the character \character{!} is dispatched to the |
| 8619 | 48 method \method{do_shell} (if such a method is defined). |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
49 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
50 All subclasses of \class{Cmd} inherit a predefined \method{do_help}. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
51 This method, called with an argument \code{bar}, invokes the |
| 8619 | 52 corresponding method \method{help_bar()}. With no argument, |
| 53 \method{do_help()} lists all available help topics (that is, all | |
| 54 commands with corresponding \method{help_*()} methods), and also lists | |
| 55 any undocumented commands. | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
56 \end{methoddesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
57 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
58 \begin{methoddesc}{onecmd}{str} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
59 Interpret the argument as though it had been typed in in |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
60 response to the prompt. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
61 \end{methoddesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
62 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
63 \begin{methoddesc}{emptyline}{} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
64 Method called when an empty line is entered in response to the prompt. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
65 If this method is not overridden, it repeats the last nonempty command |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
66 entered. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
67 \end{methoddesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
68 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
69 \begin{methoddesc}{default}{line} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
70 Method called on an input line when the command prefix is not |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
71 recognized. If this method is not overridden, it prints an |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
72 error message and returns. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
73 \end{methoddesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
74 |
| 8619 | 75 \begin{methoddesc}{precmd}{} |
| 76 Hook method executed just before the input prompt is issued. This | |
| 77 method is a stub in \class{Cmd}; it exists to be overridden by | |
| 78 subclasses. | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
79 \end{methoddesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
80 |
| 8619 | 81 \begin{methoddesc}{postcmd}{} |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
82 Hook method executed just after a command dispatch is finished. This |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
83 method is a stub in \class{Cmd}; it exists to be overridden by |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
84 subclasses. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
85 \end{methoddesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
86 |
| 8619 | 87 \begin{methoddesc}{preloop}{} |
| 88 Hook method executed once when \method{cmdloop()} is called. This | |
| 89 method is a stub in \class{Cmd}; it exists to be overridden by | |
| 90 subclasses. | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
91 \end{methoddesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
92 |
| 8619 | 93 \begin{methoddesc}{postloop}{} |
| 94 Hook method executed once when \method{cmdloop()} is about to return. | |
| 95 This method is a stub in \class{Cmd}; it exists to be overridden by | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
96 subclasses. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
97 \end{methoddesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
98 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
99 Instances of \class{Cmd} subclasses have some public instance variables: |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
100 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
101 \begin{memberdesc}{prompt} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
102 The prompt issued to solicit input. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
103 \end{memberdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
104 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
105 \begin{memberdesc}{identchars} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
106 The string of characters accepted for the command prefix. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
107 \end{memberdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
108 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
109 \begin{memberdesc}{lastcmd} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
110 The last nonempty command prefix seen. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
111 \end{memberdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
112 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
113 \begin{memberdesc}{intro} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
114 A string to issue as an intro or banner. May be overridden by giving |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
115 the \method{cmdloop()} method an argument. |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
116 \end{memberdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
117 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
118 \begin{memberdesc}{doc_header} |
| 8619 | 119 The header to issue if the help output has a section for documented |
| 120 commands. | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
121 \end{memberdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
122 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
123 \begin{memberdesc}{misc_header} |
| 8619 | 124 The header to issue if the help output has a section for miscellaneous |
| 125 help topics (that is, there are \method{help_*()} methods without | |
| 126 corresponding \method{do_*()} methods). | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
127 \end{memberdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
128 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
129 \begin{memberdesc}{undoc_header} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
130 The header to issue if the help output has a section for undocumented |
| 8619 | 131 commands (that is, there are \method{do_*()} methods without |
| 132 corresponding \method{help_*()} methods). | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
133 \end{memberdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
134 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
135 \begin{memberdesc}{ruler} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
136 The character used to draw separator lines under the help-message |
| 8619 | 137 headers. If empty, no ruler line is drawn. It defaults to |
| 138 \character{=}. | |
|
8572
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
139 \end{memberdesc} |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
140 |
|
ea8f0f5ab015
Contributions by Eric Raymond: documentation for modules
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
141 |
