Skip to content

Commit 1c302bc

Browse files
committed
Add documentation for the history command.
1 parent dfe5864 commit 1c302bc

File tree

1 file changed

+194
-6
lines changed

1 file changed

+194
-6
lines changed

docs/freefeatures.rst

Lines changed: 194 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ Simply include one command per line, typed exactly as you would inside a ``cmd2`
2929
Comments
3030
========
3131

32-
Any command line input where the first non-whitespace character is a # will be treated as a comment.
33-
This means any # character appearing later in the command will be treated as a literal. The same
34-
applies to a # in the middle of a multiline command, even if it is the first character on a line.
32+
Any command line input where the first non-whitespace character is a `#` will be treated as a comment.
33+
This means any `#` character appearing later in the command will be treated as a literal. The same
34+
applies to a `#` in the middle of a multiline command, even if it is the first character on a line.
3535

3636
Comments can be useful in :ref:`scripts`, but would be pointless within an interactive session.
3737

@@ -269,9 +269,198 @@ the readline history.
269269

270270
.. automethod:: cmd2.cmd2.Cmd.__init__
271271

272-
``cmd2`` makes a third type of history access available with the **history** command:
272+
``cmd2`` makes a third type of history access available with the `history` command. Each time
273+
the user enters a command, ``cmd2`` saves the input. The `history` command lets you do interesting
274+
things with that saved input. The examples to follow all assume that you have entered the
275+
following commands::
273276

