diff options
| -rw-r--r-- | docs/freefeatures.rst | 128 |
1 files changed, 67 insertions, 61 deletions
diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index 1ae3c7ac..b5c9991a 100644 --- a/docs/freefeatures.rst +++ b/docs/freefeatures.rst @@ -253,10 +253,10 @@ the readline history. .. automethod:: cmd2.cmd2.Cmd.__init__ -``cmd2`` makes a third type of history access available with the `history` command. Each time -the user enters a command, ``cmd2`` saves the input. The `history` command lets you do interesting -things with that saved input. The examples to follow all assume that you have entered the -following commands:: +``cmd2`` makes a third type of history access available with the ``history`` +command. Each time the user enters a command, ``cmd2`` saves the input. The +``history`` command lets you do interesting things with that saved input. The +examples to follow all assume that you have entered the following commands:: (Cmd) alias create one !echo one Alias 'one' created @@ -267,8 +267,9 @@ following commands:: (Cmd) alias create four !echo four Alias 'four' created -In it's simplest form, the `history` command displays previously entered commands. With no -additional arguments, it displays all previously entered commands:: +In it's simplest form, the ``history`` command displays previously entered +commands. With no additional arguments, it displays all previously entered +commands:: (Cmd) history 1 alias create one !echo one @@ -276,27 +277,30 @@ additional arguments, it displays all previously entered commands:: 3 alias create three !echo three 4 alias create four !echo four -If you give a positive integer as an argument, then it only displays the specified command:: +If you give a positive integer as an argument, then it only displays the +specified command:: (Cmd) history 4 4 alias create four !echo four -If you give a negative integer *N* as an argument, then it display the *Nth* last command. -For example, if you give `-1` it will display the last command you entered. If you give `-2` -it will display the next to last command you entered, and so forth:: +If you give a negative integer *N* as an argument, then it display the *Nth* +last command. For example, if you give ``-1`` it will display the last command +you entered. If you give ``-2`` it will display the next to last command you +entered, and so forth:: (Cmd) history -2 3 alias create three !echo three -You can use a similar mechanism to display a range of commands. Simply give two command numbers -separated by `..` or `:`, and you will see all commands between those two numbers:: +You can use a similar mechanism to display a range of commands. Simply give two +command numbers separated by ``..`` or ``:``, and you will see all commands +between those two numbers:: (Cmd) history 2:3 2 alias create two !echo two 3 alias create three !echo three -If you omit the first number, it will start at the beginning. If you omit the last number, it -will continue to the end:: +If you omit the first number, it will start at the beginning. If you omit the +last number, it will continue to the end:: (Cmd) history :2 1 alias create one !echo one @@ -306,25 +310,26 @@ will continue to the end:: 3 alias create three !echo three 4 alias create four !echo four -You can use negative numbers as either the first or second number of the range (but not both). If -you want to display the last three commands entered:: +You can use negative numbers as either the first or second number of the range +(but not both). If you want to display the last three commands entered:: (Cmd) history -- -3: 2 alias create two !echo two 3 alias create three !echo three 4 alias create four !echo four -Notice the double dashes. These are required because the history command uses `argparse` to parse -the command line arguments. For reasons I do not understand, `argparse` thinks `-3:` is an -option, not an argument, but it thinks `-3` is an argument. +Notice the double dashes. These are required because the history command uses +``argparse`` to parse the command line arguments. For reasons I do not +understand, ``argparse`` thinks ``-3:`` is an option, not an argument, but it +thinks ``-3`` is an argument. -There is no zeroth command, so don't ask for it. If you are a python programmer, you've -probably noticed this looks a lot like the slice syntax for lists and arrays. It is, -with the exception that the first history command is 1, where the first element in -a python array is 0. +There is no zeroth command, so don't ask for it. If you are a python programmer, +you've probably noticed this looks a lot like the slice syntax for lists and +arrays. It is, with the exception that the first history command is 1, where the +first element in a python array is 0. -Besides selecting previous commands by number, you can also search for them. You can use a simple -string search:: +Besides selecting previous commands by number, you can also search for them. You +can use a simple string search:: (Cmd) history two 2 alias create two !echo two @@ -334,7 +339,7 @@ Or a regular expression search by enclosing your regex in slashes:: (Cmd) history '/te\ +th/' 3 alias create three !echo three -If your regular expression contains any characters that `argparse` finds +If your regular expression contains any characters that ``argparse`` finds interesting, like dash or plus, you also need to enclose your regular expression in quotation marks. @@ -349,8 +354,8 @@ perform many other actions: - running previously entered commands, saving the commands and their output to a text file - clearing the history of entered commands -Each of these actions is invoked using a command line option. The `-r` or -`--run` option runs one or more previously entered commands. To run command +Each of these actions is invoked using a command line option. The ``-r`` or +``--run`` option runs one or more previously entered commands. To run command number 1:: (Cmd) history --run 1 @@ -361,80 +366,81 @@ stop looking for options):: (Cmd) history -r -- -2: Say you want to re-run some previously entered commands, but you would really -like to make a few changes to them before doing so. When you use the `-e` or -`--edit` option, `history` will write the selected commands out to a text file, -and open that file with a text editor. You make whatever changes, additions, or -deletions, you want. When you leave the text editor, all the commands in the -file are executed. To edit and then re-run commands 2-4 you would:: +like to make a few changes to them before doing so. When you use the ``-e`` or +``--edit`` option, ``history`` will write the selected commands out to a text +file, and open that file with a text editor. You make whatever changes, +additions, or deletions, you want. When you leave the text editor, all the +commands in the file are executed. To edit and then re-run commands 2-4 you +would:: (Cmd) history --edit 2:4 If you want to save the commands to a text file, but not edit and re-run them, -use the `-o` or `--output-file` option. This is a great way to create -:ref:`scripts`, which can be loaded and executed using the `load` command. To +use the ``-o`` or ``--output-file`` option. This is a great way to create +:ref:`scripts`, which can be loaded and executed using the ``load`` command. To save the first 5 commands entered in this session to a text file:: (Cmd) history :5 -o history.txt -The `history` command can also save both the commands and their output to a text -file. This is called a transcript. See :doc:`transcript` for more information on -how transcripts work, and what you can use them for. To create a transcript use -the `-t` or `--transcription` option:: +The ``history`` command can also save both the commands and their output to a +text file. This is called a transcript. See :doc:`transcript` for more +information on how transcripts work, and what you can use them for. To create a +transcript use the ``-t`` or ``--transcription`` option:: (Cmd) history 2:3 --transcript transcript.txt -The `--transcript` option implies `--run`: the commands must be re-run in order -to capture their output to the transcript file. +The ``--transcript`` option implies ``--run``: the commands must be re-run in +order to capture their output to the transcript file. The last action the history command can perform is to clear the command history -using `-c` or `--clear`:: +using ``-c`` or ``--clear``:: (Cmd) history -c -In addition to these five actions, the `history` command also has some options -to control how the output is formatted. With no arguments, the `history` command -displays the command number before each command. This is great when displaying -history to the screen because it gives you an easy reference to identify -previously entered commands. However, when creating a script or a transcript, -the command numbers would prevent the script from loading properly. The `-s` or -`--script` option instructs the `history` command to suppress the line numbers. -This option is automatically set by the `--output-file`, `--transcript`, and -`--edit` options. If you want to output the history commands with line numbers -to a file, you can do it with output redirection:: +In addition to these five actions, the ``history`` command also has some options +to control how the output is formatted. With no arguments, the ``history`` +command displays the command number before each command. This is great when +displaying history to the screen because it gives you an easy reference to +identify previously entered commands. However, when creating a script or a +transcript, the command numbers would prevent the script from loading properly. +The ``-s`` or ``--script`` option instructs the ``history`` command to suppress +the line numbers. This option is automatically set by the ``--output-file``, +``--transcript``, and ``--edit`` options. If you want to output the history +commands with line numbers to a file, you can do it with output redirection:: (Cmd) history 1:4 > history.txt -You might use `-s` or `--script` on it's own if you want to display history +You might use ``-s`` or ``--script`` on it's own if you want to display history commands to the screen without line numbers, so you can copy them to the clipboard:: (Cmd) history -s 1:3 -`cmd2` supports both aliases and macros, which allow you to substitute a short, -more convenient input string with a longer replacement string. Say we create an -alias like this, and then use it:: +``cmd2`` supports both aliases and macros, which allow you to substitute a +short, more convenient input string with a longer replacement string. Say we +create an alias like this, and then use it:: (Cmd) alias create ls shell ls -aF Alias 'ls' created (Cmd) ls -d h* history.txt htmlcov/ -By default, the `history` command shows exactly what we typed:: +By default, the ``history`` command shows exactly what we typed:: (Cmd) history 1 alias create ls shell ls -aF 2 ls -d h* There are two ways to modify that display so you can see what aliases and macros -were expanded to. The first is to use `-x` or `--expanded`. These options show -the expanded command instead of the entered command:: +were expanded to. The first is to use ``-x`` or ``--expanded``. These options +show the expanded command instead of the entered command:: (Cmd) history -x 1 alias create ls shell ls -aF 2 shell ls -aF -d h* If you want to see both the entered command and the expanded command, use the -`-v` or `--verbose` option:: +``-v`` or ``--verbose`` option:: (Cmd) history -v 1 alias create ls shell ls -aF @@ -444,7 +450,7 @@ If you want to see both the entered command and the expanded command, use the If the entered command had no expansion, it is displayed as usual. However, if there is some change as the result of expanding macros and aliases, then the entered command is displayed with the number, and the expanded command is -displayed with the number followed by an `x`. +displayed with the number followed by an ``x``. .. _`Readline Emacs editing mode`: http://readline.kablamo.org/emacs.html |