add stop column highlighting support

This change introduces optional marking of the column within a source
line where a thread is stopped.  This marking will show up when the
source code for a thread stop is displayed, when the debug info
knows the column information, and if the optional column marking is
enabled.

There are two separate methods for handling the marking of the stop
column:

* via ANSI terminal codes, which are added inline to the source line
  display.  The default ANSI mark-up is to underline the column.

* via a pure text-based caret that is added in the appropriate column
  in a newly-inserted blank line underneath the source line in
  question.

There are some new options that control how this all works.

* settings set stop-show-column

  This takes one of 4 values:

  * ansi-or-caret: use the ANSI terminal code mechanism if LLDB
    is running with color enabled; if not, use the caret-based,
    pure text method (see the "caret" mode below).

  * ansi: only use the ANSI terminal code mechanism to highlight
    the stop line.  If LLDB is running with color disabled, no
    stop column marking will occur.

  * caret: only use the pure text caret method, which introduces
    a newly-inserted line underneath the current line, where
    the only character in the new line is a caret that highlights
    the stop column in question.

  * none: no stop column marking will be attempted.

* settings set stop-show-column-ansi-prefix

  This is a text format that indicates the ANSI formatting
  code to insert into the stream immediately preceding the
  column where the stop column character will be marked up.
  It defaults to ${ansi.underline}; however, it can contain
  any valid LLDB format codes, e.g.

      ${ansi.fg.red}${ansi.bold}${ansi.underline}

* settings set stop-show-column-ansi-suffix

  This is the text format that specifies the ANSI terminal
  codes to end the markup that was started with the prefix
  described above.  It defaults to: ${ansi.normal}.  This
  should be sufficient for the common cases.

Significant leg-work was done by Adrian Prantl.  (Thanks, Adrian!)

differential review: https://reviews.llvm.org/D20835

reviewers: clayborg, jingham
llvm-svn: 282105

4 files changed, 65 insertions, 14 deletions

diff --git a/lldb/packages/Python/lldbsuite/test/functionalities/load_unload/TestLoadUnload.py b/lldb/packages/Python/lldbsuite/test/functionalities/load_unload/TestLoadUnload.py
index 8b3ce441ced..027968a727f 100644
--- a/lldb/packages/Python/lldbsuite/test/functionalities/load_unload/TestLoadUnload.py
+++ b/lldb/packages/Python/lldbsuite/test/functionalities/load_unload/TestLoadUnload.py
@@ -158,6 +158,10 @@ class LoadUnloadTestCase(TestBase):
         exe = os.path.join(os.getcwd(), "a.out")
         self.runCmd("file " + exe, CURRENT_EXECUTABLE_SET)
 
+        # Shut off ANSI color usage so we don't get ANSI escape sequences
+        # mixed in with stop locations.
+        self.dbg.SetUseColor(False)
+
         if self.platformIsDarwin():
             dylibName = 'libloadunload_d.dylib'
             dsymName = 'libloadunload_d.dylib.dSYM'
diff --git a/lldb/packages/Python/lldbsuite/test/lldbtest.py b/lldb/packages/Python/lldbsuite/test/lldbtest.py
index ae355a80c52..104cb619885 100644
--- a/lldb/packages/Python/lldbsuite/test/lldbtest.py
+++ b/lldb/packages/Python/lldbsuite/test/lldbtest.py
@@ -228,6 +228,10 @@ def line_number(filename, string_to_match):
         "Unable to find '%s' within file %s" %
         (string_to_match, filename))
 
+def get_line(filename, line_number):
+    """Return the text of the line at the 1-based line number."""
+    with io.open(filename, mode='r', encoding="utf-8") as f:
+        return f.readlines()[line_number - 1]
 
 def pointer_size():
     """Return the pointer size of the host system."""
diff --git a/lldb/packages/Python/lldbsuite/test/settings/TestSettings.py b/lldb/packages/Python/lldbsuite/test/settings/TestSettings.py
index 577cac17753..a8bd57341ed 100644
--- a/lldb/packages/Python/lldbsuite/test/settings/TestSettings.py
+++ b/lldb/packages/Python/lldbsuite/test/settings/TestSettings.py
@@ -527,6 +527,7 @@ class SettingsCommandTestCase(TestBase):
                              "stop-disassembly-display",
                              "stop-line-count-after",
                              "stop-line-count-before",
+                             "stop-show-column",
                              "term-width",
                              "thread-format",
                              "use-external-editor",
