Coverage for /pythoncovmergedfiles/medio/medio/usr/lib/python3.9/cmd.py: 15%

1"""A generic class to build line-oriented command interpreters.

3Interpreters constructed with this class obey the following conventions:

51. End of file on input is processed as the command 'EOF'.

62. A command is parsed out of each line by collecting the prefix composed

7 of characters in the identchars member.

83. 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.

104. Typing an empty line repeats the last command. (Actually, it calls the

11 method `emptyline', which may be overridden in a subclass.)

125. 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.

166. The command '?' is a synonym for `help'. The command '!' is a synonym

17 for `shell', if a do_shell method exists.

187. 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.

26The `default' method may be overridden to intercept commands for which there

27is no do_ method.

29The `completedefault' method may be overridden to intercept completions for

30commands that have no complete_ method.

32The data member `self.ruler' sets the character used to draw separator lines

33in the help messages. If empty, no ruler line is drawn. It defaults to "=".

35If the value of `self.intro' is nonempty when the cmdloop method is called,

36it is printed out on interpreter startup. This value may be overridden

37via an optional argument to the cmdloop() method.

39The data members `self.doc_header', `self.misc_header', and

40`self.undoc_header' set the headers used for the help function's

41listings of documented functions, miscellaneous topics, and undocumented

42functions respectively.

43"""

45import string, sys

47__all__ = ["Cmd"]

49PROMPT = '(Cmd) '

50IDENTCHARS = string.ascii_letters + string.digits + '_'

52class Cmd:

53 """A simple framework for writing line-oriented command interpreters.

55 These are often useful for test harnesses, administrative tools, and

56 prototypes that will later be wrapped in a more sophisticated interface.

58 A Cmd instance or subclass instance is a line-oriented interpreter

59 framework. There is no good reason to instantiate Cmd itself; rather,

60 it's useful as a superclass of an interpreter class you define yourself

61 in order to inherit Cmd's methods and encapsulate action methods.

63 """

64 prompt = PROMPT

65 identchars = IDENTCHARS

66 ruler = '='

67 lastcmd = ''

68 intro = None

69 doc_leader = ""

70 doc_header = "Documented commands (type help <topic>):"

71 misc_header = "Miscellaneous help topics:"

72 undoc_header = "Undocumented commands:"

73 nohelp = "*** No help on %s"

74 use_rawinput = 1

76 def __init__(self, completekey='tab', stdin=None, stdout=None):

77 """Instantiate a line-oriented interpreter framework.

79 The optional argument 'completekey' is the readline name of a

80 completion key; it defaults to the Tab key. If completekey is

81 not None and the readline module is available, command completion

82 is done automatically. The optional arguments stdin and stdout

83 specify alternate input and output file objects; if not specified,

84 sys.stdin and sys.stdout are used.

86 """

87 if stdin is not None:

88 self.stdin = stdin

89 else:

90 self.stdin = sys.stdin

91 if stdout is not None:

92 self.stdout = stdout

93 else:

94 self.stdout = sys.stdout

95 self.cmdqueue = []

96 self.completekey = completekey

98 def cmdloop(self, intro=None):

99 """Repeatedly issue a prompt, accept input, parse an initial prefix

100 off the received input, and dispatch to action methods, passing them

101 the remainder of the line as argument.

102

103 """

104

105 self.preloop()

106 if self.use_rawinput and self.completekey:

107 try:

108 import readline

109 self.old_completer = readline.get_completer()

110 readline.set_completer(self.complete)

111 readline.parse_and_bind(self.completekey+": complete")

112 except ImportError:

113 pass

114 try:

115 if intro is not None:

116 self.intro = intro

117 if self.intro:

118 self.stdout.write(str(self.intro)+"\n")

119 stop = None

120 while not stop:

121 if self.cmdqueue:

122 line = self.cmdqueue.pop(0)

123 else:

124 if self.use_rawinput:

125 try:

126 line = input(self.prompt)

127 except EOFError:

128 line = 'EOF'

129 else:

130 self.stdout.write(self.prompt)

131 self.stdout.flush()

132 line = self.stdin.readline()

