Handle custom completion match prefix / LCD

A following patch will add support for wild matching for C++ symbols,
making completing on "b push_ba" on a C++ program complete to
std::vector<...>::push_back, std::string::push_back etc., like:

 (gdb) b push_ba[TAB]
 std::vector<...>::push_back(....)
 std::string<...>::push_back(....)

Currently, we compute the "lowest common denominator" between all
completion candidates (what the input line is adjusted to) as the
common prefix of all matches.  That's problematic with wild matching
as above, as then we'd end up with TAB changing the input line to
"b std::", losing the original input, like:

 (gdb) b push_ba[TAB]
 std::vector<...>::push_back(....)
 std::string<...>::push_back(....)
 (gdb) b std::

while obviously we'd want it to adjust itself to "b push_back(" instead:

 (gdb) b push_ba[TAB]
 std::vector<...>::push_back(....)
 std::string<...>::push_back(....)
 (gdb) b push_back(

This patch adds the core code necessary to support this, though
nothing really makes use of it yet in this patch.

gdb/ChangeLog:
2017-11-29  Pedro Alves  <palves@redhat.com>

	* ada-lang.c (ada_lookup_name_info::matches): Change type of
	parameter from completion_match to completion_match_result.
	Adjust.
	(do_wild_match, do_full_match, ada_symbol_name_matches): Likewise.
	* completer.c (completion_tracker::maybe_add_completion): Add
	match_for_lcd parameter and use it.
	(completion_tracker::add_completion): Likewise.
	* completer.h (class completion_match_for_lcd): New class.
	(completion_match_result::match_for_lcd): New field.
	(completion_match_result::set_match): New method.
	(completion_tracker): Add comments.
	(completion_tracker::add_completion): Add match_for_lcd parameter.
	(completion_tracker::reset_completion_match_result): Reset
	match_for_lcd too.
	(completion_tracker::maybe_add_completion): Add match_for_lcd
	parameter.
	(completion_tracker::m_lowest_common_denominator_unique): Extend
	comments.
	* cp-support.c (cp_symbol_name_matches_1)
	(cp_fq_symbol_name_matches): Change type of parameter from
	completion_match to completion_match_result.  Adjust.
	* language.c (default_symbol_name_matcher): Change type of
	parameter from completion_match to completion_match_result.
	Adjust.
	* language.h (completion_match_for_lcd): Forward declare.
	(default_symbol_name_matcher): Change type of parameter from
	completion_match to completion_match_result.
	* symtab.c (compare_symbol_name): Adjust.
	(completion_list_add_name): Pass the match_for_lcd to the tracker.
	* symtab.h (ada_lookup_name_info::matches): Change type of
	parameter from completion_match to completion_match_result.
	(symbol_name_matcher_ftype): Likewise, and update comments.

gdb/completer.h

@@ -116,12 +116,56 @@ private:
   std::string m_storage;
 };
 
