gdb/completer.h

   1 /* Header for GDB line completion.
   2    Copyright (C) 2000-2019 Free Software Foundation, Inc.
   3
   4    This program is free software; you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation; either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  16
  17 #if !defined (COMPLETER_H)
  18 #define COMPLETER_H 1
  19
  20 #include "common/gdb_vecs.h"
  21 #include "command.h"
  22
  23 /* Types of functions in struct match_list_displayer.  */
  24
  25 struct match_list_displayer;
  26
  27 typedef void mld_crlf_ftype (const struct match_list_displayer *);
  28 typedef void mld_putch_ftype (const struct match_list_displayer *, int);
  29 typedef void mld_puts_ftype (const struct match_list_displayer *,
  30                              const char *);
  31 typedef void mld_flush_ftype (const struct match_list_displayer *);
  32 typedef void mld_erase_entire_line_ftype (const struct match_list_displayer *);
  33 typedef void mld_beep_ftype (const struct match_list_displayer *);
  34 typedef int mld_read_key_ftype (const struct match_list_displayer *);
  35
  36 /* Interface between CLI/TUI and gdb_match_list_displayer.  */
  37
  38 struct match_list_displayer
  39 {
  40   /* The screen dimensions to work with when displaying matches.  */
  41   int height, width;
  42
  43   /* Print cr,lf.  */
  44   mld_crlf_ftype *crlf;
  45
  46   /* Not "putc" to avoid issues where it is a stdio macro.  Sigh.  */
  47   mld_putch_ftype *putch;
  48
  49   /* Print a string.  */
  50   mld_puts_ftype *puts;
  51
  52   /* Flush all accumulated output.  */
  53   mld_flush_ftype *flush;
  54
  55   /* Erase the currently line on the terminal (but don't discard any text the
  56      user has entered, readline may shortly re-print it).  */
  57   mld_erase_entire_line_ftype *erase_entire_line;
  58
  59   /* Ring the bell.  */
  60   mld_beep_ftype *beep;
  61
  62   /* Read one key.  */
  63   mld_read_key_ftype *read_key;
  64 };
  65
  66 /* A list of completion candidates.  Each element is a malloc string,
  67    because ownership of the strings is transferred to readline, which
  68    calls free on each element.  */
  69 typedef std::vector<gdb::unique_xmalloc_ptr<char>> completion_list;
  70
  71 /* The result of a successful completion match.  When doing symbol
  72    comparison, we use the symbol search name for the symbol name match
  73    check, but the matched name that is shown to the user may be
  74    different.  For example, Ada uses encoded names for lookup, but
  75    then wants to decode the symbol name to show to the user, and also
  76    in some cases wrap the matched name in "<sym>" (meaning we can't
  77    always use the symbol's print name).  */
  78
  79 class completion_match
  80 {
  81 public:
  82   /* Get the completion match result.  See m_match/m_storage's
  83      descriptions.  */
  84   const char *match ()
  85   { return m_match; }
  86
  87   /* Set the completion match result.  See m_match/m_storage's
  88      descriptions.  */
  89   void set_match (const char *match)
  90   { m_match = match; }
  91
  92   /* Get temporary storage for generating a match result, dynamically.
  93      The built string is only good until the next clear() call.  I.e.,
  94      good until the next symbol comparison.  */
  95   std::string &storage ()
  96   { return m_storage; }
  97
  98   /* Prepare for another completion matching sequence.  */
  99   void clear ()
 100   {
 101     m_match = NULL;
 102     m_storage.clear ();
 103   }
 104
 105 private:
 106   /* The completion match result.  This can either be a pointer into
 107      M_STORAGE string, or it can be a pointer into the some other
 108      string that outlives the completion matching sequence (usually, a
 109      pointer to a symbol's name).  */
 110   const char *m_match;
 111
 112   /* Storage a symbol comparison routine can use for generating a
 113      match result, dynamically.  The built string is only good until
 114      the next clear() call.  I.e., good until the next symbol
 115      comparison.  */
 116   std::string m_storage;
 117 };
 118
 119 /* The result of a successful completion match, but for least common
 120    denominator (LCD) computation.  Some completers provide matches
 121    that don't start with the completion "word".  E.g., completing on
 122    "b push_ba" on a C++ program usually completes to
 123    std::vector<...>::push_back, std::string::push_back etc.  In such
 124    case, the symbol comparison routine will set the LCD match to point
 125    into the "push_back" substring within the symbol's name string.
 126    Also, in some cases, the symbol comparison routine will want to
 127    ignore parts of the symbol name for LCD purposes, such as for
 128    example symbols with abi tags in C++.  In such cases, the symbol
 129    comparison routine will set MARK_IGNORED_RANGE to mark the ignored
 130    substrings of the matched string.  The resulting LCD string with
 131    the ignored parts stripped out is computed at the end of a
 132    completion match sequence iff we had a positive match.  */
 133
 134 class completion_match_for_lcd
 135 {
 136 public:
 137   /* Get the resulting LCD, after a successful match.  */
 138   const char *match ()
 139   { return m_match; }
 140
 141   /* Set the match for LCD.  See m_match's description.  */
 142   void set_match (const char *match)
 143   { m_match = match; }
 144
 145   /* Mark the range between [BEGIN, END) as ignored.  */
 146   void mark_ignored_range (const char *begin, const char *end)
 147   { m_ignored_ranges.emplace_back (begin, end); }
 148
 149   /* Get the resulting LCD, after a successful match.  If there are
 150      ignored ranges, then this builds a new string with the ignored
 151      parts removed (and stores it internally).  As such, the result of
 152      this call is only good for the current completion match
 153      sequence.  */
 154   const char *finish ()
 155   {
 156     if (m_ignored_ranges.empty ())
 157       return m_match;
 158     else
 159       {
 160         m_finished_storage.clear ();
 161
 162         const char *prev = m_match;
 163         for (const auto &range : m_ignored_ranges)
 164           {
 165             m_finished_storage.append (prev, range.first);
 166             prev = range.second;
 167           }
 168         m_finished_storage.append (prev);
 169
 170         return m_finished_storage.c_str ();
 171       }
 172   }
 173
 174   /* Prepare for another completion matching sequence.  */
 175   void clear ()
 176   {
 177     m_match = NULL;
 178     m_ignored_ranges.clear ();
 179   }
 180
 181 private:
 182   /* The completion match result for LCD.  This is usually either a
 183      pointer into to a substring within a symbol's name, or to the
 184      storage of the pairing completion_match object.  */
 185   const char *m_match;
 186
 187   /* The ignored substring ranges within M_MATCH.  E.g., if we were
 188      looking for completion matches for C++ functions starting with
 189        "functio"
 190      and successfully match:
 191        "function[abi:cxx11](int)"
 192      the ignored ranges vector will contain an entry that delimits the
 193      "[abi:cxx11]" substring, such that calling finish() results in:
 194        "function(int)"
 195    */
 196   std::vector<std::pair<const char *, const char *>> m_ignored_ranges;
 197
 198   /* Storage used by the finish() method, if it has to compute a new
 199      string.  */
 200   std::string m_finished_storage;
 201 };
 202
 203 /* Convenience aggregate holding info returned by the symbol name
 204    matching routines (see symbol_name_matcher_ftype).  */
 205 struct completion_match_result
 206 {
 207   /* The completion match candidate.  */
 208   completion_match match;
 209
 210   /* The completion match, for LCD computation purposes.  */
 211   completion_match_for_lcd match_for_lcd;
 212
 213   /* Convenience that sets both MATCH and MATCH_FOR_LCD.  M_FOR_LCD is
 214      optional.  If not specified, defaults to M.  */
 215   void set_match (const char *m, const char *m_for_lcd = NULL)
 216   {
 217     match.set_match (m);
 218     if (m_for_lcd == NULL)
 219       match_for_lcd.set_match (m);
 220     else
 221       match_for_lcd.set_match (m_for_lcd);
 222   }
 223 };
 224
 225 /* The final result of a completion that is handed over to either
 226    readline or the "completion" command (which pretends to be
 227    readline).  Mainly a wrapper for a readline-style match list array,
 228    though other bits of info are included too.  */
 229
 230 struct completion_result
 231 {
 232   /* Create an empty result.  */
 233   completion_result ();
 234
 235   /* Create a result.  */
 236   completion_result (char **match_list, size_t number_matches,
 237                      bool completion_suppress_append);
 238
 239   /* Destroy a result.  */
 240   ~completion_result ();
 241
 242   DISABLE_COPY_AND_ASSIGN (completion_result);
 243
 244   /* Move a result.  */
 245   completion_result (completion_result &&rhs);
 246
 247   /* Release ownership of the match list array.  */
 248   char **release_match_list ();
 249
 250   /* Sort the match list.  */
 251   void sort_match_list ();
 252
 253 private:
 254   /* Destroy the match list array and its contents.  */
 255   void reset_match_list ();
 256
 257 public:
 258   /* (There's no point in making these fields private, since the whole
 259      point of this wrapper is to build data in the layout expected by
 260      readline.  Making them private would require adding getters for
 261      the "complete" command, which would expose the same
 262      implementation details anyway.)  */
 263
 264   /* The match list array, in the format that readline expects.
 265      match_list[0] contains the common prefix.  The real match list
 266      starts at index 1.  The list is NULL terminated.  If there's only
 267      one match, then match_list[1] is NULL.  If there are no matches,
 268      then this is NULL.  */
 269   char **match_list;
 270   /* The number of matched completions in MATCH_LIST.  Does not
 271      include the NULL terminator or the common prefix.  */
 272   size_t number_matches;
 273
 274   /* Whether readline should suppress appending a whitespace, when
 275      there's only one possible completion.  */
 276   bool completion_suppress_append;
 277 };
 278
 279 /* Object used by completers to build a completion match list to hand
 280    over to readline.  It tracks:
 281
 282    - How many unique completions have been generated, to terminate
 283      completion list generation early if the list has grown to a size
 284      so large as to be useless.  This helps avoid GDB seeming to lock
 285      up in the event the user requests to complete on something vague
 286      that necessitates the time consuming expansion of many symbol
 287      tables.
 288
 289    - The completer's idea of least common denominator (aka the common
 290      prefix) between all completion matches to hand over to readline.
 291      Some completers provide matches that don't start with the
 292      completion "word".  E.g., completing on "b push_ba" on a C++
 293      program usually completes to std::vector<...>::push_back,
 294      std::string::push_back etc.  If all matches happen to start with
 295      "std::", then readline would figure out that the lowest common
 296      denominator is "std::", and thus would do a partial completion
 297      with that.  I.e., it would replace "push_ba" in the input buffer
 298      with "std::", losing the original "push_ba", which is obviously
 299      undesirable.  To avoid that, such completers pass the substring
 300      of the match that matters for common denominator computation as
 301      MATCH_FOR_LCD argument to add_completion.  The end result is
 302      passed to readline in gdb_rl_attempted_completion_function.
 303
 304    - The custom word point to hand over to readline, for completers
 305      that parse the input string in order to dynamically adjust
 306      themselves depending on exactly what they're completing.  E.g.,
 307      the linespec completer needs to bypass readline's too-simple word
 308      breaking algorithm.
 309 */
 310 class completion_tracker
 311 {
 312 public:
 313   completion_tracker ();
 314   ~completion_tracker ();
 315
 316   DISABLE_COPY_AND_ASSIGN (completion_tracker);
 317
 318   /* Add the completion NAME to the list of generated completions if
 319      it is not there already.  If too many completions were already
 320      found, this throws an error.  */
 321   void add_completion (gdb::unique_xmalloc_ptr<char> name,
 322                        completion_match_for_lcd *match_for_lcd = NULL,
 323                        const char *text = NULL, const char *word = NULL);
 324
 325   /* Add all completions matches in LIST.  Elements are moved out of
 326      LIST.  */
 327   void add_completions (completion_list &&list);
 328
 329   /* Set the quote char to be appended after a unique completion is
 330      added to the input line.  Set to '\0' to clear.  See
 331      m_quote_char's description.  */
 332   void set_quote_char (int quote_char)
 333   { m_quote_char = quote_char; }
 334
 335   /* The quote char to be appended after a unique completion is added
 336      to the input line.  Returns '\0' if no quote char has been set.
 337      See m_quote_char's description.  */
 338   int quote_char () { return m_quote_char; }
 339
 340   /* Tell the tracker that the current completer wants to provide a
 341      custom word point instead of a list of a break chars, in the
 342      handle_brkchars phase.  Such completers must also compute their
 343      completions then.  */
 344   void set_use_custom_word_point (bool enable)
 345   { m_use_custom_word_point = enable; }
 346
 347   /* Whether the current completer computes a custom word point.  */
 348   bool use_custom_word_point () const
 349   { return m_use_custom_word_point; }
 350
 351   /* The custom word point.  */
 352   int custom_word_point () const
 353   { return m_custom_word_point; }
 354
 355   /* Set the custom word point to POINT.  */
 356   void set_custom_word_point (int point)
 357   { m_custom_word_point = point; }
 358
 359   /* Advance the custom word point by LEN.  */
 360   void advance_custom_word_point_by (size_t len);
 361
 362   /* Whether to tell readline to skip appending a whitespace after the
 363      completion.  See m_suppress_append_ws.  */
 364   bool suppress_append_ws () const
 365   { return m_suppress_append_ws; }
 366
 367   /* Set whether to tell readline to skip appending a whitespace after
 368      the completion.  See m_suppress_append_ws.  */
 369   void set_suppress_append_ws (bool suppress)
 370   { m_suppress_append_ws = suppress; }
 371
 372   /* Return true if we only have one completion, and it matches
 373      exactly the completion word.  I.e., completing results in what we
 374      already have.  */
 375   bool completes_to_completion_word (const char *word);
 376
 377   /* Get a reference to the shared (between all the multiple symbol
 378      name comparison calls) completion_match_result object, ready for
 379      another symbol name match sequence.  */
 380   completion_match_result &reset_completion_match_result ()
 381   {
 382     completion_match_result &res = m_completion_match_result;
 383
 384     /* Clear any previous match.  */
 385     res.match.clear ();
 386     res.match_for_lcd.clear ();
 387     return m_completion_match_result;
 388   }
 389
 390   /* True if we have any completion match recorded.  */
 391   bool have_completions () const
 392   { return !m_entries_vec.empty (); }
 393
 394   /* Discard the current completion match list and the current
 395      LCD.  */
 396   void discard_completions ();
 397
 398   /* Build a completion_result containing the list of completion
 399      matches to hand over to readline.  The parameters are as in
 400      rl_attempted_completion_function.  */
 401   completion_result build_completion_result (const char *text,
 402                                              int start, int end);
 403
 404 private:
 405
 406   /* Add the completion NAME to the list of generated completions if
 407      it is not there already.  If false is returned, too many
 408      completions were found.  */
 409   bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name,
 410                              completion_match_for_lcd *match_for_lcd,
 411                              const char *text, const char *word);
 412
 413   /* Given a new match, recompute the lowest common denominator (LCD)
 414      to hand over to readline.  Normally readline computes this itself
 415      based on the whole set of completion matches.  However, some
 416      completers want to override readline, in order to be able to
 417      provide a LCD that is not really a prefix of the matches, but the
 418      lowest common denominator of some relevant substring of each
 419      match.  E.g., "b push_ba" completes to
 420      "std::vector<..>::push_back", "std::string::push_back", etc., and
 421      in this case we want the lowest common denominator to be
 422      "push_back" instead of "std::".  */
 423   void recompute_lowest_common_denominator
 424     (gdb::unique_xmalloc_ptr<char> &&new_match);
 425
 426   /* Completion match outputs returned by the symbol name matching
 427      routines (see symbol_name_matcher_ftype).  These results are only
 428      valid for a single match call.  This is here in order to be able
 429      to conveniently share the same storage among all the calls to the
 430      symbol name matching routines.  */
 431   completion_match_result m_completion_match_result;
 432
 433   /* The completion matches found so far, in a vector.  */
 434   completion_list m_entries_vec;
 435
 436   /* The completion matches found so far, in a hash table, for
 437      duplicate elimination as entries are added.  Otherwise the user
 438      is left scratching his/her head: readline and complete_command
 439      will remove duplicates, and if removal of duplicates there brings
 440      the total under max_completions the user may think gdb quit
 441      searching too early.  */
 442   htab_t m_entries_hash;
 443
 444   /* If non-zero, then this is the quote char that needs to be
 445      appended after completion (iff we have a unique completion).  We
 446      don't rely on readline appending the quote char as delimiter as
 447      then readline wouldn't append the ' ' after the completion.
 448      I.e., we want this:
 449
 450       before tab: "b 'function("
 451       after tab:  "b 'function()' "
 452   */
 453   int m_quote_char = '\0';
 454
 455   /* If true, the completer has its own idea of "word" point, and
 456      doesn't want to rely on readline computing it based on brkchars.
 457      Set in the handle_brkchars phase.  */
 458   bool m_use_custom_word_point = false;
 459
 460   /* The completer's idea of where the "word" we were looking at is
 461      relative to RL_LINE_BUFFER.  This is advanced in the
 462      handle_brkchars phase as the completer discovers potential
 463      completable words.  */
 464   int m_custom_word_point = 0;
 465
 466   /* If true, tell readline to skip appending a whitespace after the
 467      completion.  Automatically set if we have a unique completion
 468      that already has a space at the end.  A completer may also
 469      explicitly set this.  E.g., the linespec completer sets this when
 470      the completion ends with the ":" separator between filename and
 471      function name.  */
 472   bool m_suppress_append_ws = false;
 473
 474   /* Our idea of lowest common denominator to hand over to readline.
 475      See intro.  */
 476   char *m_lowest_common_denominator = NULL;
 477
 478   /* If true, the LCD is unique.  I.e., all completions had the same
 479      MATCH_FOR_LCD substring, even if the completions were different.
 480      For example, if "break function<tab>" found "a::function()" and
 481      "b::function()", the LCD will be "function()" in both cases and
 482      so we want to tell readline to complete the line with
 483      "function()", instead of showing all the possible
 484      completions.  */
 485   bool m_lowest_common_denominator_unique = false;
 486 };
 487
 488 /* Return a string to hand off to readline as a completion match
 489    candidate, potentially composed of parts of MATCH_NAME and of
 490    TEXT/WORD.  For a description of TEXT/WORD see completer_ftype.  */
 491
 492 extern gdb::unique_xmalloc_ptr<char>
 493   make_completion_match_str (const char *match_name,
 494                              const char *text, const char *word);
 495
 496 /* Like above, but takes ownership of MATCH_NAME (i.e., can
 497    reuse/return it).  */
 498
 499 extern gdb::unique_xmalloc_ptr<char>
 500   make_completion_match_str (gdb::unique_xmalloc_ptr<char> &&match_name,
 501                              const char *text, const char *word);
 502
 503 extern void gdb_display_match_list (char **matches, int len, int max,
 504                                     const struct match_list_displayer *);
 505
 506 extern const char *get_max_completions_reached_message (void);
 507
 508 extern void complete_line (completion_tracker &tracker,
 509                            const char *text,
 510                            const char *line_buffer,
 511                            int point);
 512
 513 /* Find the bounds of the word in TEXT for completion purposes, and
 514    return a pointer to the end of the word.  Calls the completion
 515    machinery for a handle_brkchars phase (using TRACKER) to figure out
 516    the right work break characters for the command in TEXT.
 517    QUOTE_CHAR, if non-null, is set to the opening quote character if
 518    we found an unclosed quoted substring, '\0' otherwise.  */
 519 extern const char *completion_find_completion_word (completion_tracker &tracker,
 520                                                     const char *text,
 521                                                     int *quote_char);
 522
 523
 524 /* Assuming TEXT is an expression in the current language, find the
 525    completion word point for TEXT, emulating the algorithm readline
 526    uses to find the word point, using the current language's word
 527    break characters.  */
 528
 529 const char *advance_to_expression_complete_word_point
 530   (completion_tracker &tracker, const char *text);
 531
 532 extern char **gdb_rl_attempted_completion_function (const char *text,
 533                                                     int start, int end);
 534
 535 extern void noop_completer (struct cmd_list_element *,
 536                             completion_tracker &tracker,
 537                             const char *, const char *);
 538
 539 extern void filename_completer (struct cmd_list_element *,
 540                                 completion_tracker &tracker,
 541                                 const char *, const char *);
 542
 543 extern void expression_completer (struct cmd_list_element *,
 544                                   completion_tracker &tracker,
 545                                   const char *, const char *);
 546
 547 extern void location_completer (struct cmd_list_element *,
 548                                 completion_tracker &tracker,
 549                                 const char *, const char *);
 550
 551 extern void symbol_completer (struct cmd_list_element *,
 552                               completion_tracker &tracker,
 553                               const char *, const char *);
 554
 555 extern void command_completer (struct cmd_list_element *,
 556                                completion_tracker &tracker,
 557                                const char *, const char *);
 558
 559 extern void signal_completer (struct cmd_list_element *,
 560                               completion_tracker &tracker,
 561                               const char *, const char *);
 562
 563 extern void reg_or_group_completer (struct cmd_list_element *,
 564                                     completion_tracker &tracker,
 565                                     const char *, const char *);
 566
 567 extern void reggroup_completer (struct cmd_list_element *,
 568                                 completion_tracker &tracker,
 569                                 const char *, const char *);
 570
 571 extern const char *get_gdb_completer_quote_characters (void);
 572
 573 extern char *gdb_completion_word_break_characters (void);
 574
 575 /* Set the word break characters array to BREAK_CHARS.  This function
 576    is useful as const-correct alternative to direct assignment to
 577    rl_completer_word_break_characters, which is "char *",
 578    not "const char *".  */
 579 extern void set_rl_completer_word_break_characters (const char *break_chars);
 580
 581 /* Get the matching completer_handle_brkchars_ftype function for FN.
 582    FN is one of the core completer functions above (filename,
 583    location, symbol, etc.).  This function is useful for cases when
 584    the completer doesn't know the type of the completion until some
 585    calculation is done (e.g., for Python functions).  */
 586
 587 extern completer_handle_brkchars_ftype *
 588   completer_handle_brkchars_func_for_completer (completer_ftype *fn);
 589
 590 /* Exported to linespec.c */
 591
 592 /* Return a list of all source files whose names begin with matching
 593    TEXT.  */
 594 extern completion_list complete_source_filenames (const char *text);
 595
 596 /* Complete on expressions.  Often this means completing on symbol
 597    names, but some language parsers also have support for completing
 598    field names.  */
 599 extern void complete_expression (completion_tracker &tracker,
 600                                  const char *text, const char *word);
 601
 602 extern const char *skip_quoted_chars (const char *, const char *,
 603                                       const char *);
 604
 605 extern const char *skip_quoted (const char *);
 606
 607 /* Maximum number of candidates to consider before the completer
 608    bails by throwing MAX_COMPLETIONS_REACHED_ERROR.  Negative values
 609    disable limiting.  */
 610
 611 extern int max_completions;
 612
 613 #endif /* defined (COMPLETER_H) */