diff --git a/lldb/packages/Python/lldbsuite/test/source-manager/TestSourceManager.py b/lldb/packages/Python/lldbsuite/test/source-manager/TestSourceManager.py
index 904f0e7b7b2..31fe5437d1d 100644
--- a/lldb/packages/Python/lldbsuite/test/source-manager/TestSourceManager.py
+++ b/lldb/packages/Python/lldbsuite/test/source-manager/TestSourceManager.py
@@ -10,7 +10,7 @@ o test_modify_source_file_while_debugging:
 """
 
 from __future__ import print_function
-
+import re
 
 import lldb
 from lldbsuite.test.decorators import *
@@ -18,19 +18,37 @@ from lldbsuite.test.lldbtest import *
 from lldbsuite.test import lldbutil
 
 
+def ansi_underline_surround_regex(inner_regex_text):
+    # return re.compile(r"\[4m%s\[0m" % inner_regex_text)
+    return "4.+\033\\[4m%s\033\\[0m" % inner_regex_text
+
+
 class SourceManagerTestCase(TestBase):
 
     mydir = TestBase.compute_mydir(__file__)
 
+    SOURCE_FILE = 'main.c'
+
+    NO_DEBUG_INFO_TESTCASE = True
+
     def setUp(self):
         # Call super's setUp().
         TestBase.setUp(self)
         # Find the line number to break inside main().
-        self.line = line_number('main.c', '// Set break point at this line.')
-
-    @add_test_categories(['pyapi'])
-    def test_display_source_python(self):
-        """Test display of source using the SBSourceManager API."""
+        self.line = line_number(self.SOURCE_FILE, '// Set break point at this line.')
+
+    def get_expected_stop_column_number(self):
+        """Return the 1-based column number of the first non-whitespace
+        character in the breakpoint source line."""
+        stop_line = get_line(self.SOURCE_FILE, self.line)
+        # The number of spaces that must be skipped to get to the first non-
+        # whitespace character --- where we expect the debugger breakpoint
+        # column to be --- is equal to the number of characters that get
+        # stripped off the front when we lstrip it, plus one to specify
+        # the character column after the initial whitespace.
+        return len(stop_line) - len(stop_line.lstrip()) + 1
+
+    def do_display_source_python_api(self, use_color, column_marker_regex):
         self.build()
         exe = os.path.join(os.getcwd(), "a.out")
         self.runCmd("file " + exe, CURRENT_EXECUTABLE_SET)
@@ -39,24 +57,32 @@ class SourceManagerTestCase(TestBase):
         self.assertTrue(target, VALID_TARGET)
 
         # Launch the process, and do not stop at the entry point.
+        args = None
+        envp = None
         process = target.LaunchSimple(
-            None, None, self.get_process_working_directory())
+            args, envp, self.get_process_working_directory())
+        self.assertIsNotNone(process)
 
         #
         # Exercise Python APIs to display source lines.
         #
 
+        # Setup whether we should use ansi escape sequences, including color
+        # and styles such as underline.
+        self.dbg.SetUseColor(use_color)
+
         # Create the filespec for 'main.c'.
         filespec = lldb.SBFileSpec('main.c', False)
         source_mgr = self.dbg.GetSourceManager()
         # Use a string stream as the destination.
         stream = lldb.SBStream()
-        source_mgr.DisplaySourceLinesWithLineNumbers(filespec,
-                                                     self.line,
-                                                     2,  # context before
-                                                     2,  # context after
-                                                     "=>",  # prefix for current line
-                                                     stream)
+        column = self.get_expected_stop_column_number()
+        context_before = 2
+        context_after = 2
+        current_line_prefix = "=>"
+        source_mgr.DisplaySourceLinesWithLineNumbersAndColumn(
+            filespec, self.line, column, context_before, context_after,
+            current_line_prefix, stream)
 
         #    2
         #    3    int main(int argc, char const *argv[]) {
@@ -65,12 +91,28 @@ class SourceManagerTestCase(TestBase):
         #    6    }
         self.expect(stream.GetData(), "Source code displayed correctly",
                     exe=False,
-                    patterns=['=> %d.*Hello world' % self.line])
+                    patterns=['=> %d.*Hello world' % self.line,
+                              column_marker_regex])
 
         # Boundary condition testings for SBStream().  LLDB should not crash!
         stream.Print(None)
         stream.RedirectToFile(None, True)
 
+    @add_test_categories(['pyapi'])
+    def test_display_source_python_dumb_terminal(self):
+        """Test display of source using the SBSourceManager API, using a
+        dumb terminal and thus no color support (the default)."""
+        use_color = False
+        self.do_display_source_python_api(use_color, r"\s+\^")
+
+    @add_test_categories(['pyapi'])
+    def test_display_source_python_ansi_terminal(self):
+        """Test display of source using the SBSourceManager API, using a
+        dumb terminal and thus no color support (the default)."""
+        use_color = True
+        underline_regex = ansi_underline_surround_regex(r".")
+        self.do_display_source_python_api(use_color, underline_regex)
+
     def test_move_and_then_display_source(self):
         """Test that target.source-map settings work by moving main.c to hidden/main.c."""
         self.build()