Added load -r flag for recording a transcript based on a script file

The load command now supports the -r/--record_transcript flag for recording a transcript file based on a script file.

Author: tleonhardt

cmd2/cmd2.py

@@ -3332,18 +3332,17 @@ def do_history(self, args: argparse.Namespace) -> None:
             for hi in history:
                 self.poutput(hi.pr(script=args.script, expanded=args.expanded, verbose=args.verbose))
 
-    def _generate_transcript(self, history: List[HistoryItem], transcript_file: str) -> None:
+    def _generate_transcript(self, history: List[Union[HistoryItem, str]], transcript_file: str) -> None:
         """Generate a transcript file from a given history of commands."""
-        # Save the current echo state, and turn it off. We inject commands into the
-        # output using a different mechanism
         import io
 
+        # Disable echo and redirection while we manually redirect stdout to a StringIO buffer
+        saved_allow_redirection = self.allow_redirection
         saved_echo = self.echo
+        saved_stdout = self.stdout
+        self.allow_redirection = False
         self.echo = False
 
-        # Redirect stdout to the transcript file
-        saved_self_stdout = self.stdout
-
         # The problem with supporting regular expressions in transcripts
         # is that they shouldn't be processed in the command, just the output.
         # In addition, when we generate a transcript, any slashes in the output
@@ -3379,10 +3378,10 @@ def _generate_transcript(self, history: List[HistoryItem], transcript_file: str)
             # and add the regex-escaped output to the transcript
             transcript += output.replace('/', r'\/')
 
-        # Restore stdout to its original state
-        self.stdout = saved_self_stdout
-        # Set echo back to its original state
+        # Restore altered attributes to their original state
+        self.allow_redirection = saved_allow_redirection
         self.echo = saved_echo
+        self.stdout = saved_stdout
 
         # finally, we can write the transcript out to the file
         try:
@@ -3438,9 +3437,21 @@ def do_eos(self, _: argparse.Namespace) -> None:
     load_description = ("Run commands in script file that is encoded as either ASCII or UTF-8 text\n"
                         "\n"
                         "Script should contain one command per line, just like the command would be\n"
-                        "typed in the console.")
+                        "typed in the console.\n"
+                        "\n"
+                        "It loads commands from a script file into a queue and then the normal cmd2\n"
+                        "REPL resumes control and executes the commands in the queue in FIFO order.\n"
+                        "If you attempt to redirect/pipe a load command, it will capture the output\n"
+                        "of the load command itself, not what it adds to the queue.\n"
+                        "\n"
+                        "If the -r/--record_transcript flag is used, this command instead records\n"
+                        "the output of the script commands to a transcript for testing purposes.\n"
+                        )
 
     load_parser = ACArgumentParser(description=load_description)
+    setattr(load_parser.add_argument('-r', '--record_transcript',
+                                     help='record the output of the script as a transcript file'),
+            ACTION_ARG_CHOICES, ('path_complete',))
     setattr(load_parser.add_argument('script_path', help="path to the script file"),
             ACTION_ARG_CHOICES, ('path_complete',))
 
@@ -3474,11 +3485,16 @@ def do_load(self, args: argparse.Namespace) -> None:
             # command queue. Add an "end of script (eos)" command to cleanup the
             # self._script_dir list when done.
             with open(expanded_path, encoding='utf-8') as target:
-                self.cmdqueue = target.read().splitlines() + ['eos'] + self.cmdqueue
+                script_commands = target.read().splitlines()
         except OSError as ex:  # pragma: no cover
             self.perror("Problem accessing script from '{}': {}".format(expanded_path, ex))
             return
 
+        if args.record_transcript:
+            self._generate_transcript(script_commands, args.record_transcript)
+            return
+
+        self.cmdqueue = script_commands + ['eos'] + self.cmdqueue
         self._script_dir.append(os.path.dirname(expanded_path))
 
     relative_load_description = load_description

docs/freefeatures.rst

@@ -19,6 +19,11 @@ Both ASCII and UTF-8 encoded unicode text files are supported.
 
 Simply include one command per line, typed exactly as you would inside a ``cmd2`` application.
 
+The ``load`` command loads commands from a script file into a queue and then the normal cmd2 REPL
+resumes control and executes the commands in the queue in FIFO order.  A side effect of this
+is that if you redirect/pipe the output of a load command, it will redirect the output of the ``load``
+command itself, but will NOT redirect the output of the command loaded from the script file.
+
 .. automethod:: cmd2.cmd2.Cmd.do_load
 
 .. automethod:: cmd2.cmd2.Cmd.do__relative_load

docs/transcript.rst

@@ -13,9 +13,9 @@ from commands that produce dynamic or variable output.
 Creating a transcript
 =====================
 
-Automatically
--------------
-A transcript can automatically generated based upon commands previously executed in the *history*::
+Automatically from history
+--------------------------
+A transcript can automatically generated based upon commands previously executed in the *history* using ``history -t``::
 
     (Cmd) help
     ...
@@ -32,6 +32,17 @@ This is by far the easiest way to generate a transcript.
    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.
 
+Automatically from a script file
+--------------------------------
+A transcript can also be automatically generated from a script file using ``load -r``::
+
+    (Cmd) load scripts/script.txt -r transcript.txt
+    2 commands and their outputs saved to transcript file 'transcript.txt'
+    (Cmd)
+
+This is a particularly attractive option for automatically regenerating transcripts for regression testing as your ``cmd2``
+application changes.
+
 Manually
 --------
 Here's a transcript created from ``python examples/example.py``::