Merged alert_printer stuff from master and resolved conflicts

Author: tleonhardt

CHANGELOG.md

@@ -10,6 +10,10 @@
     for formatting help/description text
     * Aliases are now sorted alphabetically
     * The **set** command now tab-completes settable parameter names
+    * Added ``async_alert``, ``async_update_prompt``, and ``set_window_title`` functions
+        * These allow you to provide feedback to the user in an asychronous fashion, meaning alerts can
+        display when the user is still entering text at the prompt. See [async_printing.py](https://github.com/python-cmd2/cmd2/blob/master/examples/async_printing.py)
+        for an example.
     * Cross-platform colored output support 
         * ``colorama`` gets initialized properly in ``Cmd.__init()``
         * The ``Cmd.colors`` setting is no longer platform dependent and now has three values:

README.md

@@ -40,6 +40,7 @@ Main Features
 - Trivial to provide built-in help for all commands
 - Built-in regression testing framework for your applications (transcript-based testing)
 - Transcripts for use with built-in regression can be automatically generated from `history -t`
+- Alerts that seamlessly print while user enters text at prompt
 
 Python 2.7 support is EOL
 -------------------------

cmd2/cmd2.py

@@ -26,13 +26,54 @@ class RlType(Enum):
 
 
 # Check what implementation of readline we are using
-
 rl_type = RlType.NONE
 
+# Tells if the terminal we are running in supports vt100 control characters
+vt100_support = False
+
 # The order of this check matters since importing pyreadline will also show readline in the modules list
 if 'pyreadline' in sys.modules:
     rl_type = RlType.PYREADLINE
 
+    from ctypes import byref
+    from ctypes.wintypes import DWORD, HANDLE
+    import atexit
+
+    # Check if we are running in a terminal
+    if sys.stdout.isatty():  # pragma: no cover
+        # noinspection PyPep8Naming
+        def enable_win_vt100(handle: HANDLE) -> bool:
+            """
+            Enables VT100 character sequences in a Windows console
+            This only works on Windows 10 and up
+            :param handle: the handle on which to enable vt100
+            :return: True if vt100 characters are enabled for the handle
+            """
+            ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
+
+            # Get the current mode for this handle in the console
+            cur_mode = DWORD(0)
+            readline.rl.console.GetConsoleMode(handle, byref(cur_mode))
+
+            retVal = False
+
+            # Check if  ENABLE_VIRTUAL_TERMINAL_PROCESSING is already enabled
+            if (cur_mode.value & ENABLE_VIRTUAL_TERMINAL_PROCESSING) != 0:
+                retVal = True
+
+            elif readline.rl.console.SetConsoleMode(handle, cur_mode.value | ENABLE_VIRTUAL_TERMINAL_PROCESSING):
+                # Restore the original mode when we exit
+                atexit.register(readline.rl.console.SetConsoleMode, handle, cur_mode)
+                retVal = True
+
+            return retVal
+
+        # Enable VT100 sequences for stdout and stderr
+        STD_OUT_HANDLE = -11
+        STD_ERROR_HANDLE = -12
+        vt100_support = (enable_win_vt100(readline.rl.console.GetStdHandle(STD_OUT_HANDLE)) and
+                         enable_win_vt100(readline.rl.console.GetStdHandle(STD_ERROR_HANDLE)))
+
     ############################################################################################################
     # pyreadline is incomplete in terms of the Python readline API. Add the missing functions we need.
     ############################################################################################################
@@ -74,9 +115,13 @@ def pyreadline_remove_history_item(pos: int) -> None:
         import ctypes
         readline_lib = ctypes.CDLL(readline.__file__)
 
+        # Check if we are running in a terminal
+        if sys.stdout.isatty():
+            vt100_support = True
+
 
 # noinspection PyProtectedMember
-def rl_force_redisplay() -> None:
+def rl_force_redisplay() -> None:  # pragma: no cover
     """
     Causes readline to display the prompt and input text wherever the cursor is and start
     reading input from this location. This is the proper way to restore the input line after
@@ -85,14 +130,77 @@ def rl_force_redisplay() -> None:
     if not sys.stdout.isatty():
         return
 
-    if rl_type == RlType.GNU:  # pragma: no cover
+    if rl_type == RlType.GNU:
         readline_lib.rl_forced_update_display()
 
         # After manually updating the display, readline asks that rl_display_fixed be set to 1 for efficiency
         display_fixed = ctypes.c_int.in_dll(readline_lib, "rl_display_fixed")
         display_fixed.value = 1
 
-    elif rl_type == RlType.PYREADLINE:  # pragma: no cover
+    elif rl_type == RlType.PYREADLINE:
         # Call _print_prompt() first to set the new location of the prompt
         readline.rl.mode._print_prompt()
         readline.rl.mode._update_line()
+
+
+# noinspection PyProtectedMember
+def rl_get_point() -> int:  # pragma: no cover
+    """
+    Returns the offset of the current cursor position in rl_line_buffer
+    """
+    if rl_type == RlType.GNU:
+        return ctypes.c_int.in_dll(readline_lib, "rl_point").value
+
+    elif rl_type == RlType.PYREADLINE:
+        return readline.rl.mode.l_buffer.point
+
+    else:
+        return 0
+
+
+# noinspection PyProtectedMember
+def rl_set_prompt(prompt: str) -> None:  # pragma: no cover
+    """
+    Sets readline's prompt
+    :param prompt: the new prompt value
+    """
+    safe_prompt = rl_make_safe_prompt(prompt)
+
+    if rl_type == RlType.GNU:
+        encoded_prompt = bytes(safe_prompt, encoding='utf-8')
+        readline_lib.rl_set_prompt(encoded_prompt)
+
+    elif rl_type == RlType.PYREADLINE:
+        readline.rl._set_prompt(safe_prompt)
+
+
+def rl_make_safe_prompt(prompt: str) -> str:  # pragma: no cover
+    """Overcome bug in GNU Readline in relation to calculation of prompt length in presence of ANSI escape codes.
+
+    :param prompt: original prompt
+    :return: prompt safe to pass to GNU Readline
+    """
+    if rl_type == RlType.GNU:
+        # start code to tell GNU Readline about beginning of invisible characters
+        start = "\x01"
+
+        # end code to tell GNU Readline about end of invisible characters
+        end = "\x02"
+
+        escaped = False
+        result = ""
+
+        for c in prompt:
+            if c == "\x1b" and not escaped:
+                result += start + c
+                escaped = True
+            elif c.isalpha() and escaped:
+                result += c + end
+                escaped = False
+            else:
+                result += c
+
+        return result
+
+    else:
+        return prompt

cmd2/rl_utils.py

@@ -209,3 +209,33 @@ 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()``.
+
+
+Asynchronous Feedback
+=====================
+``cmd2`` provides two functions to provide asynchronous feedback to the user without interfering with
+the command line. This means the feedback is provided to the user when they are still entering text at
+the prompt. To use this functionality, the application must be running in a terminal that supports
+VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support these.
+
+async_alert()
+    Used to display an important message to the user while they are at the prompt in between commands.
+    To the user it appears as if an alert message is printed above the prompt and their current input
+    text and cursor location is left alone.
+
+async_update_prompt()
+    Updates the prompt while the user is still typing at it. This is good for alerting the user to system
+    changes dynamically in between commands. For instance you could alter the color of the prompt to indicate
+    a system status or increase a counter to report an event.
+
+``cmd2`` also provides a function to change the title of the terminal window. This feature requires the
+application be running in a terminal that supports VT100 control characters. Linux, Mac, and Windows 10 and
+greater all support these.
+
+set_window_title()
+    Sets the terminal window title
+
+
+The easiest way to understand these functions is to see the AsyncPrinting_ example for a demonstration.
+
+.. _AsyncPrinting: https://github.com/python-cmd2/cmd2/blob/master/examples/async_printing.py