diff options
| -rw-r--r-- | cmd2/cmd2.py | 72 | ||||
| -rw-r--r-- | docs/features/initialization.rst | 97 |
2 files changed, 133 insertions, 36 deletions
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 900a2451..648aadb1 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -272,9 +272,6 @@ class Cmd(cmd.Cmd): # Otherwise it will be None. Its used to know when a pipe process can be killed and/or waited upon. self._cur_pipe_proc_reader = None - # Used by complete() for readline tab completion - self.completion_matches = [] - # Used to keep track of whether we are redirecting or piping output self._redirecting = False @@ -321,6 +318,38 @@ class Cmd(cmd.Cmd): elif transcript_files: self._transcript_files = transcript_files + # Set the pager(s) for use with the ppaged() method for displaying output using a pager + if sys.platform.startswith('win'): + self.pager = self.pager_chop = 'more' + else: + # Here is the meaning of the various flags we are using with the less command: + # -S causes lines longer than the screen width to be chopped (truncated) rather than wrapped + # -R causes ANSI "style" escape sequences to be output in raw form (i.e. colors are displayed) + # -X disables sending the termcap initialization and deinitialization strings to the terminal + # -F causes less to automatically exit if the entire file can be displayed on the first screen + self.pager = 'less -RXF' + self.pager_chop = 'less -SRXF' + + # This boolean flag determines whether or not the cmd2 application can interact with the clipboard + self._can_clip = can_clip + + # This determines the value returned by cmdloop() when exiting the application + self.exit_code = 0 + + # This lock should be acquired before doing any asynchronous changes to the terminal to + # ensure the updates to the terminal don't interfere with the input being typed or output + # being printed by a command. + self.terminal_lock = threading.RLock() + + # Commands that have been disabled from use. This is to support commands that are only available + # during specific states of the application. This dictionary's keys are the command names and its + # values are DisabledCommand objects. + self.disabled_commands = dict() + + # If any command has been categorized, then all other commands that haven't been categorized + # will display under this section in the help output. + self.default_category = 'Uncategorized' + # The default key for sorting string results. Its default value performs a case-insensitive alphabetical sort. # If natural sorting is preferred, then set this to NATURAL_SORT_KEY. # cmd2 uses this key for sorting: @@ -331,7 +360,7 @@ class Cmd(cmd.Cmd): ############################################################################################################ # The following variables are used by tab-completion functions. They are reset each time complete() is run - # in reset_completion_defaults() and it is up to completer functions to set them before returning results. + # in _reset_completion_defaults() and it is up to completer functions to set them before returning results. ############################################################################################################ # If True and a single match is returned to complete(), then a space will be appended @@ -345,6 +374,9 @@ class Cmd(cmd.Cmd): # An optional header that prints above the tab-completion suggestions self.completion_header = '' + # Used by complete() for readline tab completion + self.completion_matches = [] + # Use this list if you are completing strings that contain a common delimiter and you only want to # display the final portion of the matches as the tab-completion suggestions. The full matches # still must be returned from your completer function. For an example, look at path_complete() @@ -360,38 +392,6 @@ class Cmd(cmd.Cmd): # If False, then complete() will sort the matches using self.default_sort_key before they are displayed. self.matches_sorted = False - # Set the pager(s) for use with the ppaged() method for displaying output using a pager - if sys.platform.startswith('win'): - self.pager = self.pager_chop = 'more' - else: - # Here is the meaning of the various flags we are using with the less command: - # -S causes lines longer than the screen width to be chopped (truncated) rather than wrapped - # -R causes ANSI "style" escape sequences to be output in raw form (i.e. colors are displayed) - # -X disables sending the termcap initialization and deinitialization strings to the terminal - # -F causes less to automatically exit if the entire file can be displayed on the first screen - self.pager = 'less -RXF' - self.pager_chop = 'less -SRXF' - - # This boolean flag determines whether or not the cmd2 application can interact with the clipboard - self._can_clip = can_clip - - # This determines the value returned by cmdloop() when exiting the application - self.exit_code = 0 - - # This lock should be acquired before doing any asynchronous changes to the terminal to - # ensure the updates to the terminal don't interfere with the input being typed or output - # being printed by a command. - self.terminal_lock = threading.RLock() - - # Commands that have been disabled from use. This is to support commands that are only available - # during specific states of the application. This dictionary's keys are the command names and its - # values are DisabledCommand objects. - self.disabled_commands = dict() - - # If any command has been categorized, then all other commands that haven't been categorized - # will display under this section in the help output. - self.default_category = 'Uncategorized' - # ----- Methods related to presenting output to the user ----- @property diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index cb111a39..0574c1c5 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -64,3 +64,100 @@ capabilities which you may wish to utilize while initializing the app:: if __name__ == '__main__': app = BasicApp() app.cmdloop() + + +Cmd class initializer +--------------------- + +A ``cmd2.Cmd`` instance or subclass instance is an interactive CLI application +framework. There is no good reason to instantiate ``Cmd`` itself; rather, it’s +useful as a superclass of a class you define yourself in order to inherit +``Cmd``’s methods and encapsulate action methods. + +Certain things must be initialized within the ``__init__()`` method of your +class derived from ``cmd2.Cmd``(all arguments to ``__init__()`` are optional): + +.. automethod:: cmd2.cmd2.Cmd.__init__ + :noindex: + +Cmd instance attributes +----------------------- + +The ``cmd2.Cmd`` class provides a large number of public instance attributes +which allow developers to customize a ``cmd2`` application further beyond the +options provided by the ``__init__()`` method. + +Common instance attributes to override +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Here are instance attributes of ``cmd2.Cmd`` which developers might wish +override: + +- **broken_pipe_warning**: if non-empty, this string will be displayed if a + broken pipe error occurs +- **continuation_prompt**: used for multiline commands on 2nd+ line of input +- **debug**: if ``True`` show full stack trace on error (Default: ``False``) +- **default_category**: if any command has been categorized, then all other + commands that haven't been categorized will display under this section in the + help output. +- **default_error**: the error that prints when a non-existent command is run +- **default_sort_key**: the default key for sorting string results. Its default + value performs a case-insensitive alphabetical sort. +- **default_to_shell**: if ``True`` attempt to run unrecognized commands as + shell commands (Default: ``False``) +- **disabled_commands**: commands that have been disabled from use. This is to + support commands that are only available during specific states of the + application. This dictionary's keys are the command names and its values are + DisabledCommand objects. +- **echo**: if ``True`` echo command issued into output (Default: ``False``) +- **editor**: text editor program to use with *edit* command (e.g. ``vim``) +- **exclude_from_history**: commands to exclude from the *history* command +- **exit_code**: this determines the value returned by ``cmdloop()`` when + exiting the application +- **feedback_to_output**: if ``True`` send nonessential output to stdout, if + ``False`` send them to stderr (Default: ``False``) +- **help_error**: the error that prints when no help information can be found +- **hidden_commands**: commands to exclude from the help menu and tab + completion +- **last_result**: stores results from the last command run to enable usage + of results in a Python script or interactive console. Built-in commands don't + make use of this. It is purely there for user-defined commands and + convenience. +- **locals_in_py**: if ``True`` allow access to your application in *py* + command via ``self`` (Default: ``False``) +- **macros**: dictionary of macro names and their values +- **max_completion_items**: max number of items to display during tab- + completion (Default: 50) +- **pager**: sets the pager command used by the ``Cmd.ppaged()`` method for + displaying wrapped output using a pager +- **pager_chop**: sets the pager command used by the ``Cmd.ppaged()`` method + for displaying chopped/truncated output using a pager +- **py_bridge_name**: name by which embedded Python environments and scripts + refer to the ``cmd2`` application by in order to call commands +- **py_locals**: dictionary that defines specific variables/functions available + in Python shells and scripts (provides more fine-grained control than making + everything available with **locals_in_py**) +- **quiet**: if ``True`` then completely suppress nonessential output (Default: + ``False``) +- **quit_on_sigint**: if ``True`` quit the main loop on interrupt instead of + just resetting prompt +- **settable**: dictionary that controls which of these instance attributes + are settable at runtime using the *set* command +- **timing**: if ``True`` display execution time for each command (Default: + ``False``) + +Rare instance attributes to override +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These instance attributes are used by built-in tab-completion functions. + +These instance attributes really are not intended for ``cmd2`` developers to +override, but they are there for unusual circumstances where it may be +necessary: + +- **sigint_protection**: context manager used to protect critical sections in + the main thread from stopping due to a KeyboardInterrupt +- **statement_parser**: object which parses all command line arguments (it + would be extremely rare to use something other than the default for this) +- **terminal_lock**: this lock should be acquired before doing any asynchronous + changes to the terminal to ensure the updates to the terminal don't interfere + with the input being typed or output being printed by a command. |