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