+/* The result of a successful completion match, but for least common
+   denominator (LCD) computation.  Some completers provide matches
+   that don't start with the completion "word".  E.g., completing on
+   "b push_ba" on a C++ program usually completes to
+   std::vector<...>::push_back, std::string::push_back etc.  In such
+   case, the symbol comparison routine will set the LCD match to point
+   into the "push_back" substring within the symbol's name string.  */
+
+class completion_match_for_lcd
+{
+public:
+  /* Set the match for LCD.  See m_match's description.  */
+  void set_match (const char *match)
+  { m_match = match; }
+
+  /* Get the resulting LCD, after a successful match.  */
+  const char *finish ()
+  { return m_match; }
+
+  /* Prepare for another completion matching sequence.  */
+  void clear ()
+  { m_match = NULL; }
+
+private:
+  /* The completion match result for LCD.  This is usually either a
+     pointer into to a substring within a symbol's name, or to the
+     storage of the pairing completion_match object.  */
+  const char *m_match;
+};
+
 /* Convenience aggregate holding info returned by the symbol name
    matching routines (see symbol_name_matcher_ftype).  */
 struct completion_match_result
 {
   /* The completion match candidate.  */
   completion_match match;
+
+  /* The completion match, for LCD computation purposes.  */
+  completion_match_for_lcd match_for_lcd;
+
+  /* Convenience that sets both MATCH and MATCH_FOR_LCD.  M_FOR_LCD is
+     optional.  If not specified, defaults to M.  */
+  void set_match (const char *m, const char *m_for_lcd = NULL)
+  {
+    match.set_match (m);
+    if (m_for_lcd == NULL)
+      match_for_lcd.set_match (m);
+    else
+      match_for_lcd.set_match (m_for_lcd);
+  }
 };
 
 /* The final result of a completion that is handed over to either
@@ -188,6 +232,21 @@ public:
      that necessitates the time consuming expansion of many symbol
      tables.
 
+   - The completer's idea of least common denominator (aka the common
+     prefix) between all completion matches to hand over to readline.
+     Some completers provide matches that don't start with the
+     completion "word".  E.g., completing on "b push_ba" on a C++
+     program usually completes to std::vector<...>::push_back,
+     std::string::push_back etc.  If all matches happen to start with
+     "std::", then readline would figure out that the lowest common
+     denominator is "std::", and thus would do a partial completion
+     with that.  I.e., it would replace "push_ba" in the input buffer
+     with "std::", losing the original "push_ba", which is obviously
+     undesirable.  To avoid that, such completers pass the substring
+     of the match that matters for common denominator computation as
+     MATCH_FOR_LCD argument to add_completion.  The end result is
+     passed to readline in gdb_rl_attempted_completion_function.
+
    - The custom word point to hand over to readline, for completers
      that parse the input string in order to dynamically adjust
      themselves depending on exactly what they're completing.  E.g.,
@@ -205,7 +264,8 @@ public:
   /* Add the completion NAME to the list of generated completions if
      it is not there already.  If too many completions were already
      found, this throws an error.  */
-  void add_completion (gdb::unique_xmalloc_ptr<char> name);
+  void add_completion (gdb::unique_xmalloc_ptr<char> name,
+		       completion_match_for_lcd *match_for_lcd = NULL);
 
   /* Add all completions matches in LIST.  Elements are moved out of
      LIST.  */
@@ -268,6 +328,7 @@ public:
 
     /* Clear any previous match.  */
     res.match.clear ();
+    res.match_for_lcd.clear ();
     return m_completion_match_result;
   }
 
@@ -290,10 +351,19 @@ private:
   /* Add the completion NAME to the list of generated completions if
      it is not there already.  If false is returned, too many
      completions were found.  */
-  bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name);
+  bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name,
+			     completion_match_for_lcd *match_for_lcd);
 
   /* Given a new match, recompute the lowest common denominator (LCD)
-     to hand over to readline.  */
+     to hand over to readline.  Normally readline computes this itself
+     based on the whole set of completion matches.  However, some
+     completers want to override readline, in order to be able to
+     provide a LCD that is not really a prefix of the matches, but the
+     lowest common denominator of some relevant substring of each
+     match.  E.g., "b push_ba" completes to
+     "std::vector<..>::push_back", "std::string::push_back", etc., and
+     in this case we want the lowest common denominator to be
+     "push_back" instead of "std::".  */
   void recompute_lowest_common_denominator (const char *new_match);
 
   /* Completion match outputs returned by the symbol name matching
@@ -348,8 +418,13 @@ private:
      See intro.  */
   char *m_lowest_common_denominator = NULL;
 
-  /* If true, the LCD is unique.  I.e., all completion candidates had
-     the same string.  */
+  /* If true, the LCD is unique.  I.e., all completions had the same
+     MATCH_FOR_LCD substring, even if the completions were different.
+     For example, if "break function<tab>" found "a::function()" and
+     "b::function()", the LCD will be "function()" in both cases and
+     so we want to tell readline to complete the line with
+     "function()", instead of showing all the possible
+     completions.  */
   bool m_lowest_common_denominator_unique = false;
 };