Skip to content

Commit

Permalink
Improved some comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@tleonhardt
tleonhardt committed Feb 12, 2017
1 parent 67c9cf7 commit d15fd10
Showing 1 changed file with 95 additions and 48 deletions.
143 changes: 95 additions & 48 deletions cmd2.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -586,7 +586,7 @@ def __init__(self, *args, **kwargs):
self._temp_filename = None

def poutput(self, msg):
'''Convenient shortcut for self.stdout.write(); adds newline if necessary.'''
"""Convenient shortcut for self.stdout.write(); adds newline if necessary."""
if msg:
self.stdout.write(msg)
if msg[-1] != '\n':
Expand Down Expand Up @@ -624,18 +624,18 @@ def pfeedback(self, msg):
print(msg)

def colorize(self, val, color):
'''Given a string (``val``), returns that string wrapped in UNIX-style
"""Given a string (``val``), returns that string wrapped in UNIX-style
special characters that turn on (and then off) text color and style.
If the ``colors`` environment paramter is ``False``, or the application
is running on Windows, will return ``val`` unchanged.
``color`` should be one of the supported strings (or styles):
red/blue/green/cyan/magenta, bold, underline'''
red/blue/green/cyan/magenta, bold, underline"""
if self.colors and (self.stdout == self.initial_stdout):
return self.colorcodes[color][True] + val + self.colorcodes[color][False]
return val

def do_cmdenvironment(self, args):
'''Summary report of interactive parameters.'''
"""Summary report of interactive parameters."""
self.stdout.write("""
Commands are %(casesensitive)scase-sensitive.
Commands may be terminated with: %(terminators)s
Expand All @@ -646,7 +646,7 @@ def do_cmdenvironment(self, args):
})

def do_help(self, arg):
'''List available commands with "help" or detailed help with "help cmd".'''
"""List available commands with "help" or detailed help with "help cmd"."""
if arg:
funcname = self.func_named(arg)
if funcname:
Expand Down Expand Up @@ -1166,7 +1166,7 @@ def do_quit(self, arg):
return self._STOP_AND_EXIT

