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 class completion_tracker
 138 {
 139 public:
 140   completion_tracker ();
 141   ~completion_tracker ();
 142
 143   /* Disable copy.  */
 144   completion_tracker (const completion_tracker &rhs) = delete;
 145   void operator= (const completion_tracker &rhs) = delete;
 146
 147   /* Add the completion NAME to the list of generated completions if
 148      it is not there already.  If too many completions were already
 149      found, this throws an error.  */
 150   void add_completion (gdb::unique_xmalloc_ptr<char> name);
 151
 152   /* Add all completions matches in LIST.  Elements are moved out of
 153      LIST.  */
 154   void add_completions (completion_list &&list);
 155
 156   /* True if we have any completion match recorded.  */
 157   bool have_completions () const
 158   { return !m_entries_vec.empty (); }
 159
 160   /* Build a completion_result containing the list of completion
 161      matches to hand over to readline.  The parameters are as in
 162      rl_attempted_completion_function.  */
 163   completion_result build_completion_result (const char *text,
 164                                              int start, int end);
 165
 166 private:
 167
 168   /* Add the completion NAME to the list of generated completions if
 169      it is not there already.  If false is returned, too many
 170      completions were found.  */
 171   bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name);
 172
 173   /* Given a new match, recompute the lowest common denominator (LCD)
 174      to hand over to readline.  */
 175   void recompute_lowest_common_denominator (const char *new_match);
 176
 177   /* The completion matches found so far, in a vector.  */
 178   completion_list m_entries_vec;
 179
 180   /* The completion matches found so far, in a hash table, for
 181      duplicate elimination as entries are added.  Otherwise the user
 182      is left scratching his/her head: readline and complete_command
 183      will remove duplicates, and if removal of duplicates there brings
 184      the total under max_completions the user may think gdb quit
 185      searching too early.  */
 186   htab_t m_entries_hash;
 187
 188   /* Our idea of lowest common denominator to hand over to readline.  */
 189   char *m_lowest_common_denominator = NULL;
 190
 191   /* If true, the LCD is unique.  I.e., all completion candidates had
 192      the same string.  */
 193   bool m_lowest_common_denominator_unique = false;
 194 };
 195
 196 extern void gdb_display_match_list (char **matches, int len, int max,
 197                                     const struct match_list_displayer *);
 198
 199 extern const char *get_max_completions_reached_message (void);
 200
 201 extern void complete_line (completion_tracker &tracker,
 202                            const char *text,
 203                            const char *line_buffer,
 204                            int point);
 205
 206 /* Find the bounds of the word in TEXT for completion purposes, and
 207    return a pointer to the end of the word.  Calls the completion
 208    machinery for a handle_brkchars phase (using TRACKER) to figure out
 209    the right work break characters for the command in TEXT.
 210    QUOTE_CHAR, if non-null, is set to the opening quote character if
 211    we found an unclosed quoted substring, '\0' otherwise.  */
 212 extern const char *completion_find_completion_word (completion_tracker &tracker,
 213                                                     const char *text,
 214                                                     int *quote_char);
 215
 216 extern char **gdb_rl_attempted_completion_function (const char *text,
 217                                                     int start, int end);
 218
 219 extern void noop_completer (struct cmd_list_element *,
 220                             completion_tracker &tracker,
 221                             const char *, const char *);
 222
 223 extern void filename_completer (struct cmd_list_element *,
 224                                 completion_tracker &tracker,
 225                                 const char *, const char *);
 226
 227 extern void expression_completer (struct cmd_list_element *,
 228                                   completion_tracker &tracker,
 229                                   const char *, const char *);
 230
 231 extern void location_completer (struct cmd_list_element *,
 232                                 completion_tracker &tracker,
 233                                 const char *, const char *);
 234
 235 extern void symbol_completer (struct cmd_list_element *,
 236                               completion_tracker &tracker,
 237                               const char *, const char *);
 238
 239 extern void command_completer (struct cmd_list_element *,
 240                                completion_tracker &tracker,
 241                                const char *, const char *);
 242
 243 extern void signal_completer (struct cmd_list_element *,
 244                               completion_tracker &tracker,
 245                               const char *, const char *);
 246
 247 extern void reg_or_group_completer (struct cmd_list_element *,
 248                                     completion_tracker &tracker,
 249                                     const char *, const char *);
 250
 251 extern void reggroup_completer (struct cmd_list_element *,
 252                                 completion_tracker &tracker,
 253                                 const char *, const char *);
 254
 255 extern const char *get_gdb_completer_quote_characters (void);
 256
 257 extern char *gdb_completion_word_break_characters (void);
 258
 259 /* Set the word break characters array to BREAK_CHARS.  This function
 260    is useful as const-correct alternative to direct assignment to
 261    rl_completer_word_break_characters, which is "char *",
 262    not "const char *".  */
 263 extern void set_rl_completer_word_break_characters (const char *break_chars);
 264
 265 /* Get the matching completer_handle_brkchars_ftype function for FN.
 266    FN is one of the core completer functions above (filename,
 267    location, symbol, etc.).  This function is useful for cases when
 268    the completer doesn't know the type of the completion until some
 269    calculation is done (e.g., for Python functions).  */
 270
 271 extern completer_handle_brkchars_ftype *
 272   completer_handle_brkchars_func_for_completer (completer_ftype *fn);
 273
 274 /* Exported to linespec.c */
 275
 276 extern const char *skip_quoted_chars (const char *, const char *,
 277                                       const char *);
 278
 279 extern const char *skip_quoted (const char *);
 280
 281 /* Maximum number of candidates to consider before the completer
 282    bails by throwing MAX_COMPLETIONS_REACHED_ERROR.  Negative values
 283    disable limiting.  */
 284
 285 extern int max_completions;
 286
 287 #endif /* defined (COMPLETER_H) */