| [2] | 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:
|
|---|
| [391] | 140 | line = line.rstrip('\r\n')
|
|---|
| [2] | 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
|
|---|
| [391] | 212 | if line == 'EOF' :
|
|---|
| 213 | self.lastcmd = ''
|
|---|
| [2] | 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):
|
|---|
| [391] | 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__)
|
|---|
| [2] | 289 |
|
|---|
| 290 | def complete_help(self, *args):
|
|---|
| [391] | 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)
|
|---|
| [2] | 295 |
|
|---|
| 296 | def do_help(self, arg):
|
|---|
| [391] | 297 | 'List available commands with "help" or detailed help with "help cmd".'
|
|---|
| [2] | 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)))
|
|---|
