diff options
Diffstat (limited to 'docs/features/transcripts.rst')
| -rw-r--r-- | docs/features/transcripts.rst | 51 |
1 files changed, 27 insertions, 24 deletions
diff --git a/docs/features/transcripts.rst b/docs/features/transcripts.rst index e4ff79a5..18daeb78 100644 --- a/docs/features/transcripts.rst +++ b/docs/features/transcripts.rst @@ -13,8 +13,8 @@ from commands that produce dynamic or variable output. Creating From History --------------------- -A transcript can automatically generated based upon commands previously executed -in the *history* using ``history -t``:: +A transcript can automatically generated based upon commands previously +executed in the *history* using ``history -t``:: (Cmd) help ... @@ -28,15 +28,16 @@ This is by far the easiest way to generate a transcript. .. warning:: Make sure you use the **poutput()** method in your ``cmd2`` application for - generating command output. This method of the ``cmd2.Cmd`` class ensure that - output is properly redirected when redirecting to a file, piping to a shell - command, and when generating a transcript. + generating command output. This method of the ``cmd2.Cmd`` class ensure + that output is properly redirected when redirecting to a file, piping to a + shell command, and when generating a transcript. Creating From A Script File --------------------------- -A transcript can also be automatically generated from a script file using ``run_script -t``:: +A transcript can also be automatically generated from a script file using +``run_script -t``:: (Cmd) run_script scripts/script.txt -t transcript.txt 2 commands and their outputs saved to transcript file 'transcript.txt' @@ -98,12 +99,12 @@ will be ignored. Regular Expressions ------------------- -If we used the above transcript as-is, it would likely fail. As you can see, the -``mumble`` command doesn't always return the same thing: it inserts random words -into the input. +If we used the above transcript as-is, it would likely fail. As you can see, +the ``mumble`` command doesn't always return the same thing: it inserts random +words into the input. -Regular expressions can be included in the response portion of a transcript, and -are surrounded by slashes:: +Regular expressions can be included in the response portion of a transcript, +and are surrounded by slashes:: (Cmd) mumble maybe we could go to lunch /.*\bmaybe\b.*\bcould\b.*\blunch\b.*/ @@ -111,9 +112,10 @@ are surrounded by slashes:: /.*\bmaybe\b.*\bcould\b.*\blunch\b.*/ Without creating a tutorial on regular expressions, this one matches anything -that has the words ``maybe``, ``could``, and ``lunch`` in that order. It doesn't -ensure that ``we`` or ``go`` or ``to`` appear in the output, but it does work if -mumble happens to add words to the beginning or the end of the output. +that has the words ``maybe``, ``could``, and ``lunch`` in that order. It +doesn't ensure that ``we`` or ``go`` or ``to`` appear in the output, but it +does work if mumble happens to add words to the beginning or the end of the +output. Since the output could be multiple lines long, ``cmd2`` uses multiline regular expression matching, and also uses the ``DOTALL`` flag. These two flags subtly @@ -122,7 +124,8 @@ change the behavior of commonly used special characters like ``.``, ``^`` and documentation <https://docs.python.org/3/library/re.html>`_. If your output has slashes in it, you will need to escape those slashes so the -stuff between them is not interpred as a regular expression. In this transcript:: +stuff between them is not interpred as a regular expression. In this +transcript:: (Cmd) say cd /usr/local/lib/python3.6/site-packages /usr/local/lib/python3.6/site-packages @@ -147,15 +150,15 @@ the path instead of specifying it verbatim, or we can escape the slashes:: prompt: (Cmd)/ / Some terminal emulators strip trailing space when you copy text from them. - This could make the actual data generated by your app different than the text - you pasted into the transcript, and it might not be readily obvious why the - transcript is not passing. Consider using :ref:`output_redirection` to the - clipboard or to a file to ensure you accurately capture the output of your - command. - - If you aren't using regular expressions, make sure the newlines at the end of - your transcript exactly match the output of your commands. A common cause of - a failing transcript is an extra or missing newline. + This could make the actual data generated by your app different than the + text you pasted into the transcript, and it might not be readily obvious why + the transcript is not passing. Consider using :ref:`output_redirection` to + the clipboard or to a file to ensure you accurately capture the output of + your command. + + If you aren't using regular expressions, make sure the newlines at the end + of your transcript exactly match the output of your commands. A common cause + of a failing transcript is an extra or missing newline. If you are using regular expressions, be aware that depending on how you write your regex, the newlines after the regex may or may not matter. ``\Z`` |