133 if not len(line):

134 line = 'EOF'

135 else:

136 line = line.rstrip('\r\n')

137 line = self.precmd(line)

138 stop = self.onecmd(line)

139 stop = self.postcmd(stop, line)

140 self.postloop()

141 finally:

142 if self.use_rawinput and self.completekey:

143 try:

144 import readline

145 readline.set_completer(self.old_completer)

146 except ImportError:

147 pass

148

149

150 def precmd(self, line):

151 """Hook method executed just before the command line is

152 interpreted, but after the input prompt is generated and issued.

153

154 """

155 return line

156

157 def postcmd(self, stop, line):

158 """Hook method executed just after a command dispatch is finished."""

159 return stop

160

161 def preloop(self):

162 """Hook method executed once when the cmdloop() method is called."""

163 pass

164

165 def postloop(self):

166 """Hook method executed once when the cmdloop() method is about to

167 return.

168

169 """

170 pass

171

172 def parseline(self, line):

173 """Parse the line into a command name and a string containing

174 the arguments. Returns a tuple containing (command, args, line).

175 'command' and 'args' may be None if the line couldn't be parsed.

176 """

177 line = line.strip()

178 if not line:

179 return None, None, line

180 elif line[0] == '?':

181 line = 'help ' + line[1:]

182 elif line[0] == '!':

183 if hasattr(self, 'do_shell'):

184 line = 'shell ' + line[1:]

185 else:

186 return None, None, line

187 i, n = 0, len(line)

188 while i < n and line[i] in self.identchars: i = i+1

189 cmd, arg = line[:i], line[i:].strip()

190 return cmd, arg, line

191

192 def onecmd(self, line):

193 """Interpret the argument as though it had been typed in response

194 to the prompt.

195

196 This may be overridden, but should not normally need to be;

197 see the precmd() and postcmd() methods for useful execution hooks.

198 The return value is a flag indicating whether interpretation of

199 commands by the interpreter should stop.

200

201 """

202 cmd, arg, line = self.parseline(line)

203 if not line:

204 return self.emptyline()

205 if cmd is None:

206 return self.default(line)

207 self.lastcmd = line

208 if line == 'EOF' :

209 self.lastcmd = ''

210 if cmd == '':

211 return self.default(line)

212 else:

213 try:

214 func = getattr(self, 'do_' + cmd)

215 except AttributeError:

216 return self.default(line)

217 return func(arg)

218

219 def emptyline(self):

220 """Called when an empty line is entered in response to the prompt.

221

222 If this method is not overridden, it repeats the last nonempty

223 command entered.

224

225 """

226 if self.lastcmd:

227 return self.onecmd(self.lastcmd)

228

229 def default(self, line):

230 """Called on an input line when the command prefix is not recognized.

231

232 If this method is not overridden, it prints an error message and

233 returns.

234

235 """

236 self.stdout.write('*** Unknown syntax: %s\n'%line)

237

238 def completedefault(self, *ignored):

239 """Method called to complete an input line when no command-specific

240 complete_*() method is available.

241

242 By default, it returns an empty list.

243

244 """

245 return []

246

247 def completenames(self, text, *ignored):

248 dotext = 'do_'+text

249 return [a[3:] for a in self.get_names() if a.startswith(dotext)]

250

251 def complete(self, text, state):

252 """Return the next possible completion for 'text'.

253

254 If a command has not been entered, then complete against command list.

255 Otherwise try to call complete_<command> to get list of completions.

256 """

257 if state == 0:

258 import readline

259 origline = readline.get_line_buffer()

260 line = origline.lstrip()

261 stripped = len(origline) - len(line)

262 begidx = readline.get_begidx() - stripped

263 endidx = readline.get_endidx() - stripped

264 if begidx>0:

265 cmd, args, foo = self.parseline(line)

266 if cmd == '':

267 compfunc = self.completedefault

268 else:

269 try:

270 compfunc = getattr(self, 'complete_' + cmd)

271 except AttributeError:

272 compfunc = self.completedefault

273 else:

274 compfunc = self.completenames

