@@ -29,9 +29,9 @@ Simply include one command per line, typed exactly as you would inside a ``cmd2`
29
29
Comments
30
30
========
31
31
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.
35
35
36
36
Comments can be useful in :ref: `scripts `, but would be pointless within an interactive session.
37
37
@@ -269,9 +269,198 @@ the readline history.
269
269
270
270
.. automethod :: cmd2.cmd2.Cmd.__init__
271
271
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::
273
276
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 `.
275
464
276
465
.. _`Readline Emacs editing mode` : http://readline.kablamo.org/emacs.html
277
466
@@ -295,7 +484,6 @@ with automatically included ``do_`` methods.
295
484
( ``! `` is a shortcut for ``shell ``; thus ``!ls ``
296
485
is equivalent to ``shell ls ``.)
297
486
298
-
299
487
Transcript-based testing
300
488
========================
301
489
0 commit comments