diff options
Diffstat (limited to 'docs/freefeatures.rst')
| -rw-r--r-- | docs/freefeatures.rst | 186 |
1 files changed, 0 insertions, 186 deletions
diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index 25fe3be9..cb693be8 100644 --- a/docs/freefeatures.rst +++ b/docs/freefeatures.rst @@ -76,174 +76,6 @@ quotation marks if it is more than a one-word command. .. _output_redirection: -Output redirection -================== - -As in a Unix shell, output of a command can be redirected: - - - sent to a file with ``>``, as in ``mycommand args > filename.txt`` - - appended to a file with ``>>``, as in ``mycommand args >> filename.txt`` - - piped (``|``) as input to operating-system commands, as in - ``mycommand args | wc`` - - sent to the operating system paste buffer, by ending with a bare ``>``, as - in ``mycommand args >``. You can even append output to the current contents - of the paste buffer by ending your command with ``>>``. - - -.. note:: - - If you wish to disable cmd2's output redirection and pipes features, you can - do so by setting the ``allow_redirection`` attribute of your ``cmd2.Cmd`` - class instance to ``False``. This would be useful, for example, if you want - to restrict the ability for an end user to write to disk or interact with - shell commands for security reasons:: - - from cmd2 import Cmd - class App(Cmd): - def __init__(self): - self.allow_redirection = False - - cmd2's parser will still treat the ``>``, ``>>``, and `|` symbols as output - redirection and pipe symbols and will strip arguments after them from the - command line arguments accordingly. But output from a command will not be - redirected to a file or piped to a shell command. - -If you need to include any of these redirection characters in your command, you -can enclose them in quotation marks, ``mycommand 'with > in the argument'``. - -Python -====== - -The ``py`` command will run its arguments as a Python command. Entered without -arguments, it enters an interactive Python session. The session can call -"back" to your application through the name defined in ``self.pyscript_name`` -(defaults to ``app``). This wrapper provides access to execute commands in -your cmd2 application while maintaining isolation. - -You may optionally enable full access to to your application by setting -``locals_in_py`` to ``True``. Enabling this flag adds ``self`` to the python -session, which is a reference to your Cmd2 application. This can be useful for -debugging your application. To prevent users from enabling this ability -manually you'll need to remove ``locals_in_py`` from the ``settable`` -dictionary. - -The ``app`` object (or your custom name) provides access to application -commands through raw commands. For example, any application command call be -called with ``app("<command>")``. - -:: - - >>> app('say --piglatin Blah') - lahBay - -More Python examples: - -:: - - (Cmd) py print("-".join("spelling")) - s-p-e-l-l-i-n-g - (Cmd) py - Python 3.5.3 (default, Jan 19 2017, 14:11:04) - [GCC 6.3.0 20170118] on linux - Type "help", "copyright", "credits" or "license" for more information. - (CmdLineApp) - - End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, `exit()`. - Non-python commands can be issued with: app("your command") - Run python code from external script files with: run("script.py") - - >>> import os - >>> os.uname() - ('Linux', 'eee', '2.6.31-19-generic', '#56-Ubuntu SMP Thu Jan 28 01:26:53 UTC 2010', 'i686') - >>> app("say --piglatin {os}".format(os=os.uname()[0])) - inuxLay - >>> self.prompt - '(Cmd) ' - >>> self.prompt = 'Python was here > ' - >>> quit() - Python was here > - -Using the ``py`` command is tightly integrated with your main ``cmd2`` -application and any variables created or changed will persist for the life of -the application:: - - (Cmd) py x = 5 - (Cmd) py print(x) - 5 - -The ``py`` command also allows you to run Python scripts via ``py -run('myscript.py')``. This provides a more complicated and more powerful -scripting capability than that provided by the simple text file scripts -discussed in :ref:`scripts`. Python scripts can include conditional control -flow logic. See the **python_scripting.py** ``cmd2`` application and the -**script_conditional.py** script in the ``examples`` source code directory for -an example of how to achieve this in your own applications. - -Using ``py`` to run scripts directly is considered deprecated. The newer -``run_pyscript`` command is superior for doing this in two primary ways: - -- it supports tab-completion of file system paths -- it has the ability to pass command-line arguments to the scripts invoked - -There are no disadvantages to using ``run_pyscript`` as opposed to ``py -run()``. A simple example of using ``run_pyscript`` is shown below along with -the arg_printer_ script:: - - (Cmd) run_pyscript examples/scripts/arg_printer.py foo bar baz - Running Python script 'arg_printer.py' which was called with 3 arguments - arg 1: 'foo' - arg 2: 'bar' - arg 3: 'baz' - -.. note:: - - If you want to be able to pass arguments with spaces to commands, then we - strongly recommend using one of the decorators, such as - ``with_argument_list``. ``cmd2`` will pass your **do_*** methods a list of - arguments in this case. - - When using this decorator, you can then put arguments in quotes like so:: - - $ examples/arg_print.py - (Cmd) lprint foo "bar baz" - lprint was called with the following list of arguments: ['foo', 'bar baz'] - -.. _arg_printer: - https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/arg_printer.py - - -IPython (optional) -================== - -**If** IPython_ is installed on the system **and** the ``cmd2.Cmd`` class is -instantiated with ``use_ipython=True``, then the optional ``ipy`` command will -be present:: - - from cmd2 import Cmd - class App(Cmd): - def __init__(self): - Cmd.__init__(self, use_ipython=True) - -The ``ipy`` command enters an interactive IPython_ session. Similar to an -interactive Python session, this shell can access your application instance via -``self`` and any changes to your application made via ``self`` will persist. -However, any local or global variable created within the ``ipy`` shell will not -persist. Within the ``ipy`` shell, you cannot call "back" to your application -with ``cmd("")``, however you can run commands directly like so:: - - self.onecmd_plus_hooks('help') - -IPython_ provides many advantages, including: - - * Comprehensive object introspection - * Get help on objects with ``?`` - * Extensible tab completion, with support by default for completion of - python variables and keywords - -The object introspection and tab completion make IPython particularly efficient -for debugging as well as for interactive experimentation and data analysis. - -.. _IPython: http://ipython.readthedocs.io Quitting the application @@ -268,24 +100,6 @@ with automatically included ``do_`` methods. ( ``!`` is a shortcut for ``shell``; thus ``!ls`` is equivalent to ``shell ls``.) -Transcript-based testing -======================== - -A transcript is both the input and output of a successful session of a -``cmd2``-based app which is saved to a text file. The transcript can be played -back into the app as a unit test. - -.. code-block:: text - - $ python example.py --test transcript_regex.txt - . - ---------------------------------------------------------------------- - Ran 1 test in 0.013s - - OK - -See :doc:`features/transcripts` for more details. - Tab-Completion ============== |