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
  19 The `default' method may be overridden to intercept commands for which there
  20 is no do_ method.
  21
  22 The data member `self.ruler' sets the character used to draw separator lines
  23 in the help messages.  If empty, no ruler line is drawn.  It defaults to "=".
  24
  25 If the value of `self.intro' is nonempty when the cmdloop method is called,
  26 it is printed out on interpreter startup.  This value may be overridden
  27 via an optional argument to the cmdloop() method.
  28
  29 The data members `self.doc_header', `self.misc_header', and
  30 `self.undoc_header' set the headers used for the help function's
  31 listings of documented functions, miscellaneous topics, and undocumented
  32 functions respectively.
  33
  34 These interpreters use raw_input; thus, if the readline module is loaded,
  35 they automatically support Emacs-like command history and editing features.
  36 """
  37
  38 import string, sys
  39
  40 __all__ = ["Cmd"]
  41
  42 PROMPT = '(Cmd) '
  43 IDENTCHARS = string.letters + string.digits + '_'
  44
  45 class Cmd:
  46     prompt = PROMPT
  47     identchars = IDENTCHARS
  48     ruler = '='
  49     lastcmd = ''
  50     cmdqueue = []
  51     intro = None
  52     doc_leader = ""
  53     doc_header = "Documented commands (type help <topic>):"
  54     misc_header = "Miscellaneous help topics:"
  55     undoc_header = "Undocumented commands:"
  56     nohelp = "*** No help on %s"
  57     use_rawinput = 1
  58
  59     def __init__(self): pass
  60
  61     def cmdloop(self, intro=None):
  62         self.preloop()
  63         if intro is not None:
  64             self.intro = intro
  65         if self.intro:
  66             print self.intro
  67         stop = None
  68         while not stop:
  69             if self.cmdqueue:
  70                 line = self.cmdqueue[0]
  71                 del self.cmdqueue[0]
  72             else:
  73                 if self.use_rawinput:
  74                     try:
  75                         line = raw_input(self.prompt)
  76                     except EOFError:
  77                         line = 'EOF'
  78                 else:
  79                     sys.stdout.write(self.prompt)
  80                     line = sys.stdin.readline()
  81                     if not len(line):
  82                         line = 'EOF'
  83                     else:
  84                         line = line[:-1] # chop \n
  85             line = self.precmd(line)
  86             stop = self.onecmd(line)
  87             stop = self.postcmd(stop, line)
  88         self.postloop()
  89
  90     def precmd(self, line):
  91         return line
  92
  93     def postcmd(self, stop, line):
  94         return stop
  95
  96     def preloop(self):
  97         pass
  98
  99     def postloop(self):
 100         pass
 101
 102     def onecmd(self, line):
 103         line = line.strip()
 104         if not line:
 105             return self.emptyline()
 106         elif line[0] == '?':
 107             line = 'help ' + line[1:]
 108         elif line[0] == '!':
 109             if hasattr(self, 'do_shell'):
 110                 line = 'shell ' + line[1:]
 111             else:
 112                 return self.default(line)
 113         self.lastcmd = line
 114         i, n = 0, len(line)
 115         while i < n and line[i] in self.identchars: i = i+1
 116         cmd, arg = line[:i], line[i:].strip()
 117         if cmd == '':
 118             return self.default(line)
 119         else:
 120             try:
 121                 func = getattr(self, 'do_' + cmd)
 122             except AttributeError:
 123                 return self.default(line)
 124             return func(arg)
 125
 126     def emptyline(self):
 127         if self.lastcmd:
 128             return self.onecmd(self.lastcmd)
 129
 130     def default(self, line):
 131         print '*** Unknown syntax:', line
 132
 133     def do_help(self, arg):
 134         if arg:
 135             # XXX check arg syntax
 136             try:
 137                 func = getattr(self, 'help_' + arg)
 138             except:
 139                 try:
 140                     doc=getattr(self, 'do_' + arg).__doc__
 141                     if doc:
 142                         print doc
 143                         return
 144                 except:
 145                     pass
 146                 print self.nohelp % (arg,)
 147                 return
 148             func()
 149         else:
 150             # Inheritance says we have to look in class and
 151             # base classes; order is not important.
 152             names = []
 153             classes = [self.__class__]
 154             while classes:
 155                 aclass = classes[0]
 156                 if aclass.__bases__:
 157                     classes = classes + list(aclass.__bases__)
 158                 names = names + dir(aclass)
 159                 del classes[0]
 160             cmds_doc = []
 161             cmds_undoc = []
 162             help = {}
 163             for name in names:
 164                 if name[:5] == 'help_':
 165                     help[name[5:]]=1
 166             names.sort()
 167             # There can be duplicates if routines overridden
 168             prevname = ''
 169             for name in names:
 170                 if name[:3] == 'do_':
 171                     if name == prevname:
 172                         continue
 173                     prevname = name
 174                     cmd=name[3:]
 175                     if help.has_key(cmd):
 176                         cmds_doc.append(cmd)
 177                         del help[cmd]
 178                     elif getattr(self, name).__doc__:
 179                         cmds_doc.append(cmd)
 180                     else:
 181                         cmds_undoc.append(cmd)
 182             print self.doc_leader
 183             self.print_topics(self.doc_header,   cmds_doc,   15,80)
 184             self.print_topics(self.misc_header,  help.keys(),15,80)
 185             self.print_topics(self.undoc_header, cmds_undoc, 15,80)
 186
 187     def print_topics(self, header, cmds, cmdlen, maxcol):
 188         if cmds:
 189             print header
 190             if self.ruler:
 191                 print self.ruler * len(header)
 192             (cmds_per_line,junk)=divmod(maxcol,cmdlen)
 193             col=cmds_per_line
 194             for cmd in cmds:
 195                 if col==0: print
 196                 print (("%-"+`cmdlen`+"s") % cmd),
 197                 col = (col+1) % cmds_per_line
 198             print "\n"