1 /* Header for GDB line completion. 2 Copyright (C) 2000-2020 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 "gdbsupport/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 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 /* 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. */ 133 134 class completion_match_for_lcd 135 { 136 public: 137 /* Get the resulting LCD, after a successful match. */ 138 const char *match () 139 { return m_match; } 140 141 /* Set the match for LCD. See m_match's description. */ 142 void set_match (const char *match) 143 { m_match = match; } 144 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); } 148 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 153 sequence. */ 154 const char *finish () 155 { 156 if (m_ignored_ranges.empty ()) 157 return m_match; 158 else 159 { 160 m_finished_storage.clear (); 161 162 const char *prev = m_match; 163 for (const auto &range : m_ignored_ranges) 164 { 165 m_finished_storage.append (prev, range.first); 166 prev = range.second; 167 } 168 m_finished_storage.append (prev); 169 170 return m_finished_storage.c_str (); 171 } 172 } 173 174 /* Prepare for another completion matching sequence. */ 175 void clear () 176 { 177 m_match = NULL; 178 m_ignored_ranges.clear (); 179 } 180 181 private: 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. */ 185 const char *m_match; 186 187 /* The ignored substring ranges within M_MATCH. E.g., if we were 188 looking for completion matches for C++ functions starting with 189 "functio" 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: 194 "function(int)" 195 */ 196 std::vector<std::pair<const char *, const char *>> m_ignored_ranges; 197 198 /* Storage used by the finish() method, if it has to compute a new 199 string. */ 200 std::string m_finished_storage; 201 }; 202 203 /* Convenience aggregate holding info returned by the symbol name 204 matching routines (see symbol_name_matcher_ftype). */ 205 struct completion_match_result 206 { 207 /* The completion match candidate. */ 208 completion_match match; 209 210 /* The completion match, for LCD computation purposes. */ 211 completion_match_for_lcd match_for_lcd; 212 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) 216 { 217 match.set_match (m); 218 if (m_for_lcd == NULL) 219 match_for_lcd.set_match (m); 220 else 221 match_for_lcd.set_match (m_for_lcd); 222 } 223 }; 224 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. */ 229 230 struct completion_result 231 { 232 /* Create an empty result. */ 233 completion_result (); 234 235 /* Create a result. */ 236 completion_result (char **match_list, size_t number_matches, 237 bool completion_suppress_append); 238 239 /* Destroy a result. */ 240 ~completion_result (); 241 242 DISABLE_COPY_AND_ASSIGN (completion_result); 243 244 /* Move a result. */ 245 completion_result (completion_result &&rhs) noexcept; 246 247 /* Release ownership of the match list array. */ 248 char **release_match_list (); 249 250 /* Sort the match list. */ 251 void sort_match_list (); 252 253 private: 254 /* Destroy the match list array and its contents. */ 255 void reset_match_list (); 256 257 public: 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.) */ 263 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. */ 269 char **match_list; 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; 273 274 /* Whether readline should suppress appending a whitespace, when 275 there's only one possible completion. */ 276 bool completion_suppress_append; 277 }; 278 279 /* Object used by completers to build a completion match list to hand 280 over to readline. It tracks: 281 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 287 tables. 288 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. 303 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 308 breaking algorithm. 309 */ 310 class completion_tracker 311 { 312 public: 313 completion_tracker (); 314 ~completion_tracker (); 315 316 DISABLE_COPY_AND_ASSIGN (completion_tracker); 317 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); 324 325 /* Add all completions matches in LIST. Elements are moved out of 326 LIST. */ 327 void add_completions (completion_list &&list); 328 329 /* Remove completion matching NAME from the completion list, does nothing 330 if NAME is not already in the completion list. */ 331 void remove_completion (const char *name); 332 333 /* Set the quote char to be appended after a unique completion is 334 added to the input line. Set to '\0' to clear. See 335 m_quote_char's description. */ 336 void set_quote_char (int quote_char) 337 { m_quote_char = quote_char; } 338 339 /* The quote char to be appended after a unique completion is added 340 to the input line. Returns '\0' if no quote char has been set. 341 See m_quote_char's description. */ 342 int quote_char () { return m_quote_char; } 343 344 /* Tell the tracker that the current completer wants to provide a 345 custom word point instead of a list of a break chars, in the 346 handle_brkchars phase. Such completers must also compute their 347 completions then. */ 348 void set_use_custom_word_point (bool enable) 349 { m_use_custom_word_point = enable; } 350 351 /* Whether the current completer computes a custom word point. */ 352 bool use_custom_word_point () const 353 { return m_use_custom_word_point; } 354 355 /* The custom word point. */ 356 int custom_word_point () const 357 { return m_custom_word_point; } 358 359 /* Set the custom word point to POINT. */ 360 void set_custom_word_point (int point) 361 { m_custom_word_point = point; } 362 363 /* Advance the custom word point by LEN. */ 364 void advance_custom_word_point_by (int len); 365 366 /* Whether to tell readline to skip appending a whitespace after the 367 completion. See m_suppress_append_ws. */ 368 bool suppress_append_ws () const 369 { return m_suppress_append_ws; } 370 371 /* Set whether to tell readline to skip appending a whitespace after 372 the completion. See m_suppress_append_ws. */ 373 void set_suppress_append_ws (bool suppress) 374 { m_suppress_append_ws = suppress; } 375 376 /* Return true if we only have one completion, and it matches 377 exactly the completion word. I.e., completing results in what we 378 already have. */ 379 bool completes_to_completion_word (const char *word); 380 381 /* Get a reference to the shared (between all the multiple symbol 382 name comparison calls) completion_match_result object, ready for 383 another symbol name match sequence. */ 384 completion_match_result &reset_completion_match_result () 385 { 386 completion_match_result &res = m_completion_match_result; 387 388 /* Clear any previous match. */ 389 res.match.clear (); 390 res.match_for_lcd.clear (); 391 return m_completion_match_result; 392 } 393 394 /* True if we have any completion match recorded. */ 395 bool have_completions () const 396 { return htab_elements (m_entries_hash) > 0; } 397 398 /* Discard the current completion match list and the current 399 LCD. */ 400 void discard_completions (); 401 402 /* Build a completion_result containing the list of completion 403 matches to hand over to readline. The parameters are as in 404 rl_attempted_completion_function. */ 405 completion_result build_completion_result (const char *text, 406 int start, int end); 407 408 private: 409 410 /* The type that we place into the m_entries_hash hash table. */ 411 class completion_hash_entry; 412 413 /* Add the completion NAME to the list of generated completions if 414 it is not there already. If false is returned, too many 415 completions were found. */ 416 bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name, 417 completion_match_for_lcd *match_for_lcd, 418 const char *text, const char *word); 419 420 /* Ensure that the lowest common denominator held in the member variable 421 M_LOWEST_COMMON_DENOMINATOR is valid. This method must be called if 422 there is any chance that new completions have been added to the 423 tracker before the lowest common denominator is read. */ 424 void recompute_lowest_common_denominator (); 425 426 /* Callback used from recompute_lowest_common_denominator, called for 427 every entry in m_entries_hash. */ 428 void recompute_lcd_visitor (completion_hash_entry *entry); 429 430 /* Completion match outputs returned by the symbol name matching 431 routines (see symbol_name_matcher_ftype). These results are only 432 valid for a single match call. This is here in order to be able 433 to conveniently share the same storage among all the calls to the 434 symbol name matching routines. */ 435 completion_match_result m_completion_match_result; 436 437 /* The completion matches found so far, in a hash table, for 438 duplicate elimination as entries are added. Otherwise the user 439 is left scratching his/her head: readline and complete_command 440 will remove duplicates, and if removal of duplicates there brings 441 the total under max_completions the user may think gdb quit 442 searching too early. */ 443 htab_t m_entries_hash = NULL; 444 445 /* If non-zero, then this is the quote char that needs to be 446 appended after completion (iff we have a unique completion). We 447 don't rely on readline appending the quote char as delimiter as 448 then readline wouldn't append the ' ' after the completion. 449 I.e., we want this: 450 451 before tab: "b 'function(" 452 after tab: "b 'function()' " 453 */ 454 int m_quote_char = '\0'; 455 456 /* If true, the completer has its own idea of "word" point, and 457 doesn't want to rely on readline computing it based on brkchars. 458 Set in the handle_brkchars phase. */ 459 bool m_use_custom_word_point = false; 460 461 /* The completer's idea of where the "word" we were looking at is 462 relative to RL_LINE_BUFFER. This is advanced in the 463 handle_brkchars phase as the completer discovers potential 464 completable words. */ 465 int m_custom_word_point = 0; 466 467 /* If true, tell readline to skip appending a whitespace after the 468 completion. Automatically set if we have a unique completion 469 that already has a space at the end. A completer may also 470 explicitly set this. E.g., the linespec completer sets this when 471 the completion ends with the ":" separator between filename and 472 function name. */ 473 bool m_suppress_append_ws = false; 474 475 /* Our idea of lowest common denominator to hand over to readline. 476 See intro. */ 477 char *m_lowest_common_denominator = NULL; 478 479 /* If true, the LCD is unique. I.e., all completions had the same 480 MATCH_FOR_LCD substring, even if the completions were different. 481 For example, if "break function<tab>" found "a::function()" and 482 "b::function()", the LCD will be "function()" in both cases and 483 so we want to tell readline to complete the line with 484 "function()", instead of showing all the possible 485 completions. */ 486 bool m_lowest_common_denominator_unique = false; 487 488 /* True if the value in M_LOWEST_COMMON_DENOMINATOR is correct. This is 489 set to true each time RECOMPUTE_LOWEST_COMMON_DENOMINATOR is called, 490 and reset to false whenever a new completion is added. */ 491 bool m_lowest_common_denominator_valid = false; 492 493 /* To avoid calls to xrealloc in RECOMPUTE_LOWEST_COMMON_DENOMINATOR, we 494 track the maximum possible size of the lowest common denominator, 495 which we know as each completion is added. */ 496 size_t m_lowest_common_denominator_max_length = 0; 497 }; 498 499 /* Return a string to hand off to readline as a completion match 500 candidate, potentially composed of parts of MATCH_NAME and of 501 TEXT/WORD. For a description of TEXT/WORD see completer_ftype. */ 502 503 extern gdb::unique_xmalloc_ptr<char> 504 make_completion_match_str (const char *match_name, 505 const char *text, const char *word); 506 507 /* Like above, but takes ownership of MATCH_NAME (i.e., can 508 reuse/return it). */ 509 510 extern gdb::unique_xmalloc_ptr<char> 511 make_completion_match_str (gdb::unique_xmalloc_ptr<char> &&match_name, 512 const char *text, const char *word); 513 514 extern void gdb_display_match_list (char **matches, int len, int max, 515 const struct match_list_displayer *); 516 517 extern const char *get_max_completions_reached_message (void); 518 519 extern void complete_line (completion_tracker &tracker, 520 const char *text, 521 const char *line_buffer, 522 int point); 523 524 /* Complete LINE and return completion results. For completion purposes, 525 cursor position is assumed to be at the end of LINE. WORD is set to 526 the end of word to complete. QUOTE_CHAR is set to the opening quote 527 character if we found an unclosed quoted substring, '\0' otherwise. */ 528 extern completion_result 529 complete (const char *line, char const **word, int *quote_char); 530 531 /* Find the bounds of the word in TEXT for completion purposes, and 532 return a pointer to the end of the word. Calls the completion 533 machinery for a handle_brkchars phase (using TRACKER) to figure out 534 the right work break characters for the command in TEXT. 535 QUOTE_CHAR, if non-null, is set to the opening quote character if 536 we found an unclosed quoted substring, '\0' otherwise. */ 537 extern const char *completion_find_completion_word (completion_tracker &tracker, 538 const char *text, 539 int *quote_char); 540 541 542 /* Assuming TEXT is an expression in the current language, find the 543 completion word point for TEXT, emulating the algorithm readline 544 uses to find the word point, using the current language's word 545 break characters. */ 546 const char *advance_to_expression_complete_word_point 547 (completion_tracker &tracker, const char *text); 548 549 /* Assuming TEXT is an filename, find the completion word point for 550 TEXT, emulating the algorithm readline uses to find the word 551 point. */ 552 extern const char *advance_to_filename_complete_word_point 553 (completion_tracker &tracker, const char *text); 554 555 extern char **gdb_rl_attempted_completion_function (const char *text, 556 int start, int end); 557 558 extern void noop_completer (struct cmd_list_element *, 559 completion_tracker &tracker, 560 const char *, const char *); 561 562 extern void filename_completer (struct cmd_list_element *, 563 completion_tracker &tracker, 564 const char *, const char *); 565 566 extern void expression_completer (struct cmd_list_element *, 567 completion_tracker &tracker, 568 const char *, const char *); 569 570 extern void location_completer (struct cmd_list_element *, 571 completion_tracker &tracker, 572 const char *, const char *); 573 574 extern void symbol_completer (struct cmd_list_element *, 575 completion_tracker &tracker, 576 const char *, const char *); 577 578 extern void command_completer (struct cmd_list_element *, 579 completion_tracker &tracker, 580 const char *, const char *); 581 582 extern void signal_completer (struct cmd_list_element *, 583 completion_tracker &tracker, 584 const char *, const char *); 585 586 extern void reg_or_group_completer (struct cmd_list_element *, 587 completion_tracker &tracker, 588 const char *, const char *); 589 590 extern void reggroup_completer (struct cmd_list_element *, 591 completion_tracker &tracker, 592 const char *, const char *); 593 594 extern const char *get_gdb_completer_quote_characters (void); 595 596 extern char *gdb_completion_word_break_characters (void); 597 598 /* Set the word break characters array to BREAK_CHARS. This function 599 is useful as const-correct alternative to direct assignment to 600 rl_completer_word_break_characters, which is "char *", 601 not "const char *". */ 602 extern void set_rl_completer_word_break_characters (const char *break_chars); 603 604 /* Get the matching completer_handle_brkchars_ftype function for FN. 605 FN is one of the core completer functions above (filename, 606 location, symbol, etc.). This function is useful for cases when 607 the completer doesn't know the type of the completion until some 608 calculation is done (e.g., for Python functions). */ 609 610 extern completer_handle_brkchars_ftype * 611 completer_handle_brkchars_func_for_completer (completer_ftype *fn); 612 613 /* Exported to linespec.c */ 614 615 /* Return a list of all source files whose names begin with matching 616 TEXT. */ 617 extern completion_list complete_source_filenames (const char *text); 618 619 /* Complete on expressions. Often this means completing on symbol 620 names, but some language parsers also have support for completing 621 field names. */ 622 extern void complete_expression (completion_tracker &tracker, 623 const char *text, const char *word); 624 625 /* Called by custom word point completers that want to recurse into 626 the completion machinery to complete a command. Used to complete 627 COMMAND in "thread apply all COMMAND", for example. Note that 628 unlike command_completer, this fully recurses into the proper 629 completer for COMMAND, so that e.g., 630 631 (gdb) thread apply all print -[TAB] 632 633 does the right thing and show the print options. */ 634 extern void complete_nested_command_line (completion_tracker &tracker, 635 const char *text); 636 637 extern const char *skip_quoted_chars (const char *, const char *, 638 const char *); 639 640 extern const char *skip_quoted (const char *); 641 642 /* Maximum number of candidates to consider before the completer 643 bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values 644 disable limiting. */ 645 646 extern int max_completions; 647 648 #endif /* defined (COMPLETER_H) */ 649