1 | """A generic class to build line-oriented command interpreters. |
---|
2 | |
---|
3 | Interpreters constructed with this class obey the following conventions: |
---|
4 | |
---|
5 | 1. End of file on input is processed as the command 'EOF'. |
---|
6 | 2. A command is parsed out of each line by collecting the prefix composed |
---|
7 | of characters in the identchars member. |
---|
8 | 3. A command `foo' is dispatched to a method 'do_foo()'; the do_ method |
---|
9 | is passed a single argument consisting of the remainder of the line. |
---|
10 | 4. Typing an empty line repeats the last command. (Actually, it calls the |
---|
11 | method `emptyline', which may be overridden in a subclass.) |
---|
12 | 5. There is a predefined `help' method. Given an argument `topic', it |
---|
13 | calls the command `help_topic'. With no arguments, it lists all topics |
---|
14 | with defined help_ functions, broken into up to three topics; documented |
---|
15 | commands, miscellaneous help topics, and undocumented commands. |
---|
16 | 6. The command '?' is a synonym for `help'. The command '!' is a synonym |
---|
17 | for `shell', if a do_shell method exists. |
---|
18 | 7. If completion is enabled, completing commands will be done automatically, |
---|
19 | and completing of commands args is done by calling complete_foo() with |
---|
20 | arguments text, line, begidx, endidx. text is string we are matching |
---|
21 | against, all returned matches must begin with it. line is the current |
---|
22 | input line (lstripped), begidx and endidx are the beginning and end |
---|
23 | indexes of the text being matched, which could be used to provide |
---|
24 | different completion depending upon which position the argument is in. |
---|
25 | |
---|
26 | The `default' method may be overridden to intercept commands for which there |
---|
27 | is no do_ method. |
---|
28 | |
---|
29 | The `completedefault' method may be overridden to intercept completions for |
---|
30 | commands that have no complete_ method. |
---|
31 | |
---|
32 | The data member `self.ruler' sets the character used to draw separator lines |
---|
33 | in the help messages. If empty, no ruler line is drawn. It defaults to "=". |
---|
34 | |
---|
35 | If the value of `self.intro' is nonempty when the cmdloop method is called, |
---|
36 | it is printed out on interpreter startup. This value may be overridden |
---|
37 | via an optional argument to the cmdloop() method. |
---|
38 | |
---|
39 | The data members `self.doc_header', `self.misc_header', and |
---|
40 | `self.undoc_header' set the headers used for the help function's |
---|
41 | listings of documented functions, miscellaneous topics, and undocumented |
---|
42 | functions respectively. |
---|
43 | |
---|
44 | These interpreters use raw_input; thus, if the readline module is loaded, |
---|
45 | they automatically support Emacs-like command history and editing features. |
---|
46 | """ |
---|
47 | |
---|
48 | import string |
---|
49 | |
---|
50 | __all__ = ["Cmd"] |
---|
51 | |
---|
52 | PROMPT = '(Cmd) ' |
---|
53 | IDENTCHARS = string.ascii_letters + string.digits + '_' |
---|
54 | |
---|
55 | class Cmd: |
---|
56 | """A simple framework for writing line-oriented command interpreters. |
---|
57 | |
---|
58 | These are often useful for test harnesses, administrative tools, and |
---|
59 | prototypes that will later be wrapped in a more sophisticated interface. |
---|
60 | |
---|
61 | A Cmd instance or subclass instance is a line-oriented interpreter |
---|
62 | framework. There is no good reason to instantiate Cmd itself; rather, |
---|
63 | it's useful as a superclass of an interpreter class you define yourself |
---|
64 | in order to inherit Cmd's methods and encapsulate action methods. |
---|
65 | |
---|
66 | """ |
---|
67 | prompt = PROMPT |
---|
68 | identchars = IDENTCHARS |
---|
69 | ruler = '=' |
---|
70 | lastcmd = '' |
---|
71 | intro = None |
---|
72 | doc_leader = "" |
---|
73 | doc_header = "Documented commands (type help <topic>):" |
---|
74 | misc_header = "Miscellaneous help topics:" |
---|
75 | undoc_header = "Undocumented commands:" |
---|
76 | nohelp = "*** No help on %s" |
---|
77 | use_rawinput = 1 |
---|
78 | |
---|
79 | def __init__(self, completekey='tab', stdin=None, stdout=None): |
---|
80 | """Instantiate a line-oriented interpreter framework. |
---|
81 | |
---|
82 | The optional argument 'completekey' is the readline name of a |
---|
83 | completion key; it defaults to the Tab key. If completekey is |
---|
84 | not None and the readline module is available, command completion |
---|
85 | is done automatically. The optional arguments stdin and stdout |
---|
86 | specify alternate input and output file objects; if not specified, |
---|
87 | sys.stdin and sys.stdout are used. |
---|
88 | |
---|
89 | """ |
---|
90 | import sys |
---|
91 | if stdin is not None: |
---|
92 | self.stdin = stdin |
---|
93 | else: |
---|
94 | self.stdin = sys.stdin |
---|
95 | if stdout is not None: |
---|
96 | self.stdout = stdout |
---|
97 | else: |
---|
98 | self.stdout = sys.stdout |
---|
99 | self.cmdqueue = [] |
---|
100 | self.completekey = completekey |
---|
101 | |
---|
102 | def cmdloop(self, intro=None): |
---|
103 | """Repeatedly issue a prompt, accept input, parse an initial prefix |
---|
104 | off the received input, and dispatch to action methods, passing them |
---|
105 | the remainder of the line as argument. |
---|
106 | |
---|
107 | """ |
---|
108 | |
---|
109 | self.preloop() |
---|
110 | if self.use_rawinput and self.completekey: |
---|
111 | try: |
---|
112 | import readline |
---|
113 | self.old_completer = readline.get_completer() |
---|
114 | readline.set_completer(self.complete) |
---|
115 | readline.parse_and_bind(self.completekey+": complete") |
---|
116 | except ImportError: |
---|
117 | pass |
---|
118 | try: |
---|
119 | if intro is not None: |
---|
120 | self.intro = intro |
---|
121 | if self.intro: |
---|
122 | self.stdout.write(str(self.intro)+"\n") |
---|
123 | stop = None |
---|
124 | while not stop: |
---|
125 | if self.cmdqueue: |
---|
126 | line = self.cmdqueue.pop(0) |
---|
127 | else: |
---|
128 | if self.use_rawinput: |
---|
129 | try: |
---|
130 | line = raw_input(self.prompt) |
---|
131 | except EOFError: |
---|
132 | line = 'EOF' |
---|
133 | else: |
---|
134 | self.stdout.write(self.prompt) |
---|
135 | self.stdout.flush() |
---|
136 | line = self.stdin.readline() |
---|
137 | if not len(line): |
---|
138 | line = 'EOF' |
---|
139 | else: |
---|
140 | line = line.rstrip('\r\n') |
---|
141 | line = self.precmd(line) |
---|
142 | stop = self.onecmd(line) |
---|
143 | stop = self.postcmd(stop, line) |
---|
144 | self.postloop() |
---|
145 | finally: |
---|
146 | if self.use_rawinput and self.completekey: |
---|
147 | try: |
---|
148 | import readline |
---|
149 | readline.set_completer(self.old_completer) |
---|
150 | except ImportError: |
---|
151 | pass |
---|
152 | |
---|
153 | |
---|
154 | def precmd(self, line): |
---|
155 | """Hook method executed just before the command line is |
---|
156 | interpreted, but after the input prompt is generated and issued. |
---|
157 | |
---|
158 | """ |
---|
159 | return line |
---|
160 | |
---|
161 | def postcmd(self, stop, line): |
---|
162 | """Hook method executed just after a command dispatch is finished.""" |
---|
163 | return stop |
---|
164 | |
---|
165 | def preloop(self): |
---|
166 | """Hook method executed once when the cmdloop() method is called.""" |
---|
167 | pass |
---|
168 | |
---|
169 | def postloop(self): |
---|
170 | """Hook method executed once when the cmdloop() method is about to |
---|
171 | return. |
---|
172 | |
---|
173 | """ |
---|
174 | pass |
---|
175 | |
---|
176 | def parseline(self, line): |
---|
177 | """Parse the line into a command name and a string containing |
---|
178 | the arguments. Returns a tuple containing (command, args, line). |
---|
179 | 'command' and 'args' may be None if the line couldn't be parsed. |
---|
180 | """ |
---|
181 | line = line.strip() |
---|
182 | if not line: |
---|
183 | return None, None, line |
---|
184 | elif line[0] == '?': |
---|
185 | line = 'help ' + line[1:] |
---|
186 | elif line[0] == '!': |
---|
187 | if hasattr(self, 'do_shell'): |
---|
188 | line = 'shell ' + line[1:] |
---|
189 | else: |
---|
190 | return None, None, line |
---|
191 | i, n = 0, len(line) |
---|
192 | while i < n and line[i] in self.identchars: i = i+1 |
---|
193 | cmd, arg = line[:i], line[i:].strip() |
---|
194 | return cmd, arg, line |
---|
195 | |
---|
196 | def onecmd(self, line): |
---|
197 | """Interpret the argument as though it had been typed in response |
---|
198 | to the prompt. |
---|
199 | |
---|
200 | This may be overridden, but should not normally need to be; |
---|
201 | see the precmd() and postcmd() methods for useful execution hooks. |
---|
202 | The return value is a flag indicating whether interpretation of |
---|
203 | commands by the interpreter should stop. |
---|
204 | |
---|
205 | """ |
---|
206 | cmd, arg, line = self.parseline(line) |
---|
207 | if not line: |
---|
208 | return self.emptyline() |
---|
209 | if cmd is None: |
---|
210 | return self.default(line) |
---|
211 | self.lastcmd = line |
---|
212 | if line == 'EOF' : |
---|
213 | self.lastcmd = '' |
---|
214 | if cmd == '': |
---|
215 | return self.default(line) |
---|
216 | else: |
---|
217 | try: |
---|
218 | func = getattr(self, 'do_' + cmd) |
---|
219 | except AttributeError: |
---|
220 | return self.default(line) |
---|
221 | return func(arg) |
---|
222 | |
---|
223 | def emptyline(self): |
---|
224 | """Called when an empty line is entered in response to the prompt. |
---|
225 | |
---|
226 | If this method is not overridden, it repeats the last nonempty |
---|
227 | command entered. |
---|
228 | |
---|
229 | """ |
---|
230 | if self.lastcmd: |
---|
231 | return self.onecmd(self.lastcmd) |
---|
232 | |
---|
233 | def default(self, line): |
---|
234 | """Called on an input line when the command prefix is not recognized. |
---|
235 | |
---|
236 | If this method is not overridden, it prints an error message and |
---|
237 | returns. |
---|
238 | |
---|
239 | """ |
---|
240 | self.stdout.write('*** Unknown syntax: %s\n'%line) |
---|
241 | |
---|
242 | def completedefault(self, *ignored): |
---|
243 | """Method called to complete an input line when no command-specific |
---|
244 | complete_*() method is available. |
---|
245 | |
---|
246 | By default, it returns an empty list. |
---|
247 | |
---|
248 | """ |
---|
249 | return [] |
---|
250 | |
---|
251 | def completenames(self, text, *ignored): |
---|
252 | dotext = 'do_'+text |
---|
253 | return [a[3:] for a in self.get_names() if a.startswith(dotext)] |
---|
254 | |
---|
255 | def complete(self, text, state): |
---|
256 | """Return the next possible completion for 'text'. |
---|
257 | |
---|
258 | If a command has not been entered, then complete against command list. |
---|
259 | Otherwise try to call complete_<command> to get list of completions. |
---|
260 | """ |
---|
261 | if state == 0: |
---|
262 | import readline |
---|
263 | origline = readline.get_line_buffer() |
---|
264 | line = origline.lstrip() |
---|
265 | stripped = len(origline) - len(line) |
---|
266 | begidx = readline.get_begidx() - stripped |
---|
267 | endidx = readline.get_endidx() - stripped |
---|
268 | if begidx>0: |
---|
269 | cmd, args, foo = self.parseline(line) |
---|
270 | if cmd == '': |
---|
271 | compfunc = self.completedefault |
---|
272 | else: |
---|
273 | try: |
---|
274 | compfunc = getattr(self, 'complete_' + cmd) |
---|
275 | except AttributeError: |
---|
276 | compfunc = self.completedefault |
---|
277 | else: |
---|
278 | compfunc = self.completenames |
---|
279 | self.completion_matches = compfunc(text, line, begidx, endidx) |
---|
280 | try: |
---|
281 | return self.completion_matches[state] |
---|
282 | except IndexError: |
---|
283 | return None |
---|
284 | |
---|
285 | def get_names(self): |
---|
286 | # This method used to pull in base class attributes |
---|
287 | # at a time dir() didn't do it yet. |
---|
288 | return dir(self.__class__) |
---|
289 | |
---|
290 | def complete_help(self, *args): |
---|
291 | commands = set(self.completenames(*args)) |
---|
292 | topics = set(a[5:] for a in self.get_names() |
---|
293 | if a.startswith('help_' + args[0])) |
---|
294 | return list(commands | topics) |
---|
295 | |
---|
296 | def do_help(self, arg): |
---|
297 | 'List available commands with "help" or detailed help with "help cmd".' |
---|
298 | if arg: |
---|
299 | # XXX check arg syntax |
---|
300 | try: |
---|
301 | func = getattr(self, 'help_' + arg) |
---|
302 | except AttributeError: |
---|
303 | try: |
---|
304 | doc=getattr(self, 'do_' + arg).__doc__ |
---|
305 | if doc: |
---|
306 | self.stdout.write("%s\n"%str(doc)) |
---|
307 | return |
---|
308 | except AttributeError: |
---|
309 | pass |
---|
310 | self.stdout.write("%s\n"%str(self.nohelp % (arg,))) |
---|
311 | return |
---|
312 | func() |
---|
313 | else: |
---|
314 | names = self.get_names() |
---|
315 | cmds_doc = [] |
---|
316 | cmds_undoc = [] |
---|
317 | help = {} |
---|
318 | for name in names: |
---|
319 | if name[:5] == 'help_': |
---|
320 | help[name[5:]]=1 |
---|
321 | names.sort() |
---|
322 | # There can be duplicates if routines overridden |
---|
323 | prevname = '' |
---|
324 | for name in names: |
---|
325 | if name[:3] == 'do_': |
---|
326 | if name == prevname: |
---|
327 | continue |
---|
328 | prevname = name |
---|
329 | cmd=name[3:] |
---|
330 | if cmd in help: |
---|
331 | cmds_doc.append(cmd) |
---|
332 | del help[cmd] |
---|
333 | elif getattr(self, name).__doc__: |
---|
334 | cmds_doc.append(cmd) |
---|
335 | else: |
---|
336 | cmds_undoc.append(cmd) |
---|
337 | self.stdout.write("%s\n"%str(self.doc_leader)) |
---|
338 | self.print_topics(self.doc_header, cmds_doc, 15,80) |
---|
339 | self.print_topics(self.misc_header, help.keys(),15,80) |
---|
340 | self.print_topics(self.undoc_header, cmds_undoc, 15,80) |
---|
341 | |
---|
342 | def print_topics(self, header, cmds, cmdlen, maxcol): |
---|
343 | if cmds: |
---|
344 | self.stdout.write("%s\n"%str(header)) |
---|
345 | if self.ruler: |
---|
346 | self.stdout.write("%s\n"%str(self.ruler * len(header))) |
---|
347 | self.columnize(cmds, maxcol-1) |
---|
348 | self.stdout.write("\n") |
---|
349 | |
---|
350 | def columnize(self, list, displaywidth=80): |
---|
351 | """Display a list of strings as a compact set of columns. |
---|
352 | |
---|
353 | Each column is only as wide as necessary. |
---|
354 | Columns are separated by two spaces (one was not legible enough). |
---|
355 | """ |
---|
356 | if not list: |
---|
357 | self.stdout.write("<empty>\n") |
---|
358 | return |
---|
359 | nonstrings = [i for i in range(len(list)) |
---|
360 | if not isinstance(list[i], str)] |
---|
361 | if nonstrings: |
---|
362 | raise TypeError, ("list[i] not a string for i in %s" % |
---|
363 | ", ".join(map(str, nonstrings))) |
---|
364 | size = len(list) |
---|
365 | if size == 1: |
---|
366 | self.stdout.write('%s\n'%str(list[0])) |
---|
367 | return |
---|
368 | # Try every row count from 1 upwards |
---|
369 | for nrows in range(1, len(list)): |
---|
370 | ncols = (size+nrows-1) // nrows |
---|
371 | colwidths = [] |
---|
372 | totwidth = -2 |
---|
373 | for col in range(ncols): |
---|
374 | colwidth = 0 |
---|
375 | for row in range(nrows): |
---|
376 | i = row + nrows*col |
---|
377 | if i >= size: |
---|
378 | break |
---|
379 | x = list[i] |
---|
380 | colwidth = max(colwidth, len(x)) |
---|
381 | colwidths.append(colwidth) |
---|
382 | totwidth += colwidth + 2 |
---|
383 | if totwidth > displaywidth: |
---|
384 | break |
---|
385 | if totwidth <= displaywidth: |
---|
386 | break |
---|
387 | else: |
---|
388 | nrows = len(list) |
---|
389 | ncols = 1 |
---|
390 | colwidths = [0] |
---|
391 | for row in range(nrows): |
---|
392 | texts = [] |
---|
393 | for col in range(ncols): |
---|
394 | i = row + nrows*col |
---|
395 | if i >= size: |
---|
396 | x = "" |
---|
397 | else: |
---|
398 | x = list[i] |
---|
399 | texts.append(x) |
---|
400 | while texts and not texts[-1]: |
---|
401 | del texts[-1] |
---|
402 | for col in range(len(texts)): |
---|
403 | texts[col] = texts[col].ljust(colwidths[col]) |
---|
404 | self.stdout.write("%s\n"%str(" ".join(texts))) |
---|