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