274-
.. automethod:: cmd2.cmd2.Cmd.do_history
277+
(Cmd) alias create one !echo one
278+
Alias 'one' created
279+
(Cmd) alias create two !echo two
280+
Alias 'two' created
281+
(Cmd) alias create three !echo three
282+
Alias 'three' created
283+
(Cmd) alias create four !echo four
284+
Alias 'four' created
285+
286+
In it's simplest form, the `history` command displays previously entered commands. With no
287+
additional arguments, it displays all previously entered commands::
288+
289+
(Cmd) history
290+
1 alias create one !echo one
291+
2 alias create two !echo two
292+
3 alias create three !echo three
293+
4 alias create four !echo four
294+
295+
If you give a positive integer as an argument, then it only displays the specified command::
296+
297+
(Cmd) history 4
298+
4 alias create four !echo four
299+
300+
If you give a negative integer *N* as an argument, then it display the *Nth* last command.
301+
For example, if you give `-1` it will display the last command you entered. If you give `-2`
302+
it will display the next to last command you entered, and so forth::
303+
304+
(Cmd) history -2
305+
3 alias create three !echo three
306+
307+
You can use a similar mechanism to display a range of commands. Simply give two command numbers
308+
separated by `..` or `:`, and you will see all commands between those two numbers::
309+
310+
(Cmd) history 2:3
311+
2 alias create two !echo two
312+
3 alias create three !echo three
313+
314+
If you omit the first number, it will start at the beginning. If you omit the last number, it
315+
will continue to the end::
316+
317+
(Cmd) history :2
318+
1 alias create one !echo one
319+
2 alias create two !echo two
320+
(Cmd) history 2:
321+
2 alias create two !echo two
322+
3 alias create three !echo three
323+
4 alias create four !echo four
324+
325+
You can use negative numbers as either the first or second number of the range (but not both). If
326+
you want to display the last three commands entered::
327+
328+
(Cmd) history -- -3:
329+
2 alias create two !echo two
330+
3 alias create three !echo three
331+
4 alias create four !echo four
332+
333+
Notice the double dashes. These are required because the history command uses `argparse` to parse
334+
the command line arguments. For reasons I do not understand, `argparse` thinks `-3:` is an
335+
option, not an argument, but it thinks `-3` is an argument.
336+
337+
There is no zeroth command, so don't ask for it. If you are a python programmer, you've
338+
probably noticed this looks a lot like the slice syntax for lists and arrays. It is,
339+
with the exception that the first history command is 1, where the first element in
340+
a python array is 0.
341+
342+
Besides selecting previous commands by number, you can also search for them. You can use a simple
343+
string search::
344+
345+
(Cmd) history two
346+
2 alias create two !echo two
347+
348+
Or a regular expression search by enclosing your regex in slashes::
349+
350+
(Cmd) history '/te\ +th/'
351+
3 alias create three !echo three
352+
353+
If your regular expression contains any characters that `argparse` finds
354+
interesting, like dash or plus, you also need to enclose your regular expression
355+
in quotation marks.
356+
357+
This all sounds great, but doesn't it seem like a bit of overkill to have all
358+
these ways to select commands if all we can do is display them? Turns out,
359+
displaying history commands is just the beginning. The history command can
360+
perform many other actions:
361+
362+
- running previously entered commands
363+
- saving previously entered commands to a text file
364+
- opening previously entered commands in your favorite text editor
365+
- running previously entered commands, saving the commands and their output to a text file
366+
- clearing the history of entered commands
367+
368+
Each of these actions is invoked using a command line option. The `-r` or
369+
`--run` option runs one or more previously entered commands. To run command
370+
number 1::
371+
372+
(Cmd) history --run 1
373+
374+
To rerun the last two commands (there's that double dash again to make argparse
375+
stop looking for options)::
376+
377+
(Cmd) history -r -- -2:
378+
379+
Say you want to re-run some previously entered commands, but you would really
380+
like to make a few changes to them before doing so. When you use the `-e` or
381+
`--edit` option, `history` will write the selected commands out to a text file,
382+
and open that file with a text editor. You make whatever changes, additions, or
383+
deletions, you want. When you leave the text editor, all the commands in the
384+
file are executed. To edit and then re-run commands 2-4 you would::
385+
386+
(Cmd) history --edit 2:4
387+
388+
If you want to save the commands to a text file, but not edit and re-run them,
389+
use the `-o` or `--output-file` option. This is a great way to create
390+
:ref:`scripts`, which can be loaded and executed using the `load` command. To
391+
save the first 5 commands entered in this session to a text file::
392+
393+
(Cmd) history :5 -o history.txt
394+
395+
The `history` command can also save both the commands and their output to a text
396+
file. This is called a transcript. See :doc:`transcript` for more information on
397+
how transcripts work, and what you can use them for. To create a transcript use
398+
the `-t` or `--transcription` option::
399+
400+
(Cmd) history 2:3 --transcript transcript.txt
401+
402+
The `--transcript` option implies `--run`: the commands must be re-run in order
403+
to capture their output to the transcript file.
404+
405+
The last action the history command can perform is to clear the command history
406+
using `-c` or `--clear`::
407+
408+
(Cmd) history -c
409+
410+
In addition to these five actions, the `history` command also has some options
411+
to control how the output is formatted. With no arguments, the `history` command
412+
displays the command number before each command. This is great when displaying
413+
history to the screen because it gives you an easy reference to identify
414+
previously entered commands. However, when creating a script or a transcript,
415+
the command numbers would prevent the script from loading properly. The `-s` or
416+
`--script` option instructs the `history` command to suppress the line numbers.
417+
This option is automatically set by the `--output-file`, `--transcript`, and
418+
`--edit` options. If you want to output the history commands with line numbers
419+
to a file, you can do it with output redirection::
420+
421+
(Cmd) history 1:4 > history.txt
422+
423+
You might use `-s` or `--script` on it's own if you want to display history
424+
commands to the screen without line numbers, so you can copy them to the
425+
clipboard::
426+
427+
(Cmd) history -s 1:3
428+
429+
`cmd2` supports both aliases and macros, which allow you to substitute a short,
430+
more convenient input string with a longer replacement string. Say we create an
431+
alias like this, and then use it::
432+
433+
(Cmd) alias create ls shell ls -aF
434+
Alias 'ls' created
435+
(Cmd) ls -d h*
436+
history.txt htmlcov/
437+
438+
By default, the `history` command shows exactly what we typed::
439+
440+
(Cmd) history
441+
1 alias create ls shell ls -aF
442+
2 ls -d h*
443+
444+
There are two ways to modify that display so you can see what aliases and macros
445+
were expanded to. The first is to use `-x` or `--expanded`. These options show
446+
the expanded command instead of the entered command::
447+
448+
(Cmd) history -x
449+
1 alias create ls shell ls -aF
450+
2 shell ls -aF -d h*
451+
452+
If you want to see both the entered command and the expanded command, use the
453+
`-v` or `--verbose` option::
454+
455+
(Cmd) history -v
456+
1 alias create ls shell ls -aF
457+
2 ls -d h*
458+
2x shell ls -aF -d h*
459+
460+
If the entered command had no expansion, it is displayed as usual. However, if
461+
there is some change as the result of expanding macros and aliases, then the
462+
entered command is displayed with the number, and the expanded command is
463+
displayed with the number followed by an `x`.
275464

276465
.. _`Readline Emacs editing mode`: http://readline.kablamo.org/emacs.html
277466

@@ -295,7 +484,6 @@ with automatically included ``do_`` methods.
295484
( ``!`` is a shortcut for ``shell``; thus ``!ls``
296485
is equivalent to ``shell ls``.)
297486

298-
299487
Transcript-based testing
300488
========================
301489

0 commit comments

Comments
 (0)