cmd2nest module

Command parser, extending cmd, cmd2 to nested sub-commands etc.

usage:Usage: import cmd2nest, subclass Cmd, TopCmd & SubCmd and use like cmd(2).

Module author: Michael Chapman <chapmami@ohsu.edu>

Authors:

Michael S. Chapman <chapmami@ohsu.edu>

Oregon Health & Science University

Version:

0.5, March 23, 2016

Cmd should be subclassed and extended with methods to be available at all command nesting levels. Example: ProgCmd.

TopCmd should be subclassed and extended with methods to be available only at the top level. Example ProgTopCmd.

SubCmd should be subclassed and extended for each nesting of sub-commands. Example ProgSubCmd.

Changed in version 06/05/13: relative to cmd2:

• Supports nested command structure (subcommands).
• Calling program objects can be added into the namespace for py commands.
• Help options added for verbosity & scope (command to whole program).
• Interpretation of commands entered on the program command line is now compatible with main programs use of argparse, optparse or no parser. (Internal workings of cmd2 still dependent on optparse.)

Changed in version 05/04/13: relative to cmd_extensions: upgrade to cmd2; nested commands.

Changed in version 8/13/10: start

Note

cmd2 may have an undocumented requirement that loaded files (including initial_commands) end with an EOF command. A work-around is implemented, adding an EOF if not in the last line.

class cmd2nest.Cmd(tasks, prompt=None, initial_commands=None, py_locals={'my': None}, register=True, parser=None)

Bases: cmd2.Cmd

Parser for terminal command input.

Processes commands from initial_commands, then command-line, then stdin.

This should be sub-classed, adding do_* and help_* methods. For multi-level command structures, subclasses of Cmd should contain only methods accessible at all levels, using sub-classes of TopCmd and SubCmd to restrict availability.

Shell that merely invokes task methods from a corresponding Control class. (Separation of the parser from the methods should facilitate alternative user-control interfaces.)

Changed in version relative: to cmd_extensions, a number of commands are deprecated:

• exec <command> & EXEC <command> are replaced by py <command>. There are currently no plans to support the global namespace of EXEC, but haven’t needed it.
• cmd_file <FILE> is replaced by load <FILE>, @<FILE> etc.
• echo <comment> is replaced by py print “comment” or # comment

Note

no attempt is made to import ‘option’ into namespace for py commands. Other objects will need py from module import object before using them.

Todo

(possibly) mechanism to automatically import other objects.

Todo

make sure that there is a way of modifing atom attributes.

Todo

refactored do_test when I have an example to play with.

Warning

cmd2 does not provide a means of escaping special symbols within arguments or options. Function unquote allows the rest of the command line (following options) to be enclosed in quotes - so partial support.

Changed in version ?: echo’s default is changed to True if not terminal-bound output i.e. redirected to log (but does not work within eclipse IDE).

Parameters:

• tasks (Control) – class instance that defines methods to be called. (Reference will also be bound to ‘my’, so that ‘py’ commands can reference tasks.attribute as my.attribute rather than self.task.attribute.)
• prompt (str or NoneType) – defaults to program basename.
• initial_commands (str or list of str) – file(s) of commands to run before interactive loop at the top level, and before any command-line commands.
• py_locals (dict) – objects added to the local namespace in the python interpreter invoked by ‘py’ commands.
• register (bool) – keep object reference for setting of global parameters.
• parser (ArgumentParser (argparse) or OptionParser (optparse)) – to which -t / –test option will be added for cmd2 regression testing. Should only be used once / program.

ancestory(include_self=True)

Iterator that climbs through parentage, returning Cmd objects.

base_keywords = ['EOF', '_load', '_relative_load', 'cmdenvironment', 'ed', 'edit', 'eof', 'exit', 'help', 'hi', 'history', 'l', 'li', 'list', 'load', 'parrot', 'pause', 'py', 'q', 'quit', 'r', 'run', 'save', 'set', 'shell', 'shortcuts', 'show', 'test']

Var:keywords defined at top or default level (not SubCmd).

children = None

Var:SubCommand instances called from this object.

cmdloop()

do__load(arg=None)

Runs script of command(s) from a file or URL.

do_help(instance, arg)

Document command or list available commands. Usage: help [options] [command]

Options:

-h, --help	show this help message and exit
-a, --all	Include commands inherited from higher levels. (Combining -a -r will be excessively repetitious.)
-l, --long	Fully document all commands.
-r, --recursive
	Descend through nested command sets.

