From c7eeeaa804822594dc2188def17b8e149dbd7a44 Mon Sep 17 00:00:00 2001 From: kotfu Date: Fri, 28 Feb 2020 18:22:25 -0700 Subject: Update scripting docs. Closes #765. --- docs/features/builtin_commands.rst | 9 +++++++++ docs/features/scripting.rst | 40 ++++++++++++++++++++++---------------- 2 files changed, 32 insertions(+), 17 deletions(-) (limited to 'docs/features') diff --git a/docs/features/builtin_commands.rst b/docs/features/builtin_commands.rst index 0db05c96..e08b5c24 100644 --- a/docs/features/builtin_commands.rst +++ b/docs/features/builtin_commands.rst @@ -83,6 +83,15 @@ This command runs commands in a script file that is encoded as either ASCII or UTF-8 text. See :ref:`features/scripting:Command Scripts` for more information. +_relative_run_script +~~~~~~~~~~~~~~~~~~~~ + +This command is hidden from the help that's visible to end users. It runs a +script like :ref:`features/builtin_commands:run_script` but does so using a +path relative to the script that is currently executing. This is useful when +you have scripts that run other scripts. See :ref:`features/scripting:Running +Command Scripts` for more information. + set ~~~ diff --git a/docs/features/scripting.rst b/docs/features/scripting.rst index 1128f5e1..efcb8261 100644 --- a/docs/features/scripting.rst +++ b/docs/features/scripting.rst @@ -21,9 +21,10 @@ Creating Command Scripts Command scripts can be created in several ways: - creating a text file using any method of your choice -- using the built-in ``edit`` command to create or edit an existing text file -- saving previously entered commands to a script file using ``history -s``. See - :ref:`features/history:History` for more details. +- using the built-in :ref:`features/builtin_commands:edit` command to + create or edit an existing text file +- saving previously entered commands to a script file using + :ref:`history -s ` If you create create a text file from scratch, just include one command per line, exactly as you would type it inside a ``cmd2`` application. @@ -32,11 +33,15 @@ line, exactly as you would type it inside a ``cmd2`` application. Running Command Scripts ~~~~~~~~~~~~~~~~~~~~~~~ -Command script files can be executed using the built-in ``run_script`` command -or ``@`` shortcut. Both ASCII and UTF-8 encoded unicode text files are -supported. The ``run_script`` command supports tab completion of file system -paths. There is a variant ``_relative_run_script`` command or ``@@`` -shortcut for use within a script which uses paths relative to the first script. +Command script files can be executed using the built-in +:ref:`features/builtin_commands:run_script` command or the ``@`` shortcut (if +your application is using the default shortcuts). Both ASCII and UTF-8 encoded +unicode text files are supported. The +:ref:`features/builtin_commands:run_script` command supports tab completion of +file system paths. There is a variant +:ref:`features/builtin_commands:_relative_run_script` command or ``@@`` +shortcut (if using the default shortcuts) for use within a script which uses +paths relative to the first script. Comments @@ -64,8 +69,8 @@ Python Scripts If you require logic flow, loops, branching, or other advanced features, you can write a python script which executes in the context of your ``cmd2`` app. -This script is run using the ``run_pyscript`` command. A simple example of -using ``run_pyscript`` is shown below along with the arg_printer_ script:: +This script is run using the :ref:`features/builtin_commands:run_pyscript` +command. Here's a simple example that uses the arg_printer_ script:: (Cmd) run_pyscript examples/scripts/arg_printer.py foo bar 'baz 23' Running Python script 'arg_printer.py' which was called with 3 arguments @@ -73,17 +78,18 @@ using ``run_pyscript`` is shown below along with the arg_printer_ script:: arg 2: 'bar' arg 3: 'baz 23' -``run_pyscript`` supports tab completion of file system paths, and as shown -above it has the ability to pass command-line arguments to the scripts invoked. +:ref:`features/builtin_commands:run_pyscript` supports tab completion of file +system paths, and as shown above it has the ability to pass command-line +arguments to the scripts invoked. -Python scripts executed with ``run_pyscript`` can run ``cmd2`` application -commands by using the syntax:: +Python scripts executed with :ref:`features/builtin_commands:run_pyscript` can +run ``cmd2`` application commands by using the syntax:: app(‘command args’) where: * ``app`` is a configurable name which can be changed by setting the - ``py_bridge_name`` attribute of your ``cmd2.Cmd`` class instance -* ``command`` and ``args`` are entered exactly like they would be entered on - the command line of your ``cmd2`` application + :data:`cmd2.Cmd.py_bridge_name` attribute +* ``command`` and ``args`` are entered exactly like they would be entered by + a user of your application. -- cgit v1.2.1