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 result of a successful completion match. When doing symbol
72 comparison, we use the symbol search name for the symbol name match
73 check, but the matched name that is shown to the user may be
74 different. For example, Ada uses encoded names for lookup, but
75 then wants to decode the symbol name to show to the user, and also
76 in some cases wrap the matched name in "<sym>" (meaning we can't
77 always use the symbol's print name). */
79 class completion_match
82 /* Get the completion match result. See m_match/m_storage's
87 /* Set the completion match result. See m_match/m_storage's
89 void set_match (const char *match
)
92 /* Get temporary storage for generating a match result, dynamically.
93 The built string is only good until the next clear() call. I.e.,
94 good until the next symbol comparison. */
95 std::string
&storage ()
98 /* Prepare for another completion matching sequence. */
106 /* The completion match result. This can either be a pointer into
107 M_STORAGE string, or it can be a pointer into the some other
108 string that outlives the completion matching sequence (usually, a
109 pointer to a symbol's name). */
112 /* Storage a symbol comparison routine can use for generating a
113 match result, dynamically. The built string is only good until
114 the next clear() call. I.e., good until the next symbol
116 std::string m_storage
;
119 /* Convenience aggregate holding info returned by the symbol name
120 matching routines (see symbol_name_matcher_ftype). */
121 struct completion_match_result
123 /* The completion match candidate. */
124 completion_match match
;
127 /* The final result of a completion that is handed over to either
128 readline or the "completion" command (which pretends to be
129 readline). Mainly a wrapper for a readline-style match list array,
130 though other bits of info are included too. */
132 struct completion_result
134 /* Create an empty result. */
135 completion_result ();
137 /* Create a result. */
138 completion_result (char **match_list
, size_t number_matches
,
139 bool completion_suppress_append
);
141 /* Destroy a result. */
142 ~completion_result ();
144 DISABLE_COPY_AND_ASSIGN (completion_result
);
147 completion_result (completion_result
&&rhs
);
149 /* Release ownership of the match list array. */
150 char **release_match_list ();
152 /* Sort the match list. */
153 void sort_match_list ();
156 /* Destroy the match list array and its contents. */
157 void reset_match_list ();
160 /* (There's no point in making these fields private, since the whole
161 point of this wrapper is to build data in the layout expected by
162 readline. Making them private would require adding getters for
163 the "complete" command, which would expose the same
164 implementation details anyway.) */
166 /* The match list array, in the format that readline expects.
167 match_list[0] contains the common prefix. The real match list
168 starts at index 1. The list is NULL terminated. If there's only
169 one match, then match_list[1] is NULL. If there are no matches,
170 then this is NULL. */
172 /* The number of matched completions in MATCH_LIST. Does not
173 include the NULL terminator or the common prefix. */
174 size_t number_matches
;
176 /* Whether readline should suppress appending a whitespace, when
177 there's only one possible completion. */
178 bool completion_suppress_append
;
181 /* Object used by completers to build a completion match list to hand
182 over to readline. It tracks:
184 - How many unique completions have been generated, to terminate
185 completion list generation early if the list has grown to a size
186 so large as to be useless. This helps avoid GDB seeming to lock
187 up in the event the user requests to complete on something vague
188 that necessitates the time consuming expansion of many symbol
191 - The custom word point to hand over to readline, for completers
192 that parse the input string in order to dynamically adjust
193 themselves depending on exactly what they're completing. E.g.,
194 the linespec completer needs to bypass readline's too-simple word
197 class completion_tracker
200 completion_tracker ();
201 ~completion_tracker ();
203 DISABLE_COPY_AND_ASSIGN (completion_tracker
);
205 /* Add the completion NAME to the list of generated completions if
206 it is not there already. If too many completions were already
207 found, this throws an error. */
208 void add_completion (gdb::unique_xmalloc_ptr
<char> name
);
210 /* Add all completions matches in LIST. Elements are moved out of
212 void add_completions (completion_list
&&list
);
214 /* Set the quote char to be appended after a unique completion is
215 added to the input line. Set to '\0' to clear. See
216 m_quote_char's description. */
217 void set_quote_char (int quote_char
)
218 { m_quote_char
= quote_char
; }
220 /* The quote char to be appended after a unique completion is added
221 to the input line. Returns '\0' if no quote char has been set.
222 See m_quote_char's description. */
223 int quote_char () { return m_quote_char
; }
225 /* Tell the tracker that the current completer wants to provide a
226 custom word point instead of a list of a break chars, in the
227 handle_brkchars phase. Such completers must also compute their
229 void set_use_custom_word_point (bool enable
)
230 { m_use_custom_word_point
= enable
; }
232 /* Whether the current completer computes a custom word point. */
233 bool use_custom_word_point () const
234 { return m_use_custom_word_point
; }
236 /* The custom word point. */
237 int custom_word_point () const
238 { return m_custom_word_point
; }
240 /* Set the custom word point to POINT. */
241 void set_custom_word_point (int point
)
242 { m_custom_word_point
= point
; }
244 /* Advance the custom word point by LEN. */
245 void advance_custom_word_point_by (size_t len
);
247 /* Whether to tell readline to skip appending a whitespace after the
248 completion. See m_suppress_append_ws. */
249 bool suppress_append_ws () const
250 { return m_suppress_append_ws
; }
252 /* Set whether to tell readline to skip appending a whitespace after
253 the completion. See m_suppress_append_ws. */
254 void set_suppress_append_ws (bool suppress
)
255 { m_suppress_append_ws
= suppress
; }
257 /* Return true if we only have one completion, and it matches
258 exactly the completion word. I.e., completing results in what we
260 bool completes_to_completion_word (const char *word
);
262 /* Get a reference to the shared (between all the multiple symbol
263 name comparison calls) completion_match_result object, ready for
264 another symbol name match sequence. */
265 completion_match_result
&reset_completion_match_result ()
267 completion_match_result
&res
= m_completion_match_result
;
269 /* Clear any previous match. */
271 return m_completion_match_result
;
274 /* True if we have any completion match recorded. */
275 bool have_completions () const
276 { return !m_entries_vec
.empty (); }
278 /* Discard the current completion match list and the current
280 void discard_completions ();
282 /* Build a completion_result containing the list of completion
283 matches to hand over to readline. The parameters are as in
284 rl_attempted_completion_function. */
285 completion_result
build_completion_result (const char *text
,
290 /* Add the completion NAME to the list of generated completions if
291 it is not there already. If false is returned, too many
292 completions were found. */
293 bool maybe_add_completion (gdb::unique_xmalloc_ptr
<char> name
);
295 /* Given a new match, recompute the lowest common denominator (LCD)
296 to hand over to readline. */
297 void recompute_lowest_common_denominator (const char *new_match
);
299 /* Completion match outputs returned by the symbol name matching
300 routines (see symbol_name_matcher_ftype). These results are only
301 valid for a single match call. This is here in order to be able
302 to conveniently share the same storage among all the calls to the
303 symbol name matching routines. */
304 completion_match_result m_completion_match_result
;
306 /* The completion matches found so far, in a vector. */
307 completion_list m_entries_vec
;
309 /* The completion matches found so far, in a hash table, for
310 duplicate elimination as entries are added. Otherwise the user
311 is left scratching his/her head: readline and complete_command
312 will remove duplicates, and if removal of duplicates there brings
313 the total under max_completions the user may think gdb quit
314 searching too early. */
315 htab_t m_entries_hash
;
317 /* If non-zero, then this is the quote char that needs to be
318 appended after completion (iff we have a unique completion). We
319 don't rely on readline appending the quote char as delimiter as
320 then readline wouldn't append the ' ' after the completion.
323 before tab: "b 'function("
324 after tab: "b 'function()' "
326 int m_quote_char
= '\0';
328 /* If true, the completer has its own idea of "word" point, and
329 doesn't want to rely on readline computing it based on brkchars.
330 Set in the handle_brkchars phase. */
331 bool m_use_custom_word_point
= false;
333 /* The completer's idea of where the "word" we were looking at is
334 relative to RL_LINE_BUFFER. This is advanced in the
335 handle_brkchars phase as the completer discovers potential
336 completable words. */
337 int m_custom_word_point
= 0;
339 /* If true, tell readline to skip appending a whitespace after the
340 completion. Automatically set if we have a unique completion
341 that already has a space at the end. A completer may also
342 explicitly set this. E.g., the linespec completer sets this when
343 the completion ends with the ":" separator between filename and
345 bool m_suppress_append_ws
= false;
347 /* Our idea of lowest common denominator to hand over to readline.
349 char *m_lowest_common_denominator
= NULL
;
351 /* If true, the LCD is unique. I.e., all completion candidates had
353 bool m_lowest_common_denominator_unique
= false;
356 extern void gdb_display_match_list (char **matches
, int len
, int max
,
357 const struct match_list_displayer
*);
359 extern const char *get_max_completions_reached_message (void);
361 extern void complete_line (completion_tracker
&tracker
,
363 const char *line_buffer
,
366 /* Find the bounds of the word in TEXT for completion purposes, and
367 return a pointer to the end of the word. Calls the completion
368 machinery for a handle_brkchars phase (using TRACKER) to figure out
369 the right work break characters for the command in TEXT.
370 QUOTE_CHAR, if non-null, is set to the opening quote character if
371 we found an unclosed quoted substring, '\0' otherwise. */
372 extern const char *completion_find_completion_word (completion_tracker
&tracker
,
377 /* Assuming TEXT is an expression in the current language, find the
378 completion word point for TEXT, emulating the algorithm readline
379 uses to find the word point, using the current language's word
382 const char *advance_to_expression_complete_word_point
383 (completion_tracker
&tracker
, const char *text
);
385 extern char **gdb_rl_attempted_completion_function (const char *text
,
388 extern void noop_completer (struct cmd_list_element
*,
389 completion_tracker
&tracker
,
390 const char *, const char *);
392 extern void filename_completer (struct cmd_list_element
*,
393 completion_tracker
&tracker
,
394 const char *, const char *);
396 extern void expression_completer (struct cmd_list_element
*,
397 completion_tracker
&tracker
,
398 const char *, const char *);
400 extern void location_completer (struct cmd_list_element
*,
401 completion_tracker
&tracker
,
402 const char *, const char *);
404 extern void symbol_completer (struct cmd_list_element
*,
405 completion_tracker
&tracker
,
406 const char *, const char *);
408 extern void command_completer (struct cmd_list_element
*,
409 completion_tracker
&tracker
,
410 const char *, const char *);
412 extern void signal_completer (struct cmd_list_element
*,
413 completion_tracker
&tracker
,
414 const char *, const char *);
416 extern void reg_or_group_completer (struct cmd_list_element
*,
417 completion_tracker
&tracker
,
418 const char *, const char *);
420 extern void reggroup_completer (struct cmd_list_element
*,
421 completion_tracker
&tracker
,
422 const char *, const char *);
424 extern const char *get_gdb_completer_quote_characters (void);
426 extern char *gdb_completion_word_break_characters (void);
428 /* Set the word break characters array to BREAK_CHARS. This function
429 is useful as const-correct alternative to direct assignment to
430 rl_completer_word_break_characters, which is "char *",
431 not "const char *". */
432 extern void set_rl_completer_word_break_characters (const char *break_chars
);
434 /* Get the matching completer_handle_brkchars_ftype function for FN.
435 FN is one of the core completer functions above (filename,
436 location, symbol, etc.). This function is useful for cases when
437 the completer doesn't know the type of the completion until some
438 calculation is done (e.g., for Python functions). */
440 extern completer_handle_brkchars_ftype
*
441 completer_handle_brkchars_func_for_completer (completer_ftype
*fn
);
443 /* Exported to linespec.c */
445 /* Return a list of all source files whose names begin with matching
447 extern completion_list
complete_source_filenames (const char *text
);
449 /* Complete on expressions. Often this means completing on symbol
450 names, but some language parsers also have support for completing
452 extern void complete_expression (completion_tracker
&tracker
,
453 const char *text
, const char *word
);
455 extern const char *skip_quoted_chars (const char *, const char *,
458 extern const char *skip_quoted (const char *);
460 /* Maximum number of candidates to consider before the completer
461 bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values
464 extern int max_completions
;
466 #endif /* defined (COMPLETER_H) */