275 self.completion_matches = compfunc(text, line, begidx, endidx)

276 try:

277 return self.completion_matches[state]

278 except IndexError:

279 return None

280

281 def get_names(self):

282 # This method used to pull in base class attributes

283 # at a time dir() didn't do it yet.

284 return dir(self.__class__)

285

286 def complete_help(self, *args):

287 commands = set(self.completenames(*args))

288 topics = set(a[5:] for a in self.get_names()

289 if a.startswith('help_' + args[0]))

290 return list(commands | topics)

291

292 def do_help(self, arg):

293 'List available commands with "help" or detailed help with "help cmd".'

294 if arg:

295 # XXX check arg syntax

296 try:

297 func = getattr(self, 'help_' + arg)

298 except AttributeError:

299 try:

300 doc=getattr(self, 'do_' + arg).__doc__

301 if doc:

302 self.stdout.write("%s\n"%str(doc))

303 return

304 except AttributeError:

305 pass

306 self.stdout.write("%s\n"%str(self.nohelp % (arg,)))

307 return

308 func()

309 else:

310 names = self.get_names()

311 cmds_doc = []

312 cmds_undoc = []

313 help = {}

314 for name in names:

315 if name[:5] == 'help_':

316 help[name[5:]]=1

317 names.sort()

318 # There can be duplicates if routines overridden

319 prevname = ''

320 for name in names:

321 if name[:3] == 'do_':

322 if name == prevname:

323 continue

324 prevname = name

325 cmd=name[3:]

326 if cmd in help:

327 cmds_doc.append(cmd)

328 del help[cmd]

329 elif getattr(self, name).__doc__:

330 cmds_doc.append(cmd)

331 else:

332 cmds_undoc.append(cmd)

333 self.stdout.write("%s\n"%str(self.doc_leader))

334 self.print_topics(self.doc_header, cmds_doc, 15,80)

335 self.print_topics(self.misc_header, list(help.keys()),15,80)

336 self.print_topics(self.undoc_header, cmds_undoc, 15,80)

337

338 def print_topics(self, header, cmds, cmdlen, maxcol):

339 if cmds:

340 self.stdout.write("%s\n"%str(header))

341 if self.ruler:

342 self.stdout.write("%s\n"%str(self.ruler * len(header)))

343 self.columnize(cmds, maxcol-1)

344 self.stdout.write("\n")

345

346 def columnize(self, list, displaywidth=80):

347 """Display a list of strings as a compact set of columns.

348

349 Each column is only as wide as necessary.

350 Columns are separated by two spaces (one was not legible enough).

351 """

352 if not list:

353 self.stdout.write("<empty>\n")

354 return

355

356 nonstrings = [i for i in range(len(list))

357 if not isinstance(list[i], str)]

358 if nonstrings:

359 raise TypeError("list[i] not a string for i in %s"

360 % ", ".join(map(str, nonstrings)))

361 size = len(list)

362 if size == 1:

363 self.stdout.write('%s\n'%str(list[0]))

364 return

365 # Try every row count from 1 upwards

366 for nrows in range(1, len(list)):

367 ncols = (size+nrows-1) // nrows

368 colwidths = []

369 totwidth = -2

370 for col in range(ncols):

371 colwidth = 0

372 for row in range(nrows):

373 i = row + nrows*col

374 if i >= size:

375 break

376 x = list[i]

377 colwidth = max(colwidth, len(x))

378 colwidths.append(colwidth)

379 totwidth += colwidth + 2

380 if totwidth > displaywidth:

381 break

382 if totwidth <= displaywidth:

383 break

384 else:

385 nrows = len(list)

386 ncols = 1

387 colwidths = [0]

388 for row in range(nrows):

389 texts = []

390 for col in range(ncols):

391 i = row + nrows*col

392 if i >= size:

393 x = ""

394 else:

395 x = list[i]

396 texts.append(x)

397 while texts and not texts[-1]:

398 del texts[-1]

399 for col in range(len(texts)):

400 texts[col] = texts[col].ljust(colwidths[col])

401 self.stdout.write("%s\n"%str(" ".join(texts)))