Commit | Line | Data |
---|---|---|
c5f0f3d0 | 1 | /* Header for GDB line completion. |
61baf725 | 2 | Copyright (C) 2000-2017 Free Software Foundation, Inc. |
c5f0f3d0 FN |
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 | |
a9762ec7 | 6 | the Free Software Foundation; either version 3 of the License, or |
c5f0f3d0 FN |
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 | |
a9762ec7 | 15 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
c5f0f3d0 FN |
16 | |
17 | #if !defined (COMPLETER_H) | |
18 | #define COMPLETER_H 1 | |
19 | ||
49c4e619 | 20 | #include "gdb_vecs.h" |
7d793aa9 | 21 | #include "command.h" |
49c4e619 | 22 | |
82083d6d DE |
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 | ||
eb3ff9a5 PA |
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 | ||
b5ec771e PA |
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). */ | |
78 | ||
79 | class completion_match | |
80 | { | |
81 | public: | |
82 | /* Get the completion match result. See m_match/m_storage's | |
83 | descriptions. */ | |
84 | const char *match () | |
85 | { return m_match; } | |
86 | ||
87 | /* Set the completion match result. See m_match/m_storage's | |
88 | descriptions. */ | |
89 | void set_match (const char *match) | |
90 | { m_match = match; } | |
91 | ||
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 () | |
96 | { return m_storage; } | |
97 | ||
98 | /* Prepare for another completion matching sequence. */ | |
99 | void clear () | |
100 | { | |
101 | m_match = NULL; | |
102 | m_storage.clear (); | |
103 | } | |
104 | ||
105 | private: | |
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). */ | |
110 | const char *m_match; | |
111 | ||
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 | |
115 | comparison. */ | |
116 | std::string m_storage; | |
117 | }; | |
118 | ||
119 | /* Convenience aggregate holding info returned by the symbol name | |
120 | matching routines (see symbol_name_matcher_ftype). */ | |
121 | struct completion_match_result | |
122 | { | |
123 | /* The completion match candidate. */ | |
124 | completion_match match; | |
125 | }; | |
126 | ||
eb3ff9a5 PA |
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. */ | |
131 | ||
132 | struct completion_result | |
133 | { | |
134 | /* Create an empty result. */ | |
135 | completion_result (); | |
136 | ||
137 | /* Create a result. */ | |
138 | completion_result (char **match_list, size_t number_matches, | |
139 | bool completion_suppress_append); | |
140 | ||
141 | /* Destroy a result. */ | |
142 | ~completion_result (); | |
143 | ||
d6541620 | 144 | DISABLE_COPY_AND_ASSIGN (completion_result); |
eb3ff9a5 PA |
145 | |
146 | /* Move a result. */ | |
147 | completion_result (completion_result &&rhs); | |
148 | ||
149 | /* Release ownership of the match list array. */ | |
150 | char **release_match_list (); | |
151 | ||
152 | /* Sort the match list. */ | |
153 | void sort_match_list (); | |
154 | ||
155 | private: | |
156 | /* Destroy the match list array and its contents. */ | |
157 | void reset_match_list (); | |
158 | ||
159 | public: | |
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.) */ | |
165 | ||
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. */ | |
171 | char **match_list; | |
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; | |
175 | ||
176 | /* Whether readline should suppress appending a whitespace, when | |
177 | there's only one possible completion. */ | |
178 | bool completion_suppress_append; | |
179 | }; | |
180 | ||
181 | /* Object used by completers to build a completion match list to hand | |
182 | over to readline. It tracks: | |
183 | ||
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 | |
189 | tables. | |
c6756f62 PA |
190 | |
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 | |
195 | breaking algorithm. | |
eb3ff9a5 PA |
196 | */ |
197 | class completion_tracker | |
198 | { | |
199 | public: | |
200 | completion_tracker (); | |
201 | ~completion_tracker (); | |
202 | ||
d6541620 | 203 | DISABLE_COPY_AND_ASSIGN (completion_tracker); |
eb3ff9a5 PA |
204 | |
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); | |
209 | ||
210 | /* Add all completions matches in LIST. Elements are moved out of | |
211 | LIST. */ | |
212 | void add_completions (completion_list &&list); | |
213 | ||
c6756f62 PA |
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; } | |
219 | ||
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; } | |
224 | ||
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 | |
228 | completions then. */ | |
229 | void set_use_custom_word_point (bool enable) | |
230 | { m_use_custom_word_point = enable; } | |
231 | ||
232 | /* Whether the current completer computes a custom word point. */ | |
233 | bool use_custom_word_point () const | |
234 | { return m_use_custom_word_point; } | |
235 | ||
236 | /* The custom word point. */ | |
237 | int custom_word_point () const | |
238 | { return m_custom_word_point; } | |
239 | ||
240 | /* Set the custom word point to POINT. */ | |
241 | void set_custom_word_point (int point) | |
242 | { m_custom_word_point = point; } | |
243 | ||
244 | /* Advance the custom word point by LEN. */ | |
245 | void advance_custom_word_point_by (size_t len); | |
246 | ||
c45ec17c PA |
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; } | |
251 | ||
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; } | |
256 | ||
c6756f62 PA |
257 | /* Return true if we only have one completion, and it matches |
258 | exactly the completion word. I.e., completing results in what we | |
259 | already have. */ | |
260 | bool completes_to_completion_word (const char *word); | |
261 | ||
b5ec771e PA |
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 () | |
266 | { | |
267 | completion_match_result &res = m_completion_match_result; | |
268 | ||
269 | /* Clear any previous match. */ | |
270 | res.match.clear (); | |
271 | return m_completion_match_result; | |
272 | } | |
273 | ||
eb3ff9a5 PA |
274 | /* True if we have any completion match recorded. */ |
275 | bool have_completions () const | |
276 | { return !m_entries_vec.empty (); } | |
277 | ||
c6756f62 PA |
278 | /* Discard the current completion match list and the current |
279 | LCD. */ | |
280 | void discard_completions (); | |
281 | ||
eb3ff9a5 PA |
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, | |
286 | int start, int end); | |
287 | ||
288 | private: | |
289 | ||
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); | |
294 | ||
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); | |
298 | ||
b5ec771e PA |
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; | |
305 | ||
eb3ff9a5 PA |
306 | /* The completion matches found so far, in a vector. */ |
307 | completion_list m_entries_vec; | |
308 | ||
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; | |
316 | ||
c6756f62 PA |
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. | |
321 | I.e., we want this: | |
322 | ||
323 | before tab: "b 'function(" | |
324 | after tab: "b 'function()' " | |
325 | */ | |
326 | int m_quote_char = '\0'; | |
327 | ||
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; | |
332 | ||
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; | |
338 | ||
c45ec17c PA |
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 | |
344 | function name. */ | |
345 | bool m_suppress_append_ws = false; | |
346 | ||
c6756f62 PA |
347 | /* Our idea of lowest common denominator to hand over to readline. |
348 | See intro. */ | |
eb3ff9a5 PA |
349 | char *m_lowest_common_denominator = NULL; |
350 | ||
351 | /* If true, the LCD is unique. I.e., all completion candidates had | |
352 | the same string. */ | |
353 | bool m_lowest_common_denominator_unique = false; | |
354 | }; | |
355 | ||
82083d6d DE |
356 | extern void gdb_display_match_list (char **matches, int len, int max, |
357 | const struct match_list_displayer *); | |
358 | ||
ef0b411a GB |
359 | extern const char *get_max_completions_reached_message (void); |
360 | ||
eb3ff9a5 PA |
361 | extern void complete_line (completion_tracker &tracker, |
362 | const char *text, | |
363 | const char *line_buffer, | |
364 | int point); | |
83d31a92 | 365 | |
6a2c1b87 PA |
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, | |
373 | const char *text, | |
374 | int *quote_char); | |
375 | ||
c6756f62 PA |
376 | |
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 | |
380 | break characters. */ | |
381 | ||
382 | const char *advance_to_expression_complete_word_point | |
383 | (completion_tracker &tracker, const char *text); | |
384 | ||
eb3ff9a5 PA |
385 | extern char **gdb_rl_attempted_completion_function (const char *text, |
386 | int start, int end); | |
d75b5104 | 387 | |
eb3ff9a5 PA |
388 | extern void noop_completer (struct cmd_list_element *, |
389 | completion_tracker &tracker, | |
390 | const char *, const char *); | |
d75b5104 | 391 | |
eb3ff9a5 PA |
392 | extern void filename_completer (struct cmd_list_element *, |
393 | completion_tracker &tracker, | |
394 | const char *, const char *); | |
c5f0f3d0 | 395 | |
eb3ff9a5 PA |
396 | extern void expression_completer (struct cmd_list_element *, |
397 | completion_tracker &tracker, | |
398 | const char *, const char *); | |
65d12d83 | 399 | |
eb3ff9a5 PA |
400 | extern void location_completer (struct cmd_list_element *, |
401 | completion_tracker &tracker, | |
402 | const char *, const char *); | |
c94fdfd0 | 403 | |
eb3ff9a5 PA |
404 | extern void symbol_completer (struct cmd_list_element *, |
405 | completion_tracker &tracker, | |
406 | const char *, const char *); | |
78b13106 | 407 | |
eb3ff9a5 PA |
408 | extern void command_completer (struct cmd_list_element *, |
409 | completion_tracker &tracker, | |
410 | const char *, const char *); | |
db60ec62 | 411 | |
eb3ff9a5 PA |
412 | extern void signal_completer (struct cmd_list_element *, |
413 | completion_tracker &tracker, | |
414 | const char *, const char *); | |
de0bea00 | 415 | |
eb3ff9a5 PA |
416 | extern void reg_or_group_completer (struct cmd_list_element *, |
417 | completion_tracker &tracker, | |
418 | const char *, const char *); | |
71c24708 | 419 | |
eb3ff9a5 PA |
420 | extern void reggroup_completer (struct cmd_list_element *, |
421 | completion_tracker &tracker, | |
422 | const char *, const char *); | |
51f0e40d | 423 | |
67cb5b2d | 424 | extern const char *get_gdb_completer_quote_characters (void); |
c5f0f3d0 | 425 | |
67c296a2 PM |
426 | extern char *gdb_completion_word_break_characters (void); |
427 | ||
67cb5b2d PA |
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); | |
433 | ||
6e1dbf8c PA |
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 | |
7d793aa9 SDJ |
438 | calculation is done (e.g., for Python functions). */ |
439 | ||
6e1dbf8c PA |
440 | extern completer_handle_brkchars_ftype * |
441 | completer_handle_brkchars_func_for_completer (completer_ftype *fn); | |
7d793aa9 | 442 | |
c5f0f3d0 FN |
443 | /* Exported to linespec.c */ |
444 | ||
c45ec17c PA |
445 | /* Return a list of all source files whose names begin with matching |
446 | TEXT. */ | |
447 | extern completion_list complete_source_filenames (const char *text); | |
448 | ||
449 | /* Complete on expressions. Often this means completing on symbol | |
450 | names, but some language parsers also have support for completing | |
451 | field names. */ | |
452 | extern void complete_expression (completion_tracker &tracker, | |
453 | const char *text, const char *word); | |
454 | ||
d7561cbb KS |
455 | extern const char *skip_quoted_chars (const char *, const char *, |
456 | const char *); | |
4e87b832 | 457 | |
d7561cbb | 458 | extern const char *skip_quoted (const char *); |
c5f0f3d0 | 459 | |
ef0b411a GB |
460 | /* Maximum number of candidates to consider before the completer |
461 | bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values | |
462 | disable limiting. */ | |
463 | ||
464 | extern int max_completions; | |
465 | ||
c5f0f3d0 | 466 | #endif /* defined (COMPLETER_H) */ |