Refactor exit_code implementation

cmd2.Cmd.cmdloop() now returns self.exit_code which should be an integer

Also:
- Refactored examples to call sys.exit(app.cmdloop()) in their __main__
- Running transcript tests now sets the exit_code accordingly based on success/failure
- Updated CHANGELOG
- Updated README
- Updated Sphinx docs
- Added unit test for case when transcript test fails

Author: tleonhardt

CHANGELOG.md

@@ -8,6 +8,7 @@
     * Fixed parsing issue in case where output redirection appears before a pipe. In that case, the pipe was given
     precedence even though it appeared later in the command.
     * Fixed issue where quotes around redirection file paths were being lost in `Statement.expanded_command_line()`
+    * Fixed a bug in how line numbers were calculated for transcript testing
 * Enhancements
     * Added capability to chain pipe commands and redirect their output (e.g. !ls -l | grep user | wc -l > out.txt)
     * `pyscript` limits a command's stdout capture to the same period that redirection does.
@@ -21,11 +22,14 @@
     readline. This makes debugging a lot easier since readline suppresses these exceptions.
     * Added support for custom Namespaces in the argparse decorators. See description of `ns_provider` argument
     for more information.
+    * Transcript testing now sets the `exit_code` returned from `cmdloop` based on Success/Failure
 * Potentially breaking changes
     * Replaced `unquote_redirection_tokens()` with `unquote_specific_tokens()`. This was to support the fix
       that allows terminators in alias and macro values.
     * Changed `Statement.pipe_to` to a string instead of a list
     * `preserve_quotes` is now a keyword-only argument in the argparse decorators
+    * Refactored so that `cmd2.Cmd.cmdloop()` returns the `exit_code` instead of a call to `sys.exit()`
+        * It is now applicaiton developer's responsibility to treat the return value from `cmdloop()` accordingly
 * **Python 3.4 EOL notice**
     * Python 3.4 reached its [end of life](https://www.python.org/dev/peps/pep-0429/) on March 18, 2019
     * This is the last release of `cmd2` which will support Python 3.4

README.md

@@ -227,6 +227,7 @@ A sample application for cmd2.
 """
 import argparse
 import random
+import sys
 import cmd2
 
 class CmdLineApp(cmd2.Cmd):
@@ -294,8 +295,8 @@ class CmdLineApp(cmd2.Cmd):
             self.poutput(' '.join(output))
 
 if __name__ == '__main__':
-    c = CmdLineApp()
-    c.cmdloop()
+    app = CmdLineApp()
+    sys.exit(app.cmdloop())
 ```
 
 The following is a sample session running example.py.

cmd2/cmd2.py

@@ -553,8 +553,8 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, persistent
         # This boolean flag determines whether or not the cmd2 application can interact with the clipboard
         self.can_clip = can_clip
 
-        # This determines if a non-zero exit code should be used when exiting the application
-        self.exit_code = None
+        # This determines the value returned by cmdloop() when exiting the application
+        self.exit_code = 0
 
         # This lock should be acquired before doing any asynchronous changes to the terminal to
         # ensure the updates to the terminal don't interfere with the input being typed or output
@@ -3684,7 +3684,12 @@ class TestMyAppCase(Cmd2TestCase):
         sys.argv = [sys.argv[0]]  # the --test argument upsets unittest.main()
         testcase = TestMyAppCase()
         runner = unittest.TextTestRunner()
-        runner.run(testcase)
+        test_results = runner.run(testcase)
+        if test_results.wasSuccessful():
+            self.poutput('Tests passed', color=Fore.LIGHTGREEN_EX)
+        else:
+            self.perror('Tests failed', traceback_war=False)
+            self.exit_code = -1
 
     def async_alert(self, alert_msg: str, new_prompt: Optional[str] = None) -> None:  # pragma: no cover
         """
@@ -3932,14 +3937,15 @@ def _report_disabled_command_usage(self, *args, message_to_print: str, **kwargs)
         """
         self.decolorized_write(sys.stderr, "{}\n".format(message_to_print))
 
-    def cmdloop(self, intro: Optional[str] = None) -> None:
+    def cmdloop(self, intro: Optional[str] = None) -> int:
         """This is an outer wrapper around _cmdloop() which deals with extra features provided by cmd2.
 
         _cmdloop() provides the main loop equivalent to cmd.cmdloop().  This is a wrapper around that which deals with
         the following extra features provided by cmd2:
         - commands at invocation
         - transcript testing
         - intro banner
+        - exit code
 
         :param intro: if provided this overrides self.intro and serves as the intro banner printed once at start
         """
@@ -4002,8 +4008,7 @@ def cmdloop(self, intro: Optional[str] = None) -> None:
         # Restore the original signal handler
         signal.signal(signal.SIGINT, original_sigint_handler)
 
-        if self.exit_code is not None:
-            sys.exit(self.exit_code)
+        return self.exit_code
 
     ###
     #

cmd2/transcript.py

@@ -71,6 +71,7 @@ def _test_transcript(self, fname: str, transcript):
                 line = next(transcript)
             except StopIteration:
                 line = ''
+            line_num += 1
             # Read the entirety of a multi-line command
             while line.startswith(self.cmdapp.continuation_prompt):
                 command.append(line[len(self.cmdapp.continuation_prompt):])

docs/unfreefeatures.rst

@@ -204,8 +204,8 @@ Presents numbered options to user, as bash ``select``.
 Exit code to shell
 ==================
 The ``self.exit_code`` attribute of your ``cmd2`` application controls
-what exit code is sent to the shell when your application exits from
-``cmdloop()``.
+what exit code is returned from ``cmdloop()`` when it completes.  It is your job to make sure that
+this exit code gets sent to the shell when your application exits by calling ``sys.exit(app.cmdloop())``.
 
 
 Asynchronous Feedback

examples/alias_startup.py

@@ -21,5 +21,6 @@ def do_nothing(self, args):
 
 
 if __name__ == '__main__':
+    import sys
     app = AliasAndStartup()
-    app.cmdloop()
+    sys.exit(app.cmdloop())

examples/arg_print.py

@@ -63,5 +63,6 @@ def do_pprint(self, args, unknown):
 
 
 if __name__ == '__main__':
+    import sys
     app = ArgumentAndOptionPrinter()
-    app.cmdloop()
+    sys.exit(app.cmdloop())

examples/async_printing.py

@@ -197,6 +197,7 @@ def _alerter_thread_func(self) -> None:
 
 
 if __name__ == '__main__':
+    import sys
     app = AlerterApp()
     app.set_window_title("Asynchronous Printer Test")
-    app.cmdloop()
+    sys.exit(app.cmdloop())

examples/cmd_as_argument.py

@@ -14,7 +14,6 @@
 
 import argparse
 import random
-import sys
 
 import cmd2
 
@@ -101,13 +100,17 @@ def main(argv=None):
 
     c = CmdLineApp()
 
+    sys_exit_code = 0
     if args.command:
         # we have a command, run it and then exit
         c.onecmd_plus_hooks('{} {}'.format(args.command, ' '.join(args.command_args)))
     else:
         # we have no command, drop into interactive mode
-        c.cmdloop()
+        sys_exit_code = c.cmdloop()
+
+    return sys_exit_code
 
 
 if __name__ == '__main__':
+    import sys
     sys.exit(main())

examples/colors.py

@@ -138,5 +138,6 @@ def do_mumble(self, args):
 
 
 if __name__ == '__main__':
+    import sys
     c = CmdLineApp()
-    c.cmdloop()
+    sys.exit(c.cmdloop())