Lib/cmd.py

   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 intro is not None:
 111             self.intro = intro
 112         if self.intro:
 113             self.stdout.write(str(self.intro)+"\n")
 114         stop = None
 115         while not stop:
 116             if self.cmdqueue:
 117                 line = self.cmdqueue.pop(0)
 118             else:
 119                 if self.use_rawinput:
 120                     try:
 121                         line = raw_input(self.prompt)
 122                     except EOFError:
 123                         line = 'EOF'
 124                 else:
 125                     self.stdout.write(self.prompt)
 126                     self.stdout.flush()
 127                     line = self.stdin.readline()
 128                     if not len(line):
 129                         line = 'EOF'
 130                     else:
 131                         line = line[:-1] # chop \n
 132             line = self.precmd(line)
 133             stop = self.onecmd(line)
 134             stop = self.postcmd(stop, line)
 135         self.postloop()
 136
 137     def precmd(self, line):
 138         """Hook method executed just before the command line is
 139         interpreted, but after the input prompt is generated and issued.
 140
 141         """
 142         return line
 143
 144     def postcmd(self, stop, line):
 145         """Hook method executed just after a command dispatch is finished."""
 146         return stop
 147
 148     def preloop(self):
 149         """Hook method executed once when the cmdloop() method is called."""
 150         if self.completekey:
 151             try:
 152                 import readline
 153                 self.old_completer = readline.get_completer()
 154                 readline.set_completer(self.complete)
 155                 readline.parse_and_bind(self.completekey+": complete")
 156             except ImportError:
 157                 pass
 158
 159     def postloop(self):
 160         """Hook method executed once when the cmdloop() method is about to
 161         return.
 162
 163         """
 164         if self.completekey:
 165             try:
 166                 import readline
 167                 readline.set_completer(self.old_completer)
 168             except ImportError:
 169                 pass
 170
 171     def parseline(self, line):
 172         line = line.strip()
 173         if not line:
 174             return None, None, line
 175         elif line[0] == '?':
 176             line = 'help ' + line[1:]
 177         elif line[0] == '!':
 178             if hasattr(self, 'do_shell'):
 179                 line = 'shell ' + line[1:]
 180             else:
 181                 return None, None, line
 182         i, n = 0, len(line)
 183         while i < n and line[i] in self.identchars: i = i+1
 184         cmd, arg = line[:i], line[i:].strip()
 185         return cmd, arg, line
 186
 187     def onecmd(self, line):
 188         """Interpret the argument as though it had been typed in response
 189         to the prompt.
 190
 191         This may be overridden, but should not normally need to be;
 192         see the precmd() and postcmd() methods for useful execution hooks.
 193         The return value is a flag indicating whether interpretation of
 194         commands by the interpreter should stop.
 195
 196         """
 197         cmd, arg, line = self.parseline(line)
 198         if not line:
 199             return self.emptyline()
 200         if cmd is None:
 201             return self.default(line)
 202         self.lastcmd = line
 203         if cmd == '':
 204             return self.default(line)
 205         else:
 206             try:
 207                 func = getattr(self, 'do_' + cmd)
 208             except AttributeError:
 209                 return self.default(line)
 210             return func(arg)
 211
 212     def emptyline(self):
 213         """Called when an empty line is entered in response to the prompt.
 214
 215         If this method is not overridden, it repeats the last nonempty
 216         command entered.
 217
 218         """
 219         if self.lastcmd:
 220             return self.onecmd(self.lastcmd)
 221
 222     def default(self, line):
 223         """Called on an input line when the command prefix is not recognized.
 224
 225         If this method is not overridden, it prints an error message and
 226         returns.
 227
 228         """
 229         self.stdout.write('*** Unknown syntax: %s\n'%line)
 230
 231     def completedefault(self, *ignored):
 232         """Method called to complete an input line when no command-specific
 233         complete_*() method is available.
 234
 235         By default, it returns an empty list.
 236
 237         """
 238         return []
 239
 240     def completenames(self, text, *ignored):
 241         dotext = 'do_'+text
 242         return [a[3:] for a in self.get_names() if a.startswith(dotext)]
 243
 244     def complete(self, text, state):
 245         """Return the next possible completion for 'text'.
 246
 247         If a command has not been entered, then complete against command list.
 248         Otherwise try to call complete_<command> to get list of completions.
 249         """
 250         if state == 0:
 251             import readline
 252             origline = readline.get_line_buffer()
 253             line = origline.lstrip()
 254             stripped = len(origline) - len(line)
 255             begidx = readline.get_begidx() - stripped
 256             endidx = readline.get_endidx() - stripped
 257             if begidx>0:
 258                 cmd, args, foo = self.parseline(line)
 259                 if cmd == '':
 260                     compfunc = self.completedefault
 261                 else:
 262                     try:
 263                         compfunc = getattr(self, 'complete_' + cmd)
 264                     except AttributeError:
 265                         compfunc = self.completedefault
 266             else:
 267                 compfunc = self.completenames
 268             self.completion_matches = compfunc(text, line, begidx, endidx)
 269         try:
 270             return self.completion_matches[state]
 271         except IndexError:
 272             return None
 273
 274     def get_names(self):
 275         # Inheritance says we have to look in class and
 276         # base classes; order is not important.
 277         names = []
 278         classes = [self.__class__]
 279         while classes:
 280             aclass = classes.pop(0)
 281             if aclass.__bases__:
 282                 classes = classes + list(aclass.__bases__)
 283             names = names + dir(aclass)
 284         return names
 285
 286     def complete_help(self, *args):
 287         return self.completenames(*args)
 288
 289     def do_help(self, arg):
 290         if arg:
 291             # XXX check arg syntax
 292             try:
 293                 func = getattr(self, 'help_' + arg)
 294             except AttributeError:
 295                 try:
 296                     doc=getattr(self, 'do_' + arg).__doc__
 297                     if doc:
 298                         self.stdout.write("%s\n"%str(doc))
 299                         return
 300                 except AttributeError:
 301                     pass
 302                 self.stdout.write("%s\n"%str(self.nohelp % (arg,)))
 303                 return
 304             func()
 305         else:
 306             names = self.get_names()
 307             cmds_doc = []
 308             cmds_undoc = []
 309             help = {}
 310             for name in names:
 311                 if name[:5] == 'help_':
 312                     help[name[5:]]=1
 313             names.sort()
 314             # There can be duplicates if routines overridden
 315             prevname = ''
 316             for name in names:
 317                 if name[:3] == 'do_':
 318                     if name == prevname:
 319                         continue
 320                     prevname = name
 321                     cmd=name[3:]
 322                     if cmd in help:
 323                         cmds_doc.append(cmd)
 324                         del help[cmd]
 325                     elif getattr(self, name).__doc__:
 326                         cmds_doc.append(cmd)
 327                     else:
 328                         cmds_undoc.append(cmd)
 329             self.stdout.write("%s\n"%str(self.doc_leader))
 330             self.print_topics(self.doc_header,   cmds_doc,   15,80)
 331             self.print_topics(self.misc_header,  help.keys(),15,80)
 332             self.print_topics(self.undoc_header, cmds_undoc, 15,80)
 333
 334     def print_topics(self, header, cmds, cmdlen, maxcol):
 335         if cmds:
 336             self.stdout.write("%s\n"%str(header))
 337             if self.ruler:
 338                 self.stdout.write("%s\n"%str(self.ruler * len(header)))
 339             self.columnize(cmds, maxcol-1)
 340             self.stdout.write("\n")
 341
 342     def columnize(self, list, displaywidth=80):
 343         """Display a list of strings as a compact set of columns.
 344
 345         Each column is only as wide as necessary.
 346         Columns are separated by two spaces (one was not legible enough).
 347         """
 348         if not list:
 349             self.stdout.write("<empty>\n")
 350             return
 351         nonstrings = [i for i in range(len(list))
 352                         if not isinstance(list[i], str)]
 353         if nonstrings:
 354             raise TypeError, ("list[i] not a string for i in %s" %
 355                               ", ".join(map(str, nonstrings)))
 356         size = len(list)
 357         if size == 1:
 358             self.stdout.write('%s\n'%str(list[0]))
 359             return
 360         # Try every row count from 1 upwards
 361         for nrows in range(1, len(list)):
 362             ncols = (size+nrows-1) // nrows
 363             colwidths = []
 364             totwidth = -2
 365             for col in range(ncols):
 366                 colwidth = 0
 367                 for row in range(nrows):
 368                     i = row + nrows*col
 369                     if i >= size:
 370                         break
 371                     x = list[i]
 372                     colwidth = max(colwidth, len(x))
 373                 colwidths.append(colwidth)
 374                 totwidth += colwidth + 2
 375                 if totwidth > displaywidth:
 376                     break
 377             if totwidth <= displaywidth:
 378                 break
 379         else:
 380             nrows = len(list)
 381             ncols = 1
 382             colwidths = [0]
 383         for row in range(nrows):
 384             texts = []
 385             for col in range(ncols):
 386                 i = row + nrows*col
 387                 if i >= size:
 388                     x = ""
 389                 else:
 390                     x = list[i]
 391                 texts.append(x)
 392             while texts and not texts[-1]:
 393                 del texts[-1]
 394             for col in range(len(texts)):
 395                 texts[col] = texts[col].ljust(colwidths[col])
 396             self.stdout.write("%s\n"%str("  ".join(texts)))