From afd75642be1fe8fc6b94d6ee82d5395ea78b0e84 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Wed, 29 Jan 2020 21:36:50 -0500 Subject: Updated docs on integrating with various operating system features --- docs/features/misc.rst | 24 ------------- docs/features/os.rst | 94 ++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 87 insertions(+), 31 deletions(-) (limited to 'docs/features') diff --git a/docs/features/misc.rst b/docs/features/misc.rst index 68a92b6a..aa791236 100644 --- a/docs/features/misc.rst +++ b/docs/features/misc.rst @@ -15,21 +15,6 @@ Exiting Mention quit, and EOF handling built into ``cmd2``. -Shell Command -------------- - -``cmd2`` includes a ``shell`` command which executes it's arguments in the -operating system shell:: - - (Cmd) shell ls -al - -If you use the default :ref:`features/shortcuts_aliases_macros:Shortcuts` -defined in ``cmd2`` you'll get a ``!`` shortcut for ``shell``, which allows you -to type:: - - (Cmd) !ls -al - - select ------ @@ -91,15 +76,6 @@ HelpCategories_ example for a demonstration. .. _HelpCategories: https://github.com/python-cmd2/cmd2/blob/master/examples/help_categories.py -Exit code ---------- - -The ``self.exit_code`` attribute of your ``cmd2`` application controls what -exit code is returned from ``cmdloop()`` when it completes. It is your job to -make sure that this exit code gets sent to the shell when your application -exits by calling ``sys.exit(app.cmdloop())``. - - Default to shell ---------------- diff --git a/docs/features/os.rst b/docs/features/os.rst index b6f9b61f..f042664c 100644 --- a/docs/features/os.rst +++ b/docs/features/os.rst @@ -1,14 +1,60 @@ Integrating with the OS ======================= -- how to redirect output -- executing OS commands from within ``cmd2`` -- editors -- paging -- exit codes -- Automation and calling cmd2 from other CLI/CLU tools via commands at - invocation and quit +How to redirect output +---------------------- +See :ref:`features/redirection:Output Redirection and Pipes` + +Executing OS commands from within ``cmd2`` +------------------------------------------ + +``cmd2`` includes a ``shell`` command which executes it's arguments in the +operating system shell:: + + (Cmd) shell ls -al + +If you use the default :ref:`features/shortcuts_aliases_macros:Shortcuts` +defined in ``cmd2`` you'll get a ``!`` shortcut for ``shell``, which allows you +to type:: + + (Cmd) !ls -al + + +Editors +------- + +``cmd2`` includes the built-in ``edit`` command which uns a text editor and +optionally open a file with it:: + + (Cmd) edit foo.txt + +The editor used is determined by the ``editor`` settable parameter and can +be either a text editor such as **vim** or a graphical editor such as +**VSCode**. To set it:: + + set editor + +If you have the ``EDITOR`` environment variable set, then this will be the +default value for ``editor``. If not, then ``cmd2`` will attempt to search +for any in a list of common editors for your operating system. + +Terminal pagers +--------------- + +Output of any command can be displayed one page at a time using the +:meth:`~.cmd2.Cmd.ppaged` method. + +Alternatively, a terminal pager can be invoked directly using the ability +to run shell commands with the ``!`` shortcut. + +Exit codes +---------- + +The ``self.exit_code`` attribute of your ``cmd2`` application controls what +exit code is returned from ``cmdloop()`` when it completes. It is your job to +make sure that this exit code gets sent to the shell when your application +exits by calling ``sys.exit(app.cmdloop())``. Invoking With Arguments ----------------------- @@ -84,3 +130,37 @@ your own argument parsing of the command line:: Check the source code of this example, especially the ``main()`` function, to see the technique. + +Alternatively you can simply wrap the command plus arguments in quotes (either +single or double quotes):: + + $ python example/example.py "speak -p hello there" + ellohay heretay + (Cmd) + +Automating cmd2 apps from other CLI/CLU tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While ``cmd2`` is designed to create **interactive** command-line applications +which enter a Read-Evaluate-Print-Loop (REPL), there are a great many times +when it would be useful to use a ``cmd2`` application as a run-and-done +command-line utility for purposes of automation and scripting. + +This is easily achieved by combining the following capabilities of ``cmd2``: +1. Ability to invoke a ``cmd2`` application with arguments +1. Ability to set an exit code when leaving a ``cmd2`` application +1. Ability to exit a ``cmd2`` application with the ``quit`` command + +Here is a simple example which doesn't require the quit command since the +custom ``exit`` command quits while returning an exit code:: + + $ python examples/exit_code.py "exit 23" + 'examples/exit_code.py' exiting with code: 23 + $ echo $? + 23 + +Here is another example using ``quit``:: + + $ python example/example.py "speak -p hello there" quit + ellohay heretay + $ -- cgit v1.2.1 From 074afad50320b984f81420954b4966c5a92a55d8 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Wed, 29 Jan 2020 22:06:15 -0500 Subject: Addressed PR comments --- docs/features/os.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'docs/features') diff --git a/docs/features/os.rst b/docs/features/os.rst index f042664c..d3e9b205 100644 --- a/docs/features/os.rst +++ b/docs/features/os.rst @@ -20,12 +20,15 @@ to type:: (Cmd) !ls -al +NOTE: That ``cmd2`` provides user-friendly tab-completion throughout the +process of running a shell command - first for the shell command name itself, +and then for file paths in the argument section. Editors ------- -``cmd2`` includes the built-in ``edit`` command which uns a text editor and -optionally open a file with it:: +``cmd2`` includes the built-in ``edit`` command which runs a text editor and +optionally opens a file with it:: (Cmd) edit foo.txt @@ -46,7 +49,14 @@ Output of any command can be displayed one page at a time using the :meth:`~.cmd2.Cmd.ppaged` method. Alternatively, a terminal pager can be invoked directly using the ability -to run shell commands with the ``!`` shortcut. +to run shell commands with the ``!`` shortcut like so:: + + (Cmd) !less foo.txt + +NOTE: Once you are in a terminal pager, that program temporarily has control +of your terminal, **NOT** ``cmd2``. Typically you can use either the arrow +keys or / keys to scroll around or type ``q`` to quit the +pager and return control to your ``cmd2`` application. Exit codes ---------- @@ -147,9 +157,10 @@ when it would be useful to use a ``cmd2`` application as a run-and-done command-line utility for purposes of automation and scripting. This is easily achieved by combining the following capabilities of ``cmd2``: -1. Ability to invoke a ``cmd2`` application with arguments -1. Ability to set an exit code when leaving a ``cmd2`` application -1. Ability to exit a ``cmd2`` application with the ``quit`` command + +#. Ability to invoke a ``cmd2`` application with arguments +#. Ability to set an exit code when leaving a ``cmd2`` application +#. Ability to exit a ``cmd2`` application with the ``quit`` command Here is a simple example which doesn't require the quit command since the custom ``exit`` command quits while returning an exit code:: -- cgit v1.2.1 From 322d46af90f16df3bccddbec98d3586251813609 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Wed, 29 Jan 2020 22:10:14 -0500 Subject: Minor grammar fix --- docs/features/os.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/features') diff --git a/docs/features/os.rst b/docs/features/os.rst index d3e9b205..07afc3cd 100644 --- a/docs/features/os.rst +++ b/docs/features/os.rst @@ -20,9 +20,9 @@ to type:: (Cmd) !ls -al -NOTE: That ``cmd2`` provides user-friendly tab-completion throughout the -process of running a shell command - first for the shell command name itself, -and then for file paths in the argument section. +NOTE: ``cmd2`` provides user-friendly tab-completion throughout the process of +running a shell command - first for the shell command name itself, and then for +file paths in the argument section. Editors ------- -- cgit v1.2.1