def select(self, options, prompt='Your choice? '):
'''Presents a numbered menu to the user. Modelled after
"""Presents a numbered menu to the user. Modelled after
the bash shell's SELECT. Returns the item chosen.
Argument ``options`` can be:
Expand All @@ -1175,7 +1175,7 @@ def select(self, options, prompt='Your choice? '):
| a list of strings -> will be offered as options
| a list of tuples -> interpreted as (value, text), so
that the return value can differ from
the text advertised to the user '''
the text advertised to the user """
local_opts = options
if isinstance(options, string_types):
local_opts = list(zip(options.split(), options.split()))
Expand Down Expand Up @@ -1257,13 +1257,28 @@ def do_set(self, arg):
except (ValueError, AttributeError, NotSettableError) as e:
self.do_show(arg)

def do_pause(self, arg):
'Displays the specified text then waits for the user to press RETURN.'
sm.input(arg + '\n')
def do_pause(self, text):
"""Displays the specified text then waits for the user to press <Enter>.
Usage: pause [text]
optional arguments:
text Text to display to the user
default: blank line
"""
sm.input(text + '\n')

def do_shell(self, arg):
'execute a command as if at the OS prompt.'
os.system(arg)
def do_shell(self, cmd):
"""Execute a command as if at the OS prompt.
Usage: shell cmd
positional argument:
cmd shell command to execute
NOTE: `!` is a shortcut for this command.
"""
os.system(cmd)

def do_py(self, arg):
'''
Expand Down Expand Up @@ -1353,11 +1368,11 @@ def last_matching(self, arg):
def do_list(self, arg):
"""list [arg]: lists last command issued
no arg -> list most recent command
arg is integer -> list one history item, by index
a..b, a:b, a:, ..b -> list spans from a (or start) to b (or end)
arg is string -> list all commands matching string search
arg is /enclosed in forward-slashes/ -> regular expression search
no arg -> list most recent command
arg is integer -> list one history item, by index
a..b, a:b, a:, ..b -> list spans from a (or start) to b (or end)
arg is string -> list all commands matching string search
arg is /enclosed in forward-slashes/ -> regular expression search
"""
try:
history = self.history.span(arg or '-1')
Expand All @@ -1367,13 +1382,25 @@ def do_list(self, arg):
self.poutput(hi.pr())

def do_edit(self, arg):
"""edit: edit most recent command in text editor
ed [N]: edit numbered command from history
ed [filename]: edit specified file name
commands are run after editor is closed.
"set edit (program-name)" or set EDITOR environment variable
to control which editing program is used."""
"""Edit a file or command in a text editor.
Usage: edit [N]|[file_path]
optional arguments:
N Number of command (from history), or `*` for all commands in history
default: most recent command
file_path path to a file to open in editor
The editor used is determined by the `editor` settable parameter.
"set editor (program-name" to change or set the EDITOR environment variable.
The optional arguments are mutually exclusive. Either a command number OR a file name can be supplied.
If neither is supplied, the most recent command in the history is edited.
Edited commands are always run after the editor is closed.
Edited files are run on close if the `autorun_on_edit` settable parameter is True.
"""
if not self.editor:
raise EnvironmentError("Please use 'set editor' to specify your text editing program of choice.")
filename = self.default_file_name
Expand All @@ -1397,12 +1424,16 @@ def do_edit(self, arg):
self.do_load(filename)

def do_save(self, arg):
"""`save [N] [filename.ext]`
Saves command from history to file.
| N => Number of command (from history), or `*`;
| most recent command if omitted"""
"""Saves command(s) from history to file.
Usage: save [N] [file_path]
optional arguments:
N Number of command (from history), or `*` for all commands in history
default: most recent command
file_path location to save script of command(s) to
default: value stored in `default_file_name` settable param
"""

try:
args = self.saveparser.parseString(arg)
Expand Down Expand Up @@ -1444,30 +1475,46 @@ def read_file_or_url(self, fname):
return result

def do__relative_load(self, arg=None):
'''
Runs commands in script at file or URL; if this is called from within an
already-running script, the filename will be interpreted relative to the
already-running script's directory.'''
"""Runs commands in script at file or URL.
Usage: load [file_path]
optional argument:
file_path a file path or URL pointing to a script
default: value stored in `default_file_name` settable param
Script should contain one command per line, just like command would be typed in console.
If this is called from within an already-running script, the filename will be interpreted
relative to the already-running script's directory.
NOTE: `@@` is a shortcut for this command.
"""
if arg:
arg = arg.split(None, 1)
targetname, args = arg[0], (arg[1:] or [''])[0]
targetname = os.path.join(self.current_script_dir or '', targetname)
self.do_load('%s %s' % (targetname, args))

def do_load(self, arg=None):
"""Runs script of command(s) from a file or URL.
Script should contain one command per line, just like command would be typed in console.
def do_load(self, file_path=None):
"""Runs commands in script at file or URL.
:param arg: str - Path of file to load and run commands from.
:return: bool - True if application should stop (script contained 'quit', typically False to continue running.
Usage: load [file_path]
optional argument:
file_path a file path or URL pointing to a script
default: value stored in `default_file_name` settable param
Script should contain one command per line, just like command would be typed in console.
NOTE: `@` is a shortcut for this command.
"""
# If arg is None or arg is an empty string, use the default filename
if not arg:
if not file_path:
targetname = self.default_file_name
else:
arg = arg.split(None, 1)
targetname, args = arg[0], (arg[1:] or [''])[0].strip()
file_path = file_path.split(None, 1)
targetname, args = file_path[0], (file_path[1:] or [''])[0].strip()
try:
target = self.read_file_or_url(targetname)
except IOError as e:
Expand All @@ -1488,10 +1535,10 @@ def do_load(self, arg=None):
def do_run(self, arg):
"""run [arg]: re-runs an earlier command
no arg -> run most recent command
arg is integer -> run one history item, by index
arg is string -> run most recent command by string search
arg is /enclosed in forward-slashes/ -> run most recent by regex
no arg -> run most recent command
arg is integer -> run one history item, by index
arg is string -> run most recent command by string search
arg is /enclosed in forward-slashes/ -> run most recent by regex
"""
'run [N]: runs the SQL that was run N commands ago'
runme = self.last_matching(arg)
Expand Down

0 comments on commit d15fd10

Please sign in to comment.