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   /* Return true if we only have one completion, and it matches
 196      exactly the completion word.  I.e., completing results in what we
 197      already have.  */
 198   bool completes_to_completion_word (const char *word);
 199
 200   /* True if we have any completion match recorded.  */
 201   bool have_completions () const
 202   { return !m_entries_vec.empty (); }
 203
 204   /* Discard the current completion match list and the current
 205      LCD.  */
 206   void discard_completions ();
 207
 208   /* Build a completion_result containing the list of completion
 209      matches to hand over to readline.  The parameters are as in
 210      rl_attempted_completion_function.  */
 211   completion_result build_completion_result (const char *text,
 212                                              int start, int end);
 213
 214 private:
 215
 216   /* Add the completion NAME to the list of generated completions if
 217      it is not there already.  If false is returned, too many
 218      completions were found.  */
 219   bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name);
 220
 221   /* Given a new match, recompute the lowest common denominator (LCD)
 222      to hand over to readline.  */
 223   void recompute_lowest_common_denominator (const char *new_match);
 224
 225   /* The completion matches found so far, in a vector.  */
 226   completion_list m_entries_vec;
 227
 228   /* The completion matches found so far, in a hash table, for
 229      duplicate elimination as entries are added.  Otherwise the user
 230      is left scratching his/her head: readline and complete_command
 231      will remove duplicates, and if removal of duplicates there brings
 232      the total under max_completions the user may think gdb quit
 233      searching too early.  */
 234   htab_t m_entries_hash;
 235
 236   /* If non-zero, then this is the quote char that needs to be
 237      appended after completion (iff we have a unique completion).  We
 238      don't rely on readline appending the quote char as delimiter as
 239      then readline wouldn't append the ' ' after the completion.
 240      I.e., we want this:
 241
 242       before tab: "b 'function("
 243       after tab:  "b 'function()' "
 244   */
 245   int m_quote_char = '\0';
 246
 247   /* If true, the completer has its own idea of "word" point, and
 248      doesn't want to rely on readline computing it based on brkchars.
 249      Set in the handle_brkchars phase.  */
 250   bool m_use_custom_word_point = false;
 251
 252   /* The completer's idea of where the "word" we were looking at is
 253      relative to RL_LINE_BUFFER.  This is advanced in the
 254      handle_brkchars phase as the completer discovers potential
 255      completable words.  */
 256   int m_custom_word_point = 0;
 257
 258   /* Our idea of lowest common denominator to hand over to readline.
 259      See intro.  */
 260   char *m_lowest_common_denominator = NULL;
 261
 262   /* If true, the LCD is unique.  I.e., all completion candidates had
 263      the same string.  */
 264   bool m_lowest_common_denominator_unique = false;
 265 };
 266
 267 extern void gdb_display_match_list (char **matches, int len, int max,
 268                                     const struct match_list_displayer *);
 269
 270 extern const char *get_max_completions_reached_message (void);
 271
 272 extern void complete_line (completion_tracker &tracker,
 273                            const char *text,
 274                            const char *line_buffer,
 275                            int point);
 276
 277 /* Find the bounds of the word in TEXT for completion purposes, and
 278    return a pointer to the end of the word.  Calls the completion
 279    machinery for a handle_brkchars phase (using TRACKER) to figure out
 280    the right work break characters for the command in TEXT.
 281    QUOTE_CHAR, if non-null, is set to the opening quote character if
 282    we found an unclosed quoted substring, '\0' otherwise.  */
 283 extern const char *completion_find_completion_word (completion_tracker &tracker,
 284                                                     const char *text,
 285                                                     int *quote_char);
 286
 287
 288 /* Assuming TEXT is an expression in the current language, find the
 289    completion word point for TEXT, emulating the algorithm readline
 290    uses to find the word point, using the current language's word
 291    break characters.  */
 292
 293 const char *advance_to_expression_complete_word_point
 294   (completion_tracker &tracker, const char *text);
 295
 296 extern char **gdb_rl_attempted_completion_function (const char *text,
 297                                                     int start, int end);
 298
 299 extern void noop_completer (struct cmd_list_element *,
 300                             completion_tracker &tracker,
 301                             const char *, const char *);
 302
 303 extern void filename_completer (struct cmd_list_element *,
 304                                 completion_tracker &tracker,
 305                                 const char *, const char *);
 306
 307 extern void expression_completer (struct cmd_list_element *,
 308                                   completion_tracker &tracker,
 309                                   const char *, const char *);
 310
 311 extern void location_completer (struct cmd_list_element *,
 312                                 completion_tracker &tracker,
 313                                 const char *, const char *);
 314
 315 extern void symbol_completer (struct cmd_list_element *,
 316                               completion_tracker &tracker,
 317                               const char *, const char *);
 318
 319 extern void command_completer (struct cmd_list_element *,
 320                                completion_tracker &tracker,
 321                                const char *, const char *);
 322
 323 extern void signal_completer (struct cmd_list_element *,
 324                               completion_tracker &tracker,
 325                               const char *, const char *);
 326
 327 extern void reg_or_group_completer (struct cmd_list_element *,
 328                                     completion_tracker &tracker,
 329                                     const char *, const char *);
 330
 331 extern void reggroup_completer (struct cmd_list_element *,
 332                                 completion_tracker &tracker,
 333                                 const char *, const char *);
 334
 335 extern const char *get_gdb_completer_quote_characters (void);
 336
 337 extern char *gdb_completion_word_break_characters (void);
 338
 339 /* Set the word break characters array to BREAK_CHARS.  This function
 340    is useful as const-correct alternative to direct assignment to
 341    rl_completer_word_break_characters, which is "char *",
 342    not "const char *".  */
 343 extern void set_rl_completer_word_break_characters (const char *break_chars);
 344
 345 /* Get the matching completer_handle_brkchars_ftype function for FN.
 346    FN is one of the core completer functions above (filename,
 347    location, symbol, etc.).  This function is useful for cases when
 348    the completer doesn't know the type of the completion until some
 349    calculation is done (e.g., for Python functions).  */
 350
 351 extern completer_handle_brkchars_ftype *
 352   completer_handle_brkchars_func_for_completer (completer_ftype *fn);
 353
 354 /* Exported to linespec.c */
 355
 356 extern const char *skip_quoted_chars (const char *, const char *,
 357                                       const char *);
 358
 359 extern const char *skip_quoted (const char *);
 360
 361 /* Maximum number of candidates to consider before the completer
 362    bails by throwing MAX_COMPLETIONS_REACHED_ERROR.  Negative values
 363    disable limiting.  */
 364
 365 extern int max_completions;
 366
 367 #endif /* defined (COMPLETER_H) */