diff options
| -rw-r--r-- | docs/features/misc.rst | 43 | ||||
| -rw-r--r-- | docs/features/settings.rst | 62 | ||||
| -rw-r--r-- | docs/features/shortcuts_aliases_macros.rst | 82 | ||||
| -rw-r--r-- | docs/index.rst | 15 | ||||
| -rw-r--r-- | docs/settingchanges.rst | 194 |
5 files changed, 187 insertions, 209 deletions
diff --git a/docs/features/misc.rst b/docs/features/misc.rst index 0ddc03e1..92ab7537 100644 --- a/docs/features/misc.rst +++ b/docs/features/misc.rst @@ -147,3 +147,46 @@ 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 +---------------- + +Every ``cmd2`` application can execute operating-system level (shell) commands +with ``shell`` or a ``!`` shortcut:: + + (Cmd) shell which python + /usr/bin/python + (Cmd) !which python + /usr/bin/python + +However, if the parameter ``default_to_shell`` is ``True``, then *every* +command will be attempted on the operating system. Only if that attempt fails +(i.e., produces a nonzero return value) will the application's own ``default`` +method be called. + +:: + + (Cmd) which python + /usr/bin/python + (Cmd) my dog has fleas + sh: my: not found + *** Unknown syntax: my dog has fleas + + +Quit on SIGINT +-------------- + +On many shells, SIGINT (most often triggered by the user pressing Ctrl+C) only +cancels the current line, not the entire command loop. By default, a ``cmd2`` +application will quit on receiving this signal. However, if ``quit_on_sigint`` +is set to ``False``, then the current line will simply be cancelled. + +:: + + (Cmd) typing a comma^C + (Cmd) + +.. warning:: + The default SIGINT behavior will only function properly if **cmdloop** is running + in the main thread. diff --git a/docs/features/settings.rst b/docs/features/settings.rst index 27730572..21d5a9ee 100644 --- a/docs/features/settings.rst +++ b/docs/features/settings.rst @@ -5,6 +5,68 @@ Settings - how a developer can add their own - how to hide built in settings from a user +Built In Settings +----------------- + +``cmd2`` has a number of built in settings, which a developer can set a default +value, and which users can modify to change the behavior of the application. + + +Timing +~~~~~~ + +Setting ``App.timing`` to ``True`` outputs timing data after every application +command is executed. |settable| + + +Echo +~~~~ + +If ``True``, each command the user issues will be repeated to the screen before +it is executed. This is particularly useful when running scripts. + + +Debug +~~~~~ + +Setting ``App.debug`` to ``True`` will produce detailed error stacks whenever +the application generates an error. |settable| + +.. |settable| replace:: The user can ``set`` this parameter + during application execution. + (See :ref:`parameters`) + +.. _parameters: + +Other user-settable parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A list of all user-settable parameters, with brief +comments, is viewable from within a running application +with:: + + (Cmd) set --long + allow_ansi: Terminal # Allow ANSI escape sequences in output (valid values: Terminal, Always, Never) + continuation_prompt: > # On 2nd+ line of input + debug: False # Show full error stack on error + echo: False # Echo command issued into output + editor: vim # Program used by ``edit`` + feedback_to_output: False # include nonessentials in `|`, `>` results + locals_in_py: False # Allow access to your application in py via self + prompt: (Cmd) # The prompt issued to solicit input + quiet: False # Don't print nonessential feedback + timing: False # Report execution times + +Any of these user-settable parameters can be set while running your app with +the ``set`` command like so:: + + set allow_ansi Never + + + +Create New Settings +------------------- + Your application can define user-settable parameters which your code can reference. First create a class attribute with the default value. Then update the ``settable`` dictionary with your setting name and a short description diff --git a/docs/features/shortcuts_aliases_macros.rst b/docs/features/shortcuts_aliases_macros.rst index 7b91a4b5..0f06fe08 100644 --- a/docs/features/shortcuts_aliases_macros.rst +++ b/docs/features/shortcuts_aliases_macros.rst @@ -4,10 +4,92 @@ Shortcuts, Aliases, and Macros Shortcuts --------- +Command shortcuts for long command names and common commands can make life more +convenient for your users. Shortcuts are used without a space separating them +from their arguments, like ``!ls``. By default, the following shortcuts are +defined: + + ``?`` + help + + ``!`` + shell: run as OS-level command + + ``@`` + run script file + + ``@@`` + run script file; filename is relative to current script location + +To define more shortcuts, update the dict ``App.shortcuts`` with the +{'shortcut': 'command_name'} (omit ``do_``):: + + class App(Cmd2): + def __init__(self): + shortcuts = dict(cmd2.DEFAULT_SHORTCUTS) + shortcuts.update({'*': 'sneeze', '~': 'squirm'}) + cmd2.Cmd.__init__(self, shortcuts=shortcuts) + +.. warning:: + + Shortcuts need to be created by updating the ``shortcuts`` dictionary + attribute prior to calling the ``cmd2.Cmd`` super class ``__init__()`` + method. Moreover, that super class init method needs to be called after + updating the ``shortcuts`` attribute This warning applies in general to many + other attributes which are not settable at runtime. + Aliases ------- +In addition to shortcuts, ``cmd2`` provides a full alias feature via the +``alias`` command. Aliases work in a similar fashion to aliases in the Bash +shell. + +The syntax to create an alias is: ``alias create name command [args]``. + + Ex: ``alias create ls !ls -lF`` + +For more details run: ``help alias create`` + +Use ``alias list`` to see all or some of your aliases. The output of this +command displays your aliases using the same command that was used to create +them. Therefore you can place this output in a ``cmd2`` startup script to +recreate your aliases each time you start the application + + Ex: ``alias list`` + +For more details run: ``help alias list`` + +Use ``alias delete`` to remove aliases + +For more details run: ``help alias delete`` + Macros ------ + +``cmd2`` provides a feature that is similar to aliases called macros. The major +difference between macros and aliases is that macros can contain argument +placeholders. Arguments are expressed when creating a macro using {#} notation +where {1} means the first argument. + +The following creates a macro called my_macro that expects two arguments: + + macro create my_macro make_dinner -meat {1} -veggie {2} + +When the macro is called, the provided arguments are resolved and the assembled +command is run. For example: + + my_macro beef broccoli ---> make_dinner -meat beef -veggie broccoli + +For more details run: ``help macro create`` + +The macro command has ``list`` and ``delete`` subcommands that function +identically to the alias subcommands of the same name. Like aliases, macros can +be created via a ``cmd2`` startup script to preserve them across application +sessions. + +For more details on listing macros run: ``help macro list`` + +For more details on deleting macros run: ``help macro delete`` diff --git a/docs/index.rst b/docs/index.rst index 857fb831..c21cfeb1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -88,18 +88,3 @@ Meta doc_conventions copyright - - -To Be Integrated -================ - -Files from old documentation to be integrated into new structure - -* :doc:`settingchanges` - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: To Be Integrated - - settingchanges diff --git a/docs/settingchanges.rst b/docs/settingchanges.rst deleted file mode 100644 index d4f277fd..00000000 --- a/docs/settingchanges.rst +++ /dev/null @@ -1,194 +0,0 @@ -========================================= -Features requiring only parameter changes -========================================= - -Several aspects of a ``cmd2`` application's behavior -can be controlled simply by setting attributes of ``App``. -A parameter can also be changed at runtime by the user *if* -its name is included in the dictionary ``app.settable``. -(To define your own user-settable parameters, see :ref:`parameters`) - - -Shortcuts -========= - -Command shortcuts for long command names and common commands can make life more -convenient for your users. Shortcuts are used without a space separating them -from their arguments, like ``!ls``. By default, the following shortcuts are -defined: - - ``?`` - help - - ``!`` - shell: run as OS-level command - - ``@`` - run script file - - ``@@`` - run script file; filename is relative to current script location - -To define more shortcuts, update the dict ``App.shortcuts`` with the -{'shortcut': 'command_name'} (omit ``do_``):: - - class App(Cmd2): - def __init__(self): - shortcuts = dict(cmd2.DEFAULT_SHORTCUTS) - shortcuts.update({'*': 'sneeze', '~': 'squirm'}) - cmd2.Cmd.__init__(self, shortcuts=shortcuts) - -.. warning:: - - Shortcuts need to be created by updating the ``shortcuts`` dictionary - attribute prior to calling the ``cmd2.Cmd`` super class ``__init__()`` - method. Moreover, that super class init method needs to be called after - updating the ``shortcuts`` attribute This warning applies in general to many - other attributes which are not settable at runtime. - - -Aliases -======= - -In addition to shortcuts, ``cmd2`` provides a full alias feature via the -``alias`` command. Aliases work in a similar fashion to aliases in the Bash -shell. - -The syntax to create an alias is: ``alias create name command [args]``. - - Ex: ``alias create ls !ls -lF`` - -For more details run: ``help alias create`` - -Use ``alias list`` to see all or some of your aliases. The output of this -command displays your aliases using the same command that was used to create -them. Therefore you can place this output in a ``cmd2`` startup script to -recreate your aliases each time you start the application - - Ex: ``alias list`` - -For more details run: ``help alias list`` - -Use ``alias delete`` to remove aliases - -For more details run: ``help alias delete`` - -Macros -====== - -``cmd2`` provides a feature that is similar to aliases called macros. The major -difference between macros and aliases is that macros can contain argument -placeholders. Arguments are expressed when creating a macro using {#} notation -where {1} means the first argument. - -The following creates a macro called my_macro that expects two arguments: - - macro create my_macro make_dinner -meat {1} -veggie {2} - -When the macro is called, the provided arguments are resolved and the assembled -command is run. For example: - - my_macro beef broccoli ---> make_dinner -meat beef -veggie broccoli - -For more details run: ``help macro create`` - -The macro command has ``list`` and ``delete`` subcommands that function -identically to the alias subcommands of the same name. Like aliases, macros can -be created via a ``cmd2`` startup script to preserve them across application -sessions. - -For more details on listing macros run: ``help macro list`` - -For more details on deleting macros run: ``help macro delete`` - - -Default to shell -================ - -Every ``cmd2`` application can execute operating-system level (shell) commands -with ``shell`` or a ``!`` shortcut:: - - (Cmd) shell which python - /usr/bin/python - (Cmd) !which python - /usr/bin/python - -However, if the parameter ``default_to_shell`` is ``True``, then *every* -command will be attempted on the operating system. Only if that attempt fails -(i.e., produces a nonzero return value) will the application's own ``default`` -method be called. - -:: - - (Cmd) which python - /usr/bin/python - (Cmd) my dog has fleas - sh: my: not found - *** Unknown syntax: my dog has fleas - -Quit on SIGINT -============== - -On many shells, SIGINT (most often triggered by the user pressing Ctrl+C) only -cancels the current line, not the entire command loop. By default, a ``cmd2`` -application will quit on receiving this signal. However, if ``quit_on_sigint`` -is set to ``False``, then the current line will simply be cancelled. - -:: - - (Cmd) typing a comma^C - (Cmd) - -.. warning:: - The default SIGINT behavior will only function properly if **cmdloop** is running - in the main thread. - - -Timing -====== - -Setting ``App.timing`` to ``True`` outputs timing data after every application -command is executed. |settable| - -Echo -==== - -If ``True``, each command the user issues will be repeated to the screen before -it is executed. This is particularly useful when running scripts. - -Debug -===== - -Setting ``App.debug`` to ``True`` will produce detailed error stacks whenever -the application generates an error. |settable| - -.. |settable| replace:: The user can ``set`` this parameter - during application execution. - (See :ref:`parameters`) - -.. _parameters: - -Other user-settable parameters -============================== - -A list of all user-settable parameters, with brief -comments, is viewable from within a running application -with:: - - (Cmd) set --long - allow_ansi: Terminal # Allow ANSI escape sequences in output (valid values: Terminal, Always, Never) - continuation_prompt: > # On 2nd+ line of input - debug: False # Show full error stack on error - echo: False # Echo command issued into output - editor: vim # Program used by ``edit`` - feedback_to_output: False # include nonessentials in `|`, `>` results - locals_in_py: False # Allow access to your application in py via self - prompt: (Cmd) # The prompt issued to solicit input - quiet: False # Don't print nonessential feedback - timing: False # Report execution times - -Any of these user-settable parameters can be set while running your app with -the ``set`` command like so:: - - set allow_ansi Never - |