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