1 /* Header for GDB line completion.
2 Copyright (C) 2000-2017 Free Software Foundation, Inc.
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.
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.
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/>. */
17 #if !defined (COMPLETER_H)
23 /* Types of functions in struct match_list_displayer. */
25 struct match_list_displayer;
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 *,
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 *);
36 /* Interface between CLI/TUI and gdb_match_list_displayer. */
38 struct match_list_displayer
40 /* The screen dimensions to work with when displaying matches. */
46 /* Not "putc" to avoid issues where it is a stdio macro. Sigh. */
47 mld_putch_ftype *putch;
52 /* Flush all accumulated output. */
53 mld_flush_ftype *flush;
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;
63 mld_read_key_ftype *read_key;
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;
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. */
76 struct completion_result
78 /* Create an empty result. */
81 /* Create a result. */
82 completion_result (char **match_list, size_t number_matches,
83 bool completion_suppress_append);
85 /* Destroy a result. */
86 ~completion_result ();
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;
93 completion_result (completion_result &&rhs);
95 /* Release ownership of the match list array. */
96 char **release_match_list ();
98 /* Sort the match list. */
99 void sort_match_list ();
102 /* Destroy the match list array and its contents. */
103 void reset_match_list ();
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.) */
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. */
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;
122 /* Whether readline should suppress appending a whitespace, when
123 there's only one possible completion. */
124 bool completion_suppress_append;
127 /* Object used by completers to build a completion match list to hand
128 over to readline. It tracks:
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
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
143 class completion_tracker
146 completion_tracker ();
147 ~completion_tracker ();
150 completion_tracker (const completion_tracker &rhs) = delete;
151 void operator= (const completion_tracker &rhs) = delete;
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);
158 /* Add all completions matches in LIST. Elements are moved out of
160 void add_completions (completion_list &&list);
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; }
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; }
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
177 void set_use_custom_word_point (bool enable)
178 { m_use_custom_word_point = enable; }
180 /* Whether the current completer computes a custom word point. */
181 bool use_custom_word_point () const
182 { return m_use_custom_word_point; }
184 /* The custom word point. */
185 int custom_word_point () const
186 { return m_custom_word_point; }
188 /* Set the custom word point to POINT. */
189 void set_custom_word_point (int point)
190 { m_custom_word_point = point; }
192 /* Advance the custom word point by LEN. */
193 void advance_custom_word_point_by (size_t len);
195 /* Return true if we only have one completion, and it matches
196 exactly the completion word. I.e., completing results in what we
198 bool completes_to_completion_word (const char *word);
200 /* True if we have any completion match recorded. */
201 bool have_completions () const
202 { return !m_entries_vec.empty (); }
204 /* Discard the current completion match list and the current
206 void discard_completions ();
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,
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);
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);
225 /* The completion matches found so far, in a vector. */
226 completion_list m_entries_vec;
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;
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.
242 before tab: "b 'function("
243 after tab: "b 'function()' "
245 int m_quote_char = '\0';
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;
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;
258 /* Our idea of lowest common denominator to hand over to readline.
260 char *m_lowest_common_denominator = NULL;
262 /* If true, the LCD is unique. I.e., all completion candidates had
264 bool m_lowest_common_denominator_unique = false;
267 extern void gdb_display_match_list (char **matches, int len, int max,
268 const struct match_list_displayer *);
270 extern const char *get_max_completions_reached_message (void);
272 extern void complete_line (completion_tracker &tracker,
274 const char *line_buffer,
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,
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
293 const char *advance_to_expression_complete_word_point
294 (completion_tracker &tracker, const char *text);
296 extern char **gdb_rl_attempted_completion_function (const char *text,
299 extern void noop_completer (struct cmd_list_element *,
300 completion_tracker &tracker,
301 const char *, const char *);
303 extern void filename_completer (struct cmd_list_element *,
304 completion_tracker &tracker,
305 const char *, const char *);
307 extern void expression_completer (struct cmd_list_element *,
308 completion_tracker &tracker,
309 const char *, const char *);
311 extern void location_completer (struct cmd_list_element *,
312 completion_tracker &tracker,
313 const char *, const char *);
315 extern void symbol_completer (struct cmd_list_element *,
316 completion_tracker &tracker,
317 const char *, const char *);
319 extern void command_completer (struct cmd_list_element *,
320 completion_tracker &tracker,
321 const char *, const char *);
323 extern void signal_completer (struct cmd_list_element *,
324 completion_tracker &tracker,
325 const char *, const char *);
327 extern void reg_or_group_completer (struct cmd_list_element *,
328 completion_tracker &tracker,
329 const char *, const char *);
331 extern void reggroup_completer (struct cmd_list_element *,
332 completion_tracker &tracker,
333 const char *, const char *);
335 extern const char *get_gdb_completer_quote_characters (void);
337 extern char *gdb_completion_word_break_characters (void);
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);
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). */
351 extern completer_handle_brkchars_ftype *
352 completer_handle_brkchars_func_for_completer (completer_ftype *fn);
354 /* Exported to linespec.c */
356 extern const char *skip_quoted_chars (const char *, const char *,
359 extern const char *skip_quoted (const char *);
361 /* Maximum number of candidates to consider before the completer
362 bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values
365 extern int max_completions;
367 #endif /* defined (COMPLETER_H) */