1 /* Header for GDB line completion.
2 Copyright (C) 2000-2019 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)
21 #include "common/gdb_vecs.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 /* The result of a successful completion match, but for least common
120 denominator (LCD) computation. Some completers provide matches
121 that don't start with the completion "word". E.g., completing on
122 "b push_ba" on a C++ program usually completes to
123 std::vector<...>::push_back, std::string::push_back etc. In such
124 case, the symbol comparison routine will set the LCD match to point
125 into the "push_back" substring within the symbol's name string.
126 Also, in some cases, the symbol comparison routine will want to
127 ignore parts of the symbol name for LCD purposes, such as for
128 example symbols with abi tags in C++. In such cases, the symbol
129 comparison routine will set MARK_IGNORED_RANGE to mark the ignored
130 substrings of the matched string. The resulting LCD string with
131 the ignored parts stripped out is computed at the end of a
132 completion match sequence iff we had a positive match. */
134 class completion_match_for_lcd
137 /* Get the resulting LCD, after a successful match. */
141 /* Set the match for LCD. See m_match's description. */
142 void set_match (const char *match)
145 /* Mark the range between [BEGIN, END) as ignored. */
146 void mark_ignored_range (const char *begin, const char *end)
147 { m_ignored_ranges.emplace_back (begin, end); }
149 /* Get the resulting LCD, after a successful match. If there are
150 ignored ranges, then this builds a new string with the ignored
151 parts removed (and stores it internally). As such, the result of
152 this call is only good for the current completion match
154 const char *finish ()
156 if (m_ignored_ranges.empty ())
160 m_finished_storage.clear ();
162 const char *prev = m_match;
163 for (const auto &range : m_ignored_ranges)
165 m_finished_storage.append (prev, range.first);
168 m_finished_storage.append (prev);
170 return m_finished_storage.c_str ();
174 /* Prepare for another completion matching sequence. */
178 m_ignored_ranges.clear ();
182 /* The completion match result for LCD. This is usually either a
183 pointer into to a substring within a symbol's name, or to the
184 storage of the pairing completion_match object. */
187 /* The ignored substring ranges within M_MATCH. E.g., if we were
188 looking for completion matches for C++ functions starting with
190 and successfully match:
191 "function[abi:cxx11](int)"
192 the ignored ranges vector will contain an entry that delimits the
193 "[abi:cxx11]" substring, such that calling finish() results in:
196 std::vector<std::pair<const char *, const char *>> m_ignored_ranges;
198 /* Storage used by the finish() method, if it has to compute a new
200 std::string m_finished_storage;
203 /* Convenience aggregate holding info returned by the symbol name
204 matching routines (see symbol_name_matcher_ftype). */
205 struct completion_match_result
207 /* The completion match candidate. */
208 completion_match match;
210 /* The completion match, for LCD computation purposes. */
211 completion_match_for_lcd match_for_lcd;
213 /* Convenience that sets both MATCH and MATCH_FOR_LCD. M_FOR_LCD is
214 optional. If not specified, defaults to M. */
215 void set_match (const char *m, const char *m_for_lcd = NULL)
218 if (m_for_lcd == NULL)
219 match_for_lcd.set_match (m);
221 match_for_lcd.set_match (m_for_lcd);
225 /* The final result of a completion that is handed over to either
226 readline or the "completion" command (which pretends to be
227 readline). Mainly a wrapper for a readline-style match list array,
228 though other bits of info are included too. */
230 struct completion_result
232 /* Create an empty result. */
233 completion_result ();
235 /* Create a result. */
236 completion_result (char **match_list, size_t number_matches,
237 bool completion_suppress_append);
239 /* Destroy a result. */
240 ~completion_result ();
242 DISABLE_COPY_AND_ASSIGN (completion_result);
245 completion_result (completion_result &&rhs);
247 /* Release ownership of the match list array. */
248 char **release_match_list ();
250 /* Sort the match list. */
251 void sort_match_list ();
254 /* Destroy the match list array and its contents. */
255 void reset_match_list ();
258 /* (There's no point in making these fields private, since the whole
259 point of this wrapper is to build data in the layout expected by
260 readline. Making them private would require adding getters for
261 the "complete" command, which would expose the same
262 implementation details anyway.) */
264 /* The match list array, in the format that readline expects.
265 match_list[0] contains the common prefix. The real match list
266 starts at index 1. The list is NULL terminated. If there's only
267 one match, then match_list[1] is NULL. If there are no matches,
268 then this is NULL. */
270 /* The number of matched completions in MATCH_LIST. Does not
271 include the NULL terminator or the common prefix. */
272 size_t number_matches;
274 /* Whether readline should suppress appending a whitespace, when
275 there's only one possible completion. */
276 bool completion_suppress_append;
279 /* Object used by completers to build a completion match list to hand
280 over to readline. It tracks:
282 - How many unique completions have been generated, to terminate
283 completion list generation early if the list has grown to a size
284 so large as to be useless. This helps avoid GDB seeming to lock
285 up in the event the user requests to complete on something vague
286 that necessitates the time consuming expansion of many symbol
289 - The completer's idea of least common denominator (aka the common
290 prefix) between all completion matches to hand over to readline.
291 Some completers provide matches that don't start with the
292 completion "word". E.g., completing on "b push_ba" on a C++
293 program usually completes to std::vector<...>::push_back,
294 std::string::push_back etc. If all matches happen to start with
295 "std::", then readline would figure out that the lowest common
296 denominator is "std::", and thus would do a partial completion
297 with that. I.e., it would replace "push_ba" in the input buffer
298 with "std::", losing the original "push_ba", which is obviously
299 undesirable. To avoid that, such completers pass the substring
300 of the match that matters for common denominator computation as
301 MATCH_FOR_LCD argument to add_completion. The end result is
302 passed to readline in gdb_rl_attempted_completion_function.
304 - The custom word point to hand over to readline, for completers
305 that parse the input string in order to dynamically adjust
306 themselves depending on exactly what they're completing. E.g.,
307 the linespec completer needs to bypass readline's too-simple word
310 class completion_tracker
313 completion_tracker ();
314 ~completion_tracker ();
316 DISABLE_COPY_AND_ASSIGN (completion_tracker);
318 /* Add the completion NAME to the list of generated completions if
319 it is not there already. If too many completions were already
320 found, this throws an error. */
321 void add_completion (gdb::unique_xmalloc_ptr<char> name,
322 completion_match_for_lcd *match_for_lcd = NULL,
323 const char *text = NULL, const char *word = NULL);
325 /* Add all completions matches in LIST. Elements are moved out of
327 void add_completions (completion_list &&list);
329 /* Set the quote char to be appended after a unique completion is
330 added to the input line. Set to '\0' to clear. See
331 m_quote_char's description. */
332 void set_quote_char (int quote_char)
333 { m_quote_char = quote_char; }
335 /* The quote char to be appended after a unique completion is added
336 to the input line. Returns '\0' if no quote char has been set.
337 See m_quote_char's description. */
338 int quote_char () { return m_quote_char; }
340 /* Tell the tracker that the current completer wants to provide a
341 custom word point instead of a list of a break chars, in the
342 handle_brkchars phase. Such completers must also compute their
344 void set_use_custom_word_point (bool enable)
345 { m_use_custom_word_point = enable; }
347 /* Whether the current completer computes a custom word point. */
348 bool use_custom_word_point () const
349 { return m_use_custom_word_point; }
351 /* The custom word point. */
352 int custom_word_point () const
353 { return m_custom_word_point; }
355 /* Set the custom word point to POINT. */
356 void set_custom_word_point (int point)
357 { m_custom_word_point = point; }
359 /* Advance the custom word point by LEN. */
360 void advance_custom_word_point_by (size_t len);
362 /* Whether to tell readline to skip appending a whitespace after the
363 completion. See m_suppress_append_ws. */
364 bool suppress_append_ws () const
365 { return m_suppress_append_ws; }
367 /* Set whether to tell readline to skip appending a whitespace after
368 the completion. See m_suppress_append_ws. */
369 void set_suppress_append_ws (bool suppress)
370 { m_suppress_append_ws = suppress; }
372 /* Return true if we only have one completion, and it matches
373 exactly the completion word. I.e., completing results in what we
375 bool completes_to_completion_word (const char *word);
377 /* Get a reference to the shared (between all the multiple symbol
378 name comparison calls) completion_match_result object, ready for
379 another symbol name match sequence. */
380 completion_match_result &reset_completion_match_result ()
382 completion_match_result &res = m_completion_match_result;
384 /* Clear any previous match. */
386 res.match_for_lcd.clear ();
387 return m_completion_match_result;
390 /* True if we have any completion match recorded. */
391 bool have_completions () const
392 { return !m_entries_vec.empty (); }
394 /* Discard the current completion match list and the current
396 void discard_completions ();
398 /* Build a completion_result containing the list of completion
399 matches to hand over to readline. The parameters are as in
400 rl_attempted_completion_function. */
401 completion_result build_completion_result (const char *text,
406 /* Add the completion NAME to the list of generated completions if
407 it is not there already. If false is returned, too many
408 completions were found. */
409 bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name,
410 completion_match_for_lcd *match_for_lcd,
411 const char *text, const char *word);
413 /* Given a new match, recompute the lowest common denominator (LCD)
414 to hand over to readline. Normally readline computes this itself
415 based on the whole set of completion matches. However, some
416 completers want to override readline, in order to be able to
417 provide a LCD that is not really a prefix of the matches, but the
418 lowest common denominator of some relevant substring of each
419 match. E.g., "b push_ba" completes to
420 "std::vector<..>::push_back", "std::string::push_back", etc., and
421 in this case we want the lowest common denominator to be
422 "push_back" instead of "std::". */
423 void recompute_lowest_common_denominator
424 (gdb::unique_xmalloc_ptr<char> &&new_match);
426 /* Completion match outputs returned by the symbol name matching
427 routines (see symbol_name_matcher_ftype). These results are only
428 valid for a single match call. This is here in order to be able
429 to conveniently share the same storage among all the calls to the
430 symbol name matching routines. */
431 completion_match_result m_completion_match_result;
433 /* The completion matches found so far, in a vector. */
434 completion_list m_entries_vec;
436 /* The completion matches found so far, in a hash table, for
437 duplicate elimination as entries are added. Otherwise the user
438 is left scratching his/her head: readline and complete_command
439 will remove duplicates, and if removal of duplicates there brings
440 the total under max_completions the user may think gdb quit
441 searching too early. */
442 htab_t m_entries_hash;
444 /* If non-zero, then this is the quote char that needs to be
445 appended after completion (iff we have a unique completion). We
446 don't rely on readline appending the quote char as delimiter as
447 then readline wouldn't append the ' ' after the completion.
450 before tab: "b 'function("
451 after tab: "b 'function()' "
453 int m_quote_char = '\0';
455 /* If true, the completer has its own idea of "word" point, and
456 doesn't want to rely on readline computing it based on brkchars.
457 Set in the handle_brkchars phase. */
458 bool m_use_custom_word_point = false;
460 /* The completer's idea of where the "word" we were looking at is
461 relative to RL_LINE_BUFFER. This is advanced in the
462 handle_brkchars phase as the completer discovers potential
463 completable words. */
464 int m_custom_word_point = 0;
466 /* If true, tell readline to skip appending a whitespace after the
467 completion. Automatically set if we have a unique completion
468 that already has a space at the end. A completer may also
469 explicitly set this. E.g., the linespec completer sets this when
470 the completion ends with the ":" separator between filename and
472 bool m_suppress_append_ws = false;
474 /* Our idea of lowest common denominator to hand over to readline.
476 char *m_lowest_common_denominator = NULL;
478 /* If true, the LCD is unique. I.e., all completions had the same
479 MATCH_FOR_LCD substring, even if the completions were different.
480 For example, if "break function<tab>" found "a::function()" and
481 "b::function()", the LCD will be "function()" in both cases and
482 so we want to tell readline to complete the line with
483 "function()", instead of showing all the possible
485 bool m_lowest_common_denominator_unique = false;
488 /* Return a string to hand off to readline as a completion match
489 candidate, potentially composed of parts of MATCH_NAME and of
490 TEXT/WORD. For a description of TEXT/WORD see completer_ftype. */
492 extern gdb::unique_xmalloc_ptr<char>
493 make_completion_match_str (const char *match_name,
494 const char *text, const char *word);
496 /* Like above, but takes ownership of MATCH_NAME (i.e., can
499 extern gdb::unique_xmalloc_ptr<char>
500 make_completion_match_str (gdb::unique_xmalloc_ptr<char> &&match_name,
501 const char *text, const char *word);
503 extern void gdb_display_match_list (char **matches, int len, int max,
504 const struct match_list_displayer *);
506 extern const char *get_max_completions_reached_message (void);
508 extern void complete_line (completion_tracker &tracker,
510 const char *line_buffer,
513 /* Find the bounds of the word in TEXT for completion purposes, and
514 return a pointer to the end of the word. Calls the completion
515 machinery for a handle_brkchars phase (using TRACKER) to figure out
516 the right work break characters for the command in TEXT.
517 QUOTE_CHAR, if non-null, is set to the opening quote character if
518 we found an unclosed quoted substring, '\0' otherwise. */
519 extern const char *completion_find_completion_word (completion_tracker &tracker,
524 /* Assuming TEXT is an expression in the current language, find the
525 completion word point for TEXT, emulating the algorithm readline
526 uses to find the word point, using the current language's word
529 const char *advance_to_expression_complete_word_point
530 (completion_tracker &tracker, const char *text);
532 extern char **gdb_rl_attempted_completion_function (const char *text,
535 extern void noop_completer (struct cmd_list_element *,
536 completion_tracker &tracker,
537 const char *, const char *);
539 extern void filename_completer (struct cmd_list_element *,
540 completion_tracker &tracker,
541 const char *, const char *);
543 extern void expression_completer (struct cmd_list_element *,
544 completion_tracker &tracker,
545 const char *, const char *);
547 extern void location_completer (struct cmd_list_element *,
548 completion_tracker &tracker,
549 const char *, const char *);
551 extern void symbol_completer (struct cmd_list_element *,
552 completion_tracker &tracker,
553 const char *, const char *);
555 extern void command_completer (struct cmd_list_element *,
556 completion_tracker &tracker,
557 const char *, const char *);
559 extern void signal_completer (struct cmd_list_element *,
560 completion_tracker &tracker,
561 const char *, const char *);
563 extern void reg_or_group_completer (struct cmd_list_element *,
564 completion_tracker &tracker,
565 const char *, const char *);
567 extern void reggroup_completer (struct cmd_list_element *,
568 completion_tracker &tracker,
569 const char *, const char *);
571 extern const char *get_gdb_completer_quote_characters (void);
573 extern char *gdb_completion_word_break_characters (void);
575 /* Set the word break characters array to BREAK_CHARS. This function
576 is useful as const-correct alternative to direct assignment to
577 rl_completer_word_break_characters, which is "char *",
578 not "const char *". */
579 extern void set_rl_completer_word_break_characters (const char *break_chars);
581 /* Get the matching completer_handle_brkchars_ftype function for FN.
582 FN is one of the core completer functions above (filename,
583 location, symbol, etc.). This function is useful for cases when
584 the completer doesn't know the type of the completion until some
585 calculation is done (e.g., for Python functions). */
587 extern completer_handle_brkchars_ftype *
588 completer_handle_brkchars_func_for_completer (completer_ftype *fn);
590 /* Exported to linespec.c */
592 /* Return a list of all source files whose names begin with matching
594 extern completion_list complete_source_filenames (const char *text);
596 /* Complete on expressions. Often this means completing on symbol
597 names, but some language parsers also have support for completing
599 extern void complete_expression (completion_tracker &tracker,
600 const char *text, const char *word);
602 extern const char *skip_quoted_chars (const char *, const char *,
605 extern const char *skip_quoted (const char *);
607 /* Maximum number of candidates to consider before the completer
608 bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values
611 extern int max_completions;
613 #endif /* defined (COMPLETER_H) */