gdb/completer.h

   1 /* Header for GDB line completion.
   2    Copyright (C) 2000-2017 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 "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
 127 class completion_match_for_lcd
 128 {
 129 public:
 130   /* Set the match for LCD.  See m_match's description.  */
 131   void set_match (const char *match)
 132   { m_match = match; }
 133
 134   /* Get the resulting LCD, after a successful match.  */
 135   const char *finish ()
 136   { return m_match; }
 137
 138   /* Prepare for another completion matching sequence.  */
 139   void clear ()
 140   { m_match = NULL; }
 141
 142 private:
 143   /* The completion match result for LCD.  This is usually either a
 144      pointer into to a substring within a symbol's name, or to the
 145      storage of the pairing completion_match object.  */
 146   const char *m_match;
 147 };
 148
 149 /* Convenience aggregate holding info returned by the symbol name
 150    matching routines (see symbol_name_matcher_ftype).  */
 151 struct completion_match_result
 152 {
 153   /* The completion match candidate.  */
 154   completion_match match;
 155
 156   /* The completion match, for LCD computation purposes.  */
 157   completion_match_for_lcd match_for_lcd;
 158
 159   /* Convenience that sets both MATCH and MATCH_FOR_LCD.  M_FOR_LCD is
 160      optional.  If not specified, defaults to M.  */
 161   void set_match (const char *m, const char *m_for_lcd = NULL)
 162   {
 163     match.set_match (m);
 164     if (m_for_lcd == NULL)
 165       match_for_lcd.set_match (m);
 166     else
 167       match_for_lcd.set_match (m_for_lcd);
 168   }
 169 };
 170
 171 /* The final result of a completion that is handed over to either
 172    readline or the "completion" command (which pretends to be
 173    readline).  Mainly a wrapper for a readline-style match list array,
 174    though other bits of info are included too.  */
 175
 176 struct completion_result
 177 {
 178   /* Create an empty result.  */
 179   completion_result ();
 180
 181   /* Create a result.  */
 182   completion_result (char **match_list, size_t number_matches,
 183                      bool completion_suppress_append);
 184
 185   /* Destroy a result.  */
 186   ~completion_result ();
 187
 188   DISABLE_COPY_AND_ASSIGN (completion_result);
 189
 190   /* Move a result.  */
 191   completion_result (completion_result &&rhs);
 192
 193   /* Release ownership of the match list array.  */
 194   char **release_match_list ();
 195
 196   /* Sort the match list.  */
 197   void sort_match_list ();
 198
 199 private:
 200   /* Destroy the match list array and its contents.  */
 201   void reset_match_list ();
 202
 203 public:
 204   /* (There's no point in making these fields private, since the whole
 205      point of this wrapper is to build data in the layout expected by
 206      readline.  Making them private would require adding getters for
 207      the "complete" command, which would expose the same
 208      implementation details anyway.)  */
 209
 210   /* The match list array, in the format that readline expects.
 211      match_list[0] contains the common prefix.  The real match list
 212      starts at index 1.  The list is NULL terminated.  If there's only
 213      one match, then match_list[1] is NULL.  If there are no matches,
 214      then this is NULL.  */
 215   char **match_list;
 216   /* The number of matched completions in MATCH_LIST.  Does not
 217      include the NULL terminator or the common prefix.  */
 218   size_t number_matches;
 219
 220   /* Whether readline should suppress appending a whitespace, when
 221      there's only one possible completion.  */
 222   bool completion_suppress_append;
 223 };
 224
 225 /* Object used by completers to build a completion match list to hand
 226    over to readline.  It tracks:
 227
 228    - How many unique completions have been generated, to terminate
 229      completion list generation early if the list has grown to a size
 230      so large as to be useless.  This helps avoid GDB seeming to lock
 231      up in the event the user requests to complete on something vague
 232      that necessitates the time consuming expansion of many symbol
 233      tables.
 234
 235    - The completer's idea of least common denominator (aka the common
 236      prefix) between all completion matches to hand over to readline.
 237      Some completers provide matches that don't start with the
 238      completion "word".  E.g., completing on "b push_ba" on a C++
 239      program usually completes to std::vector<...>::push_back,
 240      std::string::push_back etc.  If all matches happen to start with
 241      "std::", then readline would figure out that the lowest common
 242      denominator is "std::", and thus would do a partial completion
 243      with that.  I.e., it would replace "push_ba" in the input buffer
 244      with "std::", losing the original "push_ba", which is obviously
 245      undesirable.  To avoid that, such completers pass the substring
 246      of the match that matters for common denominator computation as
 247      MATCH_FOR_LCD argument to add_completion.  The end result is
 248      passed to readline in gdb_rl_attempted_completion_function.
 249
 250    - The custom word point to hand over to readline, for completers
 251      that parse the input string in order to dynamically adjust
 252      themselves depending on exactly what they're completing.  E.g.,
 253      the linespec completer needs to bypass readline's too-simple word
 254      breaking algorithm.
 255 */
 256 class completion_tracker
 257 {
 258 public:
 259   completion_tracker ();
 260   ~completion_tracker ();
 261
 262   DISABLE_COPY_AND_ASSIGN (completion_tracker);
 263
 264   /* Add the completion NAME to the list of generated completions if
 265      it is not there already.  If too many completions were already
 266      found, this throws an error.  */
 267   void add_completion (gdb::unique_xmalloc_ptr<char> name,
 268                        completion_match_for_lcd *match_for_lcd = NULL);
 269
 270   /* Add all completions matches in LIST.  Elements are moved out of
 271      LIST.  */
 272   void add_completions (completion_list &&list);
 273
 274   /* Set the quote char to be appended after a unique completion is
 275      added to the input line.  Set to '\0' to clear.  See
 276      m_quote_char's description.  */
 277   void set_quote_char (int quote_char)
 278   { m_quote_char = quote_char; }
 279
 280   /* The quote char to be appended after a unique completion is added
 281      to the input line.  Returns '\0' if no quote char has been set.
 282      See m_quote_char's description.  */
 283   int quote_char () { return m_quote_char; }
 284
 285   /* Tell the tracker that the current completer wants to provide a
 286      custom word point instead of a list of a break chars, in the
 287      handle_brkchars phase.  Such completers must also compute their
 288      completions then.  */
 289   void set_use_custom_word_point (bool enable)
 290   { m_use_custom_word_point = enable; }
 291
 292   /* Whether the current completer computes a custom word point.  */
 293   bool use_custom_word_point () const
 294   { return m_use_custom_word_point; }
 295
 296   /* The custom word point.  */
 297   int custom_word_point () const
 298   { return m_custom_word_point; }
 299
 300   /* Set the custom word point to POINT.  */
 301   void set_custom_word_point (int point)
 302   { m_custom_word_point = point; }
 303
 304   /* Advance the custom word point by LEN.  */
 305   void advance_custom_word_point_by (size_t len);
 306
 307   /* Whether to tell readline to skip appending a whitespace after the
 308      completion.  See m_suppress_append_ws.  */
 309   bool suppress_append_ws () const
 310   { return m_suppress_append_ws; }
 311
 312   /* Set whether to tell readline to skip appending a whitespace after
 313      the completion.  See m_suppress_append_ws.  */
 314   void set_suppress_append_ws (bool suppress)
 315   { m_suppress_append_ws = suppress; }
 316
 317   /* Return true if we only have one completion, and it matches
 318      exactly the completion word.  I.e., completing results in what we
 319      already have.  */
 320   bool completes_to_completion_word (const char *word);
 321
 322   /* Get a reference to the shared (between all the multiple symbol
 323      name comparison calls) completion_match_result object, ready for
 324      another symbol name match sequence.  */
 325   completion_match_result &reset_completion_match_result ()
 326   {
 327     completion_match_result &res = m_completion_match_result;
 328
 329     /* Clear any previous match.  */
 330     res.match.clear ();
 331     res.match_for_lcd.clear ();
 332     return m_completion_match_result;
 333   }
 334
 335   /* True if we have any completion match recorded.  */
 336   bool have_completions () const
 337   { return !m_entries_vec.empty (); }
 338
 339   /* Discard the current completion match list and the current
 340      LCD.  */
 341   void discard_completions ();
 342
 343   /* Build a completion_result containing the list of completion
 344      matches to hand over to readline.  The parameters are as in
 345      rl_attempted_completion_function.  */
 346   completion_result build_completion_result (const char *text,
 347                                              int start, int end);
 348
 349 private:
 350
 351   /* Add the completion NAME to the list of generated completions if
 352      it is not there already.  If false is returned, too many
 353      completions were found.  */
 354   bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name,
 355                              completion_match_for_lcd *match_for_lcd);
 356
 357   /* Given a new match, recompute the lowest common denominator (LCD)
 358      to hand over to readline.  Normally readline computes this itself
 359      based on the whole set of completion matches.  However, some
 360      completers want to override readline, in order to be able to
 361      provide a LCD that is not really a prefix of the matches, but the
 362      lowest common denominator of some relevant substring of each
 363      match.  E.g., "b push_ba" completes to
 364      "std::vector<..>::push_back", "std::string::push_back", etc., and
 365      in this case we want the lowest common denominator to be
 366      "push_back" instead of "std::".  */
 367   void recompute_lowest_common_denominator (const char *new_match);
 368
 369   /* Completion match outputs returned by the symbol name matching
 370      routines (see symbol_name_matcher_ftype).  These results are only
 371      valid for a single match call.  This is here in order to be able
 372      to conveniently share the same storage among all the calls to the
 373      symbol name matching routines.  */
 374   completion_match_result m_completion_match_result;
 375
 376   /* The completion matches found so far, in a vector.  */
 377   completion_list m_entries_vec;
 378
 379   /* The completion matches found so far, in a hash table, for
 380      duplicate elimination as entries are added.  Otherwise the user
 381      is left scratching his/her head: readline and complete_command
 382      will remove duplicates, and if removal of duplicates there brings
 383      the total under max_completions the user may think gdb quit
 384      searching too early.  */
 385   htab_t m_entries_hash;
 386
 387   /* If non-zero, then this is the quote char that needs to be
 388      appended after completion (iff we have a unique completion).  We
 389      don't rely on readline appending the quote char as delimiter as
 390      then readline wouldn't append the ' ' after the completion.
 391      I.e., we want this:
 392
 393       before tab: "b 'function("
 394       after tab:  "b 'function()' "
 395   */
 396   int m_quote_char = '\0';
 397
 398   /* If true, the completer has its own idea of "word" point, and
 399      doesn't want to rely on readline computing it based on brkchars.
 400      Set in the handle_brkchars phase.  */
 401   bool m_use_custom_word_point = false;
 402
 403   /* The completer's idea of where the "word" we were looking at is
 404      relative to RL_LINE_BUFFER.  This is advanced in the
 405      handle_brkchars phase as the completer discovers potential
 406      completable words.  */
 407   int m_custom_word_point = 0;
 408
 409   /* If true, tell readline to skip appending a whitespace after the
 410      completion.  Automatically set if we have a unique completion
 411      that already has a space at the end.  A completer may also
 412      explicitly set this.  E.g., the linespec completer sets this when
 413      the completion ends with the ":" separator between filename and
 414      function name.  */
 415   bool m_suppress_append_ws = false;
 416
 417   /* Our idea of lowest common denominator to hand over to readline.
 418      See intro.  */
 419   char *m_lowest_common_denominator = NULL;
 420
 421   /* If true, the LCD is unique.  I.e., all completions had the same
 422      MATCH_FOR_LCD substring, even if the completions were different.
 423      For example, if "break function<tab>" found "a::function()" and
 424      "b::function()", the LCD will be "function()" in both cases and
 425      so we want to tell readline to complete the line with
 426      "function()", instead of showing all the possible
 427      completions.  */
 428   bool m_lowest_common_denominator_unique = false;
 429 };
 430
 431 extern void gdb_display_match_list (char **matches, int len, int max,
 432                                     const struct match_list_displayer *);
 433
 434 extern const char *get_max_completions_reached_message (void);
 435
 436 extern void complete_line (completion_tracker &tracker,
 437                            const char *text,
 438                            const char *line_buffer,
 439                            int point);
 440
 441 /* Find the bounds of the word in TEXT for completion purposes, and
 442    return a pointer to the end of the word.  Calls the completion
 443    machinery for a handle_brkchars phase (using TRACKER) to figure out
 444    the right work break characters for the command in TEXT.
 445    QUOTE_CHAR, if non-null, is set to the opening quote character if
 446    we found an unclosed quoted substring, '\0' otherwise.  */
 447 extern const char *completion_find_completion_word (completion_tracker &tracker,
 448                                                     const char *text,
 449                                                     int *quote_char);
 450
 451
 452 /* Assuming TEXT is an expression in the current language, find the
 453    completion word point for TEXT, emulating the algorithm readline
 454    uses to find the word point, using the current language's word
 455    break characters.  */
 456
 457 const char *advance_to_expression_complete_word_point
 458   (completion_tracker &tracker, const char *text);
 459
 460 extern char **gdb_rl_attempted_completion_function (const char *text,
 461                                                     int start, int end);
 462
 463 extern void noop_completer (struct cmd_list_element *,
 464                             completion_tracker &tracker,
 465                             const char *, const char *);
 466
 467 extern void filename_completer (struct cmd_list_element *,
 468                                 completion_tracker &tracker,
 469                                 const char *, const char *);
 470
 471 extern void expression_completer (struct cmd_list_element *,
 472                                   completion_tracker &tracker,
 473                                   const char *, const char *);
 474
 475 extern void location_completer (struct cmd_list_element *,
 476                                 completion_tracker &tracker,
 477                                 const char *, const char *);
 478
 479 extern void symbol_completer (struct cmd_list_element *,
 480                               completion_tracker &tracker,
 481                               const char *, const char *);
 482
 483 extern void command_completer (struct cmd_list_element *,
 484                                completion_tracker &tracker,
 485                                const char *, const char *);
 486
 487 extern void signal_completer (struct cmd_list_element *,
 488                               completion_tracker &tracker,
 489                               const char *, const char *);
 490
 491 extern void reg_or_group_completer (struct cmd_list_element *,
 492                                     completion_tracker &tracker,
 493                                     const char *, const char *);
 494
 495 extern void reggroup_completer (struct cmd_list_element *,
 496                                 completion_tracker &tracker,
 497                                 const char *, const char *);
 498
 499 extern const char *get_gdb_completer_quote_characters (void);
 500
 501 extern char *gdb_completion_word_break_characters (void);
 502
 503 /* Set the word break characters array to BREAK_CHARS.  This function
 504    is useful as const-correct alternative to direct assignment to
 505    rl_completer_word_break_characters, which is "char *",
 506    not "const char *".  */
 507 extern void set_rl_completer_word_break_characters (const char *break_chars);
 508
 509 /* Get the matching completer_handle_brkchars_ftype function for FN.
 510    FN is one of the core completer functions above (filename,
 511    location, symbol, etc.).  This function is useful for cases when
 512    the completer doesn't know the type of the completion until some
 513    calculation is done (e.g., for Python functions).  */
 514
 515 extern completer_handle_brkchars_ftype *
 516   completer_handle_brkchars_func_for_completer (completer_ftype *fn);
 517
 518 /* Exported to linespec.c */
 519
 520 /* Return a list of all source files whose names begin with matching
 521    TEXT.  */
 522 extern completion_list complete_source_filenames (const char *text);
 523
 524 /* Complete on expressions.  Often this means completing on symbol
 525    names, but some language parsers also have support for completing
 526    field names.  */
 527 extern void complete_expression (completion_tracker &tracker,
 528                                  const char *text, const char *word);
 529
 530 extern const char *skip_quoted_chars (const char *, const char *,
 531                                       const char *);
 532
 533 extern const char *skip_quoted (const char *);
 534
 535 /* Maximum number of candidates to consider before the completer
 536    bails by throwing MAX_COMPLETIONS_REACHED_ERROR.  Negative values
 537    disable limiting.  */
 538
 539 extern int max_completions;
 540
 541 #endif /* defined (COMPLETER_H) */