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 /* Whether to tell readline to skip appending a whitespace after the
196 completion. See m_suppress_append_ws. */
197 bool suppress_append_ws () const
198 { return m_suppress_append_ws
; }
200 /* Set whether to tell readline to skip appending a whitespace after
201 the completion. See m_suppress_append_ws. */
202 void set_suppress_append_ws (bool suppress
)
203 { m_suppress_append_ws
= suppress
; }
205 /* Return true if we only have one completion, and it matches
206 exactly the completion word. I.e., completing results in what we
208 bool completes_to_completion_word (const char *word
);
210 /* True if we have any completion match recorded. */
211 bool have_completions () const
212 { return !m_entries_vec
.empty (); }
214 /* Discard the current completion match list and the current
216 void discard_completions ();
218 /* Build a completion_result containing the list of completion
219 matches to hand over to readline. The parameters are as in
220 rl_attempted_completion_function. */
221 completion_result
build_completion_result (const char *text
,
226 /* Add the completion NAME to the list of generated completions if
227 it is not there already. If false is returned, too many
228 completions were found. */
229 bool maybe_add_completion (gdb::unique_xmalloc_ptr
<char> name
);
231 /* Given a new match, recompute the lowest common denominator (LCD)
232 to hand over to readline. */
233 void recompute_lowest_common_denominator (const char *new_match
);
235 /* The completion matches found so far, in a vector. */
236 completion_list m_entries_vec
;
238 /* The completion matches found so far, in a hash table, for
239 duplicate elimination as entries are added. Otherwise the user
240 is left scratching his/her head: readline and complete_command
241 will remove duplicates, and if removal of duplicates there brings
242 the total under max_completions the user may think gdb quit
243 searching too early. */
244 htab_t m_entries_hash
;
246 /* If non-zero, then this is the quote char that needs to be
247 appended after completion (iff we have a unique completion). We
248 don't rely on readline appending the quote char as delimiter as
249 then readline wouldn't append the ' ' after the completion.
252 before tab: "b 'function("
253 after tab: "b 'function()' "
255 int m_quote_char
= '\0';
257 /* If true, the completer has its own idea of "word" point, and
258 doesn't want to rely on readline computing it based on brkchars.
259 Set in the handle_brkchars phase. */
260 bool m_use_custom_word_point
= false;
262 /* The completer's idea of where the "word" we were looking at is
263 relative to RL_LINE_BUFFER. This is advanced in the
264 handle_brkchars phase as the completer discovers potential
265 completable words. */
266 int m_custom_word_point
= 0;
268 /* If true, tell readline to skip appending a whitespace after the
269 completion. Automatically set if we have a unique completion
270 that already has a space at the end. A completer may also
271 explicitly set this. E.g., the linespec completer sets this when
272 the completion ends with the ":" separator between filename and
274 bool m_suppress_append_ws
= false;
276 /* Our idea of lowest common denominator to hand over to readline.
278 char *m_lowest_common_denominator
= NULL
;
280 /* If true, the LCD is unique. I.e., all completion candidates had
282 bool m_lowest_common_denominator_unique
= false;
285 extern void gdb_display_match_list (char **matches
, int len
, int max
,
286 const struct match_list_displayer
*);
288 extern const char *get_max_completions_reached_message (void);
290 extern void complete_line (completion_tracker
&tracker
,
292 const char *line_buffer
,
295 /* Find the bounds of the word in TEXT for completion purposes, and
296 return a pointer to the end of the word. Calls the completion
297 machinery for a handle_brkchars phase (using TRACKER) to figure out
298 the right work break characters for the command in TEXT.
299 QUOTE_CHAR, if non-null, is set to the opening quote character if
300 we found an unclosed quoted substring, '\0' otherwise. */
301 extern const char *completion_find_completion_word (completion_tracker
&tracker
,
306 /* Assuming TEXT is an expression in the current language, find the
307 completion word point for TEXT, emulating the algorithm readline
308 uses to find the word point, using the current language's word
311 const char *advance_to_expression_complete_word_point
312 (completion_tracker
&tracker
, const char *text
);
314 extern char **gdb_rl_attempted_completion_function (const char *text
,
317 extern void noop_completer (struct cmd_list_element
*,
318 completion_tracker
&tracker
,
319 const char *, const char *);
321 extern void filename_completer (struct cmd_list_element
*,
322 completion_tracker
&tracker
,
323 const char *, const char *);
325 extern void expression_completer (struct cmd_list_element
*,
326 completion_tracker
&tracker
,
327 const char *, const char *);
329 extern void location_completer (struct cmd_list_element
*,
330 completion_tracker
&tracker
,
331 const char *, const char *);
333 extern void symbol_completer (struct cmd_list_element
*,
334 completion_tracker
&tracker
,
335 const char *, const char *);
337 extern void command_completer (struct cmd_list_element
*,
338 completion_tracker
&tracker
,
339 const char *, const char *);
341 extern void signal_completer (struct cmd_list_element
*,
342 completion_tracker
&tracker
,
343 const char *, const char *);
345 extern void reg_or_group_completer (struct cmd_list_element
*,
346 completion_tracker
&tracker
,
347 const char *, const char *);
349 extern void reggroup_completer (struct cmd_list_element
*,
350 completion_tracker
&tracker
,
351 const char *, const char *);
353 extern const char *get_gdb_completer_quote_characters (void);
355 extern char *gdb_completion_word_break_characters (void);
357 /* Set the word break characters array to BREAK_CHARS. This function
358 is useful as const-correct alternative to direct assignment to
359 rl_completer_word_break_characters, which is "char *",
360 not "const char *". */
361 extern void set_rl_completer_word_break_characters (const char *break_chars
);
363 /* Get the matching completer_handle_brkchars_ftype function for FN.
364 FN is one of the core completer functions above (filename,
365 location, symbol, etc.). This function is useful for cases when
366 the completer doesn't know the type of the completion until some
367 calculation is done (e.g., for Python functions). */
369 extern completer_handle_brkchars_ftype
*
370 completer_handle_brkchars_func_for_completer (completer_ftype
*fn
);
372 /* Exported to linespec.c */
374 /* Return a list of all source files whose names begin with matching
376 extern completion_list
complete_source_filenames (const char *text
);
378 /* Complete on expressions. Often this means completing on symbol
379 names, but some language parsers also have support for completing
381 extern void complete_expression (completion_tracker
&tracker
,
382 const char *text
, const char *word
);
384 extern const char *skip_quoted_chars (const char *, const char *,
387 extern const char *skip_quoted (const char *);
389 /* Maximum number of candidates to consider before the completer
390 bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values
393 extern int max_completions
;
395 #endif /* defined (COMPLETER_H) */