do_load(arg=None)

Runs script of command(s) from a file or URL.

do_parrot(arg)

parrot [T[rue]|F[alse]|Y[es]|N[o]]: toggle or set command echoing (for log file).

do_set(arg)

Sets named Cmd parameter or lists all; unambiguous abbreviations OK.

do_test(arg)

test [<name>]: run test (developers only)

instances = []

Var:list of instances (for setting global attributes).

onfailure(cmd)

Attempt at learning how to trap exceptions, but not working.

parent = None

Var:Command instance from which this instance created. None for top level.

postloop()

Hook method executed once when the cmdloop() method is about to return.

preloop()

Run at start of cmdloop().

Warning

self.initial_commands set to None to avoid recursive call.

Changed in version ?: new implementation relative to cmd2 to be polymorphic for initial_commands open file(s) or file name(s).

Changed in version ?: relative to cmd2, adds EOF command at end if absent.

undocumented = ('EOF', 'eof', 'exit', 'q', 'quit', 'test')

class cmd2nest.Documentation

Bases: object

User-level documentation for imports.

general

Generic documentation for import into other modules.

class cmd2nest.ProgCmd(tasks, initial_commands=None, py_locals={})

Bases: cmd2nest.Cmd

Commands available at all levels for Program Prog.

Processes commands from initial_commands, then command-line, then stdin.

Parameters:

• tasks (Control) – class instance that defines methods to be called.
• initial_commands (str or list of str) – file(s) of commands to run before interactive loop at the top level, and before any command-line commands.
• py_locals (dict) – objects added to the local namespace in the python interpreter invoked by ‘py’ commands.

class cmd2nest.ProgSubCmd(parent, prompt='sub-command')

Bases: cmd2nest.SubCmd, cmd2nest.ProgCmd

Parameters:

• parent (TopCmd) – Cmd object whence this call was made, usually self.
• prompt (str) – concatonated with the parent’s prompt.

do_callee(arg)

Call a sub-command.

help_callee()

class cmd2nest.ProgTopCmd(tasks, initial_commands=None, py_locals={}, parser=None)

Bases: cmd2nest.TopCmd, cmd2nest.ProgCmd

Top-level commands for Program Prog.

Parameters:

• tasks (Control) – class instance that defines methods to be called.
• initial_commands (str or list of str) – file(s) of commands to run before interactive loop at the top level, and before any command-line commands.
• py_locals (dict) – objects added to the local namespace in the python interpreter invoked by ‘py’ commands.
• parser (ArgumentParser (argparse) or OptionParser (optparse)) – to which -t / –test option will be added for cmd2 regression testing. Should only be used once / program.

do_caller(arg)

Call a sub-command object.

help_caller()

class cmd2nest.SubCmd(parent, prompt='sub-command')

Bases: cmd2nest.Cmd

Parser for sub-menu terminal command input.

Programs should sub-class SubComands, adding do_* and help_* methods for each cascading level of commands.

Todo

Inheritance of “state”. How to get from parent? Should changes of state be mirrored back up to parent?

Parameters:

• parent (TopCmd) – Cmd object whence call is being made, usually self.
• prompt (str) – concatonated with the parent’s prompt.

do_done(arg)

Safe sub-menu exit, returning to higher level command.

class cmd2nest.TestControl(option=None)

Bases: object

class cmd2nest.TopCmd(tasks, initial_commands=None, py_locals={}, parser=None)

Bases: cmd2nest.Cmd

Parser for top-level terminal command input.

Processes commands from initial_commands, then command-line, then stdin.

For multi-level commands structure, programs should sub-class Cmd, TopCmd and SubCmd. To a TopCmd sub-class do_* and help_* methods should be added for tasks available only at the top level. The program should then instantiate TopCmd and not Cmd.

Parameters:

• tasks (Control) – class instance that defines methods to be called.
• initial_commands (str or list of str) – file(s) of commands to run before interactive loop at the top level, and before any command-line commands.
• py_locals (dict) – objects added to the local namespace in the python interpreter invoked by ‘py’ commands.
• parser (ArgumentParser (argparse) or OptionParser (optparse)) – to which -t / –test option will be added for cmd2 regression testing. Should only be used once / program.

cmd2nest.unquote(text)

Strip paired single or double quotes from ends of string.

Do nothing if not string or not quoted.