Improved documentation for regular expressions in transcripts

README.rst

@@ -240,9 +240,14 @@ example/exampleSession.txt::
     blah blah blah
     (Cmd) & look, a shortcut!
     look, a shortcut!
+    (Cmd) show color
+    colors: /(True|False)/
     (Cmd) set prompt "---> "
     prompt - was: (Cmd)
     now: --->
     ---> say goodbye
     goodbye
 
+Note how a regular expression ``/True|False/`` is used near the end for output of the **show color** command since
+colored text is currently not available for cmd2 on Windows.  Regular expressions can be used anywhere within a
+transcript file simply by embedding them within two forward slashes, ``/``.

cmd2.py

@@ -2001,6 +2001,12 @@ class Cmd2TestCase(unittest.TestCase):
        that will execute the commands in a transcript file and expect the results shown.
        See example.py"""
     CmdApp = None
+    regexPattern = pyparsing.QuotedString(quoteChar=r'/', escChar='\\', multiline=True, unquoteResults=True)
+    regexPattern.ignore(pyparsing.cStyleComment)
+    notRegexPattern = pyparsing.Word(pyparsing.printables)
+    notRegexPattern.setParseAction(lambda t: re.escape(t[0]))
+    expectationParser = regexPattern | notRegexPattern
+    anyWhitespace = re.compile(r'\s', re.DOTALL | re.MULTILINE)
 
     def fetchTranscripts(self):
         self.transcripts = {}
@@ -2024,13 +2030,6 @@ def runTest(self):  # was testall
             for (fname, transcript) in its:
                 self._test_transcript(fname, transcript)
 
-    regexPattern = pyparsing.QuotedString(quoteChar=r'/', escChar='\\', multiline=True, unquoteResults=True)
-    regexPattern.ignore(pyparsing.cStyleComment)
-    notRegexPattern = pyparsing.Word(pyparsing.printables)
-    notRegexPattern.setParseAction(lambda t: re.escape(t[0]))
-    expectationParser = regexPattern | notRegexPattern
-    anyWhitespace = re.compile(r'\s', re.DOTALL | re.MULTILINE)
-
     def _test_transcript(self, fname, transcript):
         line_num = 0
         finished = False

examples/exampleSession.txt

@@ -1,3 +1,4 @@
+# Run this transcript with "python example.py -t exampleSession.txt"
 (Cmd) help
 
 Documented commands (type help <topic>):
@@ -62,6 +63,8 @@ our BDFL
 blah blah blah
 (Cmd) & look, a shortcut!
 look, a shortcut!
+(Cmd) show color
+colors: /(True|False)/
 (Cmd) set prompt "---> "
 prompt - was: (Cmd)
 now: --->

examples/transcript_regex.txt

@@ -0,0 +1,18 @@
+# Run this transcript with "python example.py -t transcript_regex.txt"
+# The regex for editor matches any word until first space.  The one for colors is because no color on Windows.
+(Cmd) set
+abbrev: True
+autorun_on_edit: True
+case_insensitive: True
+colors: /(True|False)/
+continuation_prompt: >
+debug: False
+default_file_name: command.txt
+echo: False
+editor: /([^\s]+)/
+feedback_to_output: False
+locals_in_py: True
+maxrepeats: 3
+prompt: (Cmd)
+quiet: False
+timing: False

tests/test_transcript.py

@@ -310,3 +310,29 @@ def test_invalid_syntax(_cmdline_app, capsys):
     out, err = capsys.readouterr()
     expected = normalize("""ERROR: Invalid syntax: No closing quotation""")
     assert normalize(str(err)) == expected
+
+
+def test_regex_transcript(request, capsys):
+    # Create a cmd2.Cmd() instance and make sure basic settings are like we want for test
+    app = CmdLineApp()
+
+    # Get location of the transcript
+    test_dir = os.path.dirname(request.module.__file__)
+    transcript_file = os.path.join(test_dir, 'transcript_regex.txt')
+
+    # Need to patch sys.argv so cmd2 doesn't think it was called with arguments equal to the py.test args
+    testargs = ['prog', '-t', transcript_file]
+    with mock.patch.object(sys, 'argv', testargs):
+        # Run the command loop
+        app.cmdloop()
+
+    # Check for the unittest "OK" condition for the 1 test which ran
+    expected_start = ".\n----------------------------------------------------------------------\nRan 1 test in"
+    expected_end = "s\n\nOK\n\n"
+    out, err = capsys.readouterr()
+    if six.PY3:
+        assert err.startswith(expected_start)
+        assert err.endswith(expected_end)
+    else:
+        assert err == ''
+        assert out == ''

tests/transcript_regex.txt

@@ -0,0 +1,18 @@
+# Run this transcript with "python example.py -t transcript_regex.txt"
+# The regex for editor matches any word until first space.  The one for colors is because no color on Windows.
+(Cmd) set
+abbrev: True
+autorun_on_edit: True
+case_insensitive: True
+colors: /(True|False)/
+continuation_prompt: >
+debug: False
+default_file_name: command.txt
+echo: False
+editor: /([^\s]+)/
+feedback_to_output: False
+locals_in_py: True
+maxrepeats: 3
+prompt: (Cmd)
+quiet: False
+timing: False