| 1 | /* Header for GDB line completion. |
| 2 | Copyright (C) 2000-2017 Free Software Foundation, Inc. |
| 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 |
| 6 | the Free Software Foundation; either version 3 of the License, or |
| 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 |
| 15 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
| 16 | |
| 17 | #if !defined (COMPLETER_H) |
| 18 | #define COMPLETER_H 1 |
| 19 | |
| 20 | #include "gdb_vecs.h" |
| 21 | #include "command.h" |
| 22 | |
| 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 | |
| 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 | |
| 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. */ |
| 75 | |
| 76 | struct completion_result |
| 77 | { |
| 78 | /* Create an empty result. */ |
| 79 | completion_result (); |
| 80 | |
| 81 | /* Create a result. */ |
| 82 | completion_result (char **match_list, size_t number_matches, |
| 83 | bool completion_suppress_append); |
| 84 | |
| 85 | /* Destroy a result. */ |
| 86 | ~completion_result (); |
| 87 | |
| 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; |
| 91 | |
| 92 | /* Move a result. */ |
| 93 | completion_result (completion_result &&rhs); |
| 94 | |
| 95 | /* Release ownership of the match list array. */ |
| 96 | char **release_match_list (); |
| 97 | |
| 98 | /* Sort the match list. */ |
| 99 | void sort_match_list (); |
| 100 | |
| 101 | private: |
| 102 | /* Destroy the match list array and its contents. */ |
| 103 | void reset_match_list (); |
| 104 | |
| 105 | public: |
| 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.) */ |
| 111 | |
| 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. */ |
| 117 | char **match_list; |
| 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; |
| 121 | |
| 122 | /* Whether readline should suppress appending a whitespace, when |
| 123 | there's only one possible completion. */ |
| 124 | bool completion_suppress_append; |
| 125 | }; |
| 126 | |
| 127 | /* Object used by completers to build a completion match list to hand |
| 128 | over to readline. It tracks: |
| 129 | |
| 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 |
| 135 | tables. |
| 136 | |
| 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 |
| 141 | breaking algorithm. |
| 142 | */ |
| 143 | class completion_tracker |
| 144 | { |
| 145 | public: |
| 146 | completion_tracker (); |
| 147 | ~completion_tracker (); |
| 148 | |
| 149 | /* Disable copy. */ |
| 150 | completion_tracker (const completion_tracker &rhs) = delete; |
| 151 | void operator= (const completion_tracker &rhs) = delete; |
| 152 | |
| 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); |
| 157 | |
| 158 | /* Add all completions matches in LIST. Elements are moved out of |
| 159 | LIST. */ |
| 160 | void add_completions (completion_list &&list); |
| 161 | |
| 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; } |
| 167 | |
| 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; } |
| 172 | |
| 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 |
| 176 | completions then. */ |
| 177 | void set_use_custom_word_point (bool enable) |
| 178 | { m_use_custom_word_point = enable; } |
| 179 | |
| 180 | /* Whether the current completer computes a custom word point. */ |
| 181 | bool use_custom_word_point () const |
| 182 | { return m_use_custom_word_point; } |
| 183 | |
| 184 | /* The custom word point. */ |
| 185 | int custom_word_point () const |
| 186 | { return m_custom_word_point; } |
| 187 | |
| 188 | /* Set the custom word point to POINT. */ |
| 189 | void set_custom_word_point (int point) |
| 190 | { m_custom_word_point = point; } |
| 191 | |
| 192 | /* Advance the custom word point by LEN. */ |
| 193 | void advance_custom_word_point_by (size_t len); |
| 194 | |
| 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; } |
| 199 | |
| 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; } |
| 204 | |
| 205 | /* Return true if we only have one completion, and it matches |
| 206 | exactly the completion word. I.e., completing results in what we |
| 207 | already have. */ |
| 208 | bool completes_to_completion_word (const char *word); |
| 209 | |
| 210 | /* True if we have any completion match recorded. */ |
| 211 | bool have_completions () const |
| 212 | { return !m_entries_vec.empty (); } |
| 213 | |
| 214 | /* Discard the current completion match list and the current |
| 215 | LCD. */ |
| 216 | void discard_completions (); |
| 217 | |
| 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, |
| 222 | int start, int end); |
| 223 | |
| 224 | private: |
| 225 | |
| 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); |
| 230 | |
| 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); |
| 234 | |
| 235 | /* The completion matches found so far, in a vector. */ |
| 236 | completion_list m_entries_vec; |
| 237 | |
| 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; |
| 245 | |
| 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. |
| 250 | I.e., we want this: |
| 251 | |
| 252 | before tab: "b 'function(" |
| 253 | after tab: "b 'function()' " |
| 254 | */ |
| 255 | int m_quote_char = '\0'; |
| 256 | |
| 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; |
| 261 | |
| 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; |
| 267 | |
| 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 |
| 273 | function name. */ |
| 274 | bool m_suppress_append_ws = false; |
| 275 | |
| 276 | /* Our idea of lowest common denominator to hand over to readline. |
| 277 | See intro. */ |
| 278 | char *m_lowest_common_denominator = NULL; |
| 279 | |
| 280 | /* If true, the LCD is unique. I.e., all completion candidates had |
| 281 | the same string. */ |
| 282 | bool m_lowest_common_denominator_unique = false; |
| 283 | }; |
| 284 | |
| 285 | extern void gdb_display_match_list (char **matches, int len, int max, |
| 286 | const struct match_list_displayer *); |
| 287 | |
| 288 | extern const char *get_max_completions_reached_message (void); |
| 289 | |
| 290 | extern void complete_line (completion_tracker &tracker, |
| 291 | const char *text, |
| 292 | const char *line_buffer, |
| 293 | int point); |
| 294 | |
| 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, |
| 302 | const char *text, |
| 303 | int *quote_char); |
| 304 | |
| 305 | |
| 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 |
| 309 | break characters. */ |
| 310 | |
| 311 | const char *advance_to_expression_complete_word_point |
| 312 | (completion_tracker &tracker, const char *text); |
| 313 | |
| 314 | extern char **gdb_rl_attempted_completion_function (const char *text, |
| 315 | int start, int end); |
| 316 | |
| 317 | extern void noop_completer (struct cmd_list_element *, |
| 318 | completion_tracker &tracker, |
| 319 | const char *, const char *); |
| 320 | |
| 321 | extern void filename_completer (struct cmd_list_element *, |
| 322 | completion_tracker &tracker, |
| 323 | const char *, const char *); |
| 324 | |
| 325 | extern void expression_completer (struct cmd_list_element *, |
| 326 | completion_tracker &tracker, |
| 327 | const char *, const char *); |
| 328 | |
| 329 | extern void location_completer (struct cmd_list_element *, |
| 330 | completion_tracker &tracker, |
| 331 | const char *, const char *); |
| 332 | |
| 333 | extern void symbol_completer (struct cmd_list_element *, |
| 334 | completion_tracker &tracker, |
| 335 | const char *, const char *); |
| 336 | |
| 337 | extern void command_completer (struct cmd_list_element *, |
| 338 | completion_tracker &tracker, |
| 339 | const char *, const char *); |
| 340 | |
| 341 | extern void signal_completer (struct cmd_list_element *, |
| 342 | completion_tracker &tracker, |
| 343 | const char *, const char *); |
| 344 | |
| 345 | extern void reg_or_group_completer (struct cmd_list_element *, |
| 346 | completion_tracker &tracker, |
| 347 | const char *, const char *); |
| 348 | |
| 349 | extern void reggroup_completer (struct cmd_list_element *, |
| 350 | completion_tracker &tracker, |
| 351 | const char *, const char *); |
| 352 | |
| 353 | extern const char *get_gdb_completer_quote_characters (void); |
| 354 | |
| 355 | extern char *gdb_completion_word_break_characters (void); |
| 356 | |
| 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); |
| 362 | |
| 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). */ |
| 368 | |
| 369 | extern completer_handle_brkchars_ftype * |
| 370 | completer_handle_brkchars_func_for_completer (completer_ftype *fn); |
| 371 | |
| 372 | /* Exported to linespec.c */ |
| 373 | |
| 374 | /* Return a list of all source files whose names begin with matching |
| 375 | TEXT. */ |
| 376 | extern completion_list complete_source_filenames (const char *text); |
| 377 | |
| 378 | /* Complete on expressions. Often this means completing on symbol |
| 379 | names, but some language parsers also have support for completing |
| 380 | field names. */ |
| 381 | extern void complete_expression (completion_tracker &tracker, |
| 382 | const char *text, const char *word); |
| 383 | |
| 384 | extern const char *skip_quoted_chars (const char *, const char *, |
| 385 | const char *); |
| 386 | |
| 387 | extern const char *skip_quoted (const char *); |
| 388 | |
| 389 | /* Maximum number of candidates to consider before the completer |
| 390 | bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values |
| 391 | disable limiting. */ |
| 392 | |
| 393 | extern int max_completions; |
| 394 | |
| 395 | #endif /* defined (COMPLETER_H) */ |