1 /* Header for GDB line completion. 2 Copyright (C) 2000-2023 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-hashtab.h" 21 #include "gdbsupport/gdb_vecs.h" 22 #include "command.h" 23 24 /* Types of functions in struct match_list_displayer. */ 25 26 struct match_list_displayer; 27 28 typedef void mld_crlf_ftype (const struct match_list_displayer *); 29 typedef void mld_putch_ftype (const struct match_list_displayer *, int); 30 typedef void mld_puts_ftype (const struct match_list_displayer *, 31 const char *); 32 typedef void mld_flush_ftype (const struct match_list_displayer *); 33 typedef void mld_erase_entire_line_ftype (const struct match_list_displayer *); 34 typedef void mld_beep_ftype (const struct match_list_displayer *); 35 typedef int mld_read_key_ftype (const struct match_list_displayer *); 36 37 /* Interface between CLI/TUI and gdb_match_list_displayer. */ 38 39 struct match_list_displayer 40 { 41 /* The screen dimensions to work with when displaying matches. */ 42 int height, width; 43 44 /* Print cr,lf. */ 45 mld_crlf_ftype *crlf; 46 47 /* Not "putc" to avoid issues where it is a stdio macro. Sigh. */ 48 mld_putch_ftype *putch; 49 50 /* Print a string. */ 51 mld_puts_ftype *puts; 52 53 /* Flush all accumulated output. */ 54 mld_flush_ftype *flush; 55 56 /* Erase the currently line on the terminal (but don't discard any text the 57 user has entered, readline may shortly re-print it). */ 58 mld_erase_entire_line_ftype *erase_entire_line; 59 60 /* Ring the bell. */ 61 mld_beep_ftype *beep; 62 63 /* Read one key. */ 64 mld_read_key_ftype *read_key; 65 }; 66 67 /* A list of completion candidates. Each element is a malloc string, 68 because ownership of the strings is transferred to readline, which 69 calls free on each element. */ 70 typedef std::vector<gdb::unique_xmalloc_ptr<char>> completion_list; 71 72 /* The result of a successful completion match. When doing symbol 73 comparison, we use the symbol search name for the symbol name match 74 check, but the matched name that is shown to the user may be 75 different. For example, Ada uses encoded names for lookup, but 76 then wants to decode the symbol name to show to the user, and also 77 in some cases wrap the matched name in "<sym>" (meaning we can't 78 always use the symbol's print name). */ 79 80 class completion_match 81 { 82 public: 83 /* Get the completion match result. See m_match/m_storage's 84 descriptions. */ 85 const char *match () 86 { return m_match; } 87 88 /* Set the completion match result. See m_match/m_storage's 89 descriptions. */ 90 void set_match (const char *match) 91 { m_match = match; } 92 93 /* Get temporary storage for generating a match result, dynamically. 94 The built string is only good until the next clear() call. I.e., 95 good until the next symbol comparison. */ 96 std::string &storage () 97 { return m_storage; } 98 99 /* Prepare for another completion matching sequence. */ 100 void clear () 101 { 102 m_match = NULL; 103 m_storage.clear (); 104 } 105 106 private: 107 /* The completion match result. This can either be a pointer into 108 M_STORAGE string, or it can be a pointer into the some other 109 string that outlives the completion matching sequence (usually, a 110 pointer to a symbol's name). */ 111 const char *m_match; 112 113 /* Storage a symbol comparison routine can use for generating a 114 match result, dynamically. The built string is only good until 115 the next clear() call. I.e., good until the next symbol 116 comparison. */ 117 std::string m_storage; 118 }; 119 120 /* The result of a successful completion match, but for least common 121 denominator (LCD) computation. Some completers provide matches 122 that don't start with the completion "word". E.g., completing on 123 "b push_ba" on a C++ program usually completes to 124 std::vector<...>::push_back, std::string::push_back etc. In such 125 case, the symbol comparison routine will set the LCD match to point 126 into the "push_back" substring within the symbol's name string. 127 Also, in some cases, the symbol comparison routine will want to 128 ignore parts of the symbol name for LCD purposes, such as for 129 example symbols with abi tags in C++. In such cases, the symbol 130 comparison routine will set MARK_IGNORED_RANGE to mark the ignored 131 substrings of the matched string. The resulting LCD string with 132 the ignored parts stripped out is computed at the end of a 133 completion match sequence iff we had a positive match. */ 134 135 class completion_match_for_lcd 136 { 137 public: 138 /* Get the resulting LCD, after a successful match. */ 139 const char *match () 140 { return m_match; } 141 142 /* Set the match for LCD. See m_match's description. */ 143 void set_match (const char *match) 144 { m_match = match; } 145 146 /* Mark the range between [BEGIN, END) as ignored. */ 147 void mark_ignored_range (const char *begin, const char *end) 148 { m_ignored_ranges.emplace_back (begin, end); } 149 150 /* Get the resulting LCD, after a successful match. If there are 151 ignored ranges, then this builds a new string with the ignored 152 parts removed (and stores it internally). As such, the result of 153 this call is only good for the current completion match 154 sequence. */ 155 const char *finish () 156 { 157 if (m_ignored_ranges.empty ()) 158 return m_match; 159 else 160 { 161 m_finished_storage.clear (); 162 163 const char *prev = m_match; 164 for (const auto &range : m_ignored_ranges) 165 { 166 m_finished_storage.append (prev, range.first); 167 prev = range.second; 168 } 169 m_finished_storage.append (prev); 170 171 return m_finished_storage.c_str (); 172 } 173 } 174 175 /* Prepare for another completion matching sequence. */ 176 void clear () 177 { 178 m_match = NULL; 179 m_ignored_ranges.clear (); 180 } 181 182 private: 183 /* The completion match result for LCD. This is usually either a 184 pointer into to a substring within a symbol's name, or to the 185 storage of the pairing completion_match object. */ 186 const char *m_match; 187 188 /* The ignored substring ranges within M_MATCH. E.g., if we were 189 looking for completion matches for C++ functions starting with 190 "functio" 191 and successfully match: 192 "function[abi:cxx11](int)" 193 the ignored ranges vector will contain an entry that delimits the 194 "[abi:cxx11]" substring, such that calling finish() results in: 195 "function(int)" 196 */ 197 std::vector<std::pair<const char *, const char *>> m_ignored_ranges; 198 199 /* Storage used by the finish() method, if it has to compute a new 200 string. */ 201 std::string m_finished_storage; 202 }; 203 204 /* Convenience aggregate holding info returned by the symbol name 205 matching routines (see symbol_name_matcher_ftype). */ 206 struct completion_match_result 207 { 208 /* The completion match candidate. */ 209 completion_match match; 210 211 /* The completion match, for LCD computation purposes. */ 212 completion_match_for_lcd match_for_lcd; 213 214 /* Convenience that sets both MATCH and MATCH_FOR_LCD. M_FOR_LCD is 215 optional. If not specified, defaults to M. */ 216 void set_match (const char *m, const char *m_for_lcd = NULL) 217 { 218 match.set_match (m); 219 if (m_for_lcd == NULL) 220 match_for_lcd.set_match (m); 221 else 222 match_for_lcd.set_match (m_for_lcd); 223 } 224 }; 225 226 /* The final result of a completion that is handed over to either 227 readline or the "completion" command (which pretends to be 228 readline). Mainly a wrapper for a readline-style match list array, 229 though other bits of info are included too. */ 230 231 struct completion_result 232 { 233 /* Create an empty result. */ 234 completion_result (); 235 236 /* Create a result. */ 237 completion_result (char **match_list, size_t number_matches, 238 bool completion_suppress_append); 239 240 /* Destroy a result. */ 241 ~completion_result (); 242 243 DISABLE_COPY_AND_ASSIGN (completion_result); 244 245 /* Move a result. */ 246 completion_result (completion_result &&rhs) noexcept; 247 248 /* Release ownership of the match list array. */ 249 char **release_match_list (); 250 251 /* Sort the match list. */ 252 void sort_match_list (); 253 254 private: 255 /* Destroy the match list array and its contents. */ 256 void reset_match_list (); 257 258 public: 259 /* (There's no point in making these fields private, since the whole 260 point of this wrapper is to build data in the layout expected by 261 readline. Making them private would require adding getters for 262 the "complete" command, which would expose the same 263 implementation details anyway.) */ 264 265 /* The match list array, in the format that readline expects. 266 match_list[0] contains the common prefix. The real match list 267 starts at index 1. The list is NULL terminated. If there's only 268 one match, then match_list[1] is NULL. If there are no matches, 269 then this is NULL. */ 270 char **match_list; 271 /* The number of matched completions in MATCH_LIST. Does not 272 include the NULL terminator or the common prefix. */ 273 size_t number_matches; 274 275 /* Whether readline should suppress appending a whitespace, when 276 there's only one possible completion. */ 277 bool completion_suppress_append; 278 }; 279 280 /* Object used by completers to build a completion match list to hand 281 over to readline. It tracks: 282 283 - How many unique completions have been generated, to terminate 284 completion list generation early if the list has grown to a size 285 so large as to be useless. This helps avoid GDB seeming to lock 286 up in the event the user requests to complete on something vague 287 that necessitates the time consuming expansion of many symbol 288 tables. 289 290 - The completer's idea of least common denominator (aka the common 291 prefix) between all completion matches to hand over to readline. 292 Some completers provide matches that don't start with the 293 completion "word". E.g., completing on "b push_ba" on a C++ 294 program usually completes to std::vector<...>::push_back, 295 std::string::push_back etc. If all matches happen to start with 296 "std::", then readline would figure out that the lowest common 297 denominator is "std::", and thus would do a partial completion 298 with that. I.e., it would replace "push_ba" in the input buffer 299 with "std::", losing the original "push_ba", which is obviously 300 undesirable. To avoid that, such completers pass the substring 301 of the match that matters for common denominator computation as 302 MATCH_FOR_LCD argument to add_completion. The end result is 303 passed to readline in gdb_rl_attempted_completion_function. 304 305 - The custom word point to hand over to readline, for completers 306 that parse the input string in order to dynamically adjust 307 themselves depending on exactly what they're completing. E.g., 308 the linespec completer needs to bypass readline's too-simple word 309 breaking algorithm. 310 */ 311 class completion_tracker 312 { 313 public: 314 completion_tracker (); 315 ~completion_tracker (); 316 317 DISABLE_COPY_AND_ASSIGN (completion_tracker); 318 319 /* Add the completion NAME to the list of generated completions if 320 it is not there already. If too many completions were already 321 found, this throws an error. */ 322 void add_completion (gdb::unique_xmalloc_ptr<char> name, 323 completion_match_for_lcd *match_for_lcd = NULL, 324 const char *text = NULL, const char *word = NULL); 325 326 /* Add all completions matches in LIST. Elements are moved out of 327 LIST. */ 328 void add_completions (completion_list &&list); 329 330 /* Remove completion matching NAME from the completion list, does nothing 331 if NAME is not already in the completion list. */ 332 void remove_completion (const char *name); 333 334 /* Set the quote char to be appended after a unique completion is 335 added to the input line. Set to '\0' to clear. See 336 m_quote_char's description. */ 337 void set_quote_char (int quote_char) 338 { m_quote_char = quote_char; } 339 340 /* The quote char to be appended after a unique completion is added 341 to the input line. Returns '\0' if no quote char has been set. 342 See m_quote_char's description. */ 343 int quote_char () { return m_quote_char; } 344 345 /* Tell the tracker that the current completer wants to provide a 346 custom word point instead of a list of a break chars, in the 347 handle_brkchars phase. Such completers must also compute their 348 completions then. */ 349 void set_use_custom_word_point (bool enable) 350 { m_use_custom_word_point = enable; } 351 352 /* Whether the current completer computes a custom word point. */ 353 bool use_custom_word_point () const 354 { return m_use_custom_word_point; } 355 356 /* The custom word point. */ 357 int custom_word_point () const 358 { return m_custom_word_point; } 359 360 /* Set the custom word point to POINT. */ 361 void set_custom_word_point (int point) 362 { m_custom_word_point = point; } 363 364 /* Advance the custom word point by LEN. */ 365 void advance_custom_word_point_by (int len); 366 367 /* Whether to tell readline to skip appending a whitespace after the 368 completion. See m_suppress_append_ws. */ 369 bool suppress_append_ws () const 370 { return m_suppress_append_ws; } 371 372 /* Set whether to tell readline to skip appending a whitespace after 373 the completion. See m_suppress_append_ws. */ 374 void set_suppress_append_ws (bool suppress) 375 { m_suppress_append_ws = suppress; } 376 377 /* Return true if we only have one completion, and it matches 378 exactly the completion word. I.e., completing results in what we 379 already have. */ 380 bool completes_to_completion_word (const char *word); 381 382 /* Get a reference to the shared (between all the multiple symbol 383 name comparison calls) completion_match_result object, ready for 384 another symbol name match sequence. */ 385 completion_match_result &reset_completion_match_result () 386 { 387 completion_match_result &res = m_completion_match_result; 388 389 /* Clear any previous match. */ 390 res.match.clear (); 391 res.match_for_lcd.clear (); 392 return m_completion_match_result; 393 } 394 395 /* True if we have any completion match recorded. */ 396 bool have_completions () const 397 { return htab_elements (m_entries_hash.get ()) > 0; } 398 399 /* Discard the current completion match list and the current 400 LCD. */ 401 void discard_completions (); 402 403 /* Build a completion_result containing the list of completion 404 matches to hand over to readline. The parameters are as in 405 rl_attempted_completion_function. */ 406 completion_result build_completion_result (const char *text, 407 int start, int end); 408 409 private: 410 411 /* The type that we place into the m_entries_hash hash table. */ 412 class completion_hash_entry; 413 414 /* Add the completion NAME to the list of generated completions if 415 it is not there already. If false is returned, too many 416 completions were found. */ 417 bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name, 418 completion_match_for_lcd *match_for_lcd, 419 const char *text, const char *word); 420 421 /* Ensure that the lowest common denominator held in the member variable 422 M_LOWEST_COMMON_DENOMINATOR is valid. This method must be called if 423 there is any chance that new completions have been added to the 424 tracker before the lowest common denominator is read. */ 425 void recompute_lowest_common_denominator (); 426 427 /* Callback used from recompute_lowest_common_denominator, called for 428 every entry in m_entries_hash. */ 429 void recompute_lcd_visitor (completion_hash_entry *entry); 430 431 /* Completion match outputs returned by the symbol name matching 432 routines (see symbol_name_matcher_ftype). These results are only 433 valid for a single match call. This is here in order to be able 434 to conveniently share the same storage among all the calls to the 435 symbol name matching routines. */ 436 completion_match_result m_completion_match_result; 437 438 /* The completion matches found so far, in a hash table, for 439 duplicate elimination as entries are added. Otherwise the user 440 is left scratching his/her head: readline and complete_command 441 will remove duplicates, and if removal of duplicates there brings 442 the total under max_completions the user may think gdb quit 443 searching too early. */ 444 htab_up m_entries_hash; 445 446 /* If non-zero, then this is the quote char that needs to be 447 appended after completion (iff we have a unique completion). We 448 don't rely on readline appending the quote char as delimiter as 449 then readline wouldn't append the ' ' after the completion. 450 I.e., we want this: 451 452 before tab: "b 'function(" 453 after tab: "b 'function()' " 454 */ 455 int m_quote_char = '\0'; 456 457 /* If true, the completer has its own idea of "word" point, and 458 doesn't want to rely on readline computing it based on brkchars. 459 Set in the handle_brkchars phase. */ 460 bool m_use_custom_word_point = false; 461 462 /* The completer's idea of where the "word" we were looking at is 463 relative to RL_LINE_BUFFER. This is advanced in the 464 handle_brkchars phase as the completer discovers potential 465 completable words. */ 466 int m_custom_word_point = 0; 467 468 /* If true, tell readline to skip appending a whitespace after the 469 completion. Automatically set if we have a unique completion 470 that already has a space at the end. A completer may also 471 explicitly set this. E.g., the linespec completer sets this when 472 the completion ends with the ":" separator between filename and 473 function name. */ 474 bool m_suppress_append_ws = false; 475 476 /* Our idea of lowest common denominator to hand over to readline. 477 See intro. */ 478 char *m_lowest_common_denominator = NULL; 479 480 /* If true, the LCD is unique. I.e., all completions had the same 481 MATCH_FOR_LCD substring, even if the completions were different. 482 For example, if "break function<tab>" found "a::function()" and 483 "b::function()", the LCD will be "function()" in both cases and 484 so we want to tell readline to complete the line with 485 "function()", instead of showing all the possible 486 completions. */ 487 bool m_lowest_common_denominator_unique = false; 488 489 /* True if the value in M_LOWEST_COMMON_DENOMINATOR is correct. This is 490 set to true each time RECOMPUTE_LOWEST_COMMON_DENOMINATOR is called, 491 and reset to false whenever a new completion is added. */ 492 bool m_lowest_common_denominator_valid = false; 493 494 /* To avoid calls to xrealloc in RECOMPUTE_LOWEST_COMMON_DENOMINATOR, we 495 track the maximum possible size of the lowest common denominator, 496 which we know as each completion is added. */ 497 size_t m_lowest_common_denominator_max_length = 0; 498 }; 499 500 /* Return a string to hand off to readline as a completion match 501 candidate, potentially composed of parts of MATCH_NAME and of 502 TEXT/WORD. For a description of TEXT/WORD see completer_ftype. */ 503 504 extern gdb::unique_xmalloc_ptr<char> 505 make_completion_match_str (const char *match_name, 506 const char *text, const char *word); 507 508 /* Like above, but takes ownership of MATCH_NAME (i.e., can 509 reuse/return it). */ 510 511 extern gdb::unique_xmalloc_ptr<char> 512 make_completion_match_str (gdb::unique_xmalloc_ptr<char> &&match_name, 513 const char *text, const char *word); 514 515 extern void gdb_display_match_list (char **matches, int len, int max, 516 const struct match_list_displayer *); 517 518 extern const char *get_max_completions_reached_message (void); 519 520 extern void complete_line (completion_tracker &tracker, 521 const char *text, 522 const char *line_buffer, 523 int point); 524 525 /* Complete LINE and return completion results. For completion purposes, 526 cursor position is assumed to be at the end of LINE. WORD is set to 527 the end of word to complete. QUOTE_CHAR is set to the opening quote 528 character if we found an unclosed quoted substring, '\0' otherwise. */ 529 extern completion_result 530 complete (const char *line, char const **word, int *quote_char); 531 532 /* Find the bounds of the word in TEXT for completion purposes, and 533 return a pointer to the end of the word. Calls the completion 534 machinery for a handle_brkchars phase (using TRACKER) to figure out 535 the right work break characters for the command in TEXT. 536 QUOTE_CHAR, if non-null, is set to the opening quote character if 537 we found an unclosed quoted substring, '\0' otherwise. */ 538 extern const char *completion_find_completion_word (completion_tracker &tracker, 539 const char *text, 540 int *quote_char); 541 542 543 /* Assuming TEXT is an expression in the current language, find the 544 completion word point for TEXT, emulating the algorithm readline 545 uses to find the word point, using the current language's word 546 break characters. */ 547 const char *advance_to_expression_complete_word_point 548 (completion_tracker &tracker, const char *text); 549 550 /* Assuming TEXT is an filename, find the completion word point for 551 TEXT, emulating the algorithm readline uses to find the word 552 point. */ 553 extern const char *advance_to_filename_complete_word_point 554 (completion_tracker &tracker, const char *text); 555 556 extern char **gdb_rl_attempted_completion_function (const char *text, 557 int start, int end); 558 559 extern void noop_completer (struct cmd_list_element *, 560 completion_tracker &tracker, 561 const char *, const char *); 562 563 extern void filename_completer (struct cmd_list_element *, 564 completion_tracker &tracker, 565 const char *, const char *); 566 567 extern void expression_completer (struct cmd_list_element *, 568 completion_tracker &tracker, 569 const char *, const char *); 570 571 extern void location_completer (struct cmd_list_element *, 572 completion_tracker &tracker, 573 const char *, const char *); 574 575 extern void symbol_completer (struct cmd_list_element *, 576 completion_tracker &tracker, 577 const char *, const char *); 578 579 extern void command_completer (struct cmd_list_element *, 580 completion_tracker &tracker, 581 const char *, const char *); 582 583 extern void signal_completer (struct cmd_list_element *, 584 completion_tracker &tracker, 585 const char *, const char *); 586 587 extern void reg_or_group_completer (struct cmd_list_element *, 588 completion_tracker &tracker, 589 const char *, const char *); 590 591 extern void reggroup_completer (struct cmd_list_element *, 592 completion_tracker &tracker, 593 const char *, const char *); 594 595 extern const char *get_gdb_completer_quote_characters (void); 596 597 extern char *gdb_completion_word_break_characters (void); 598 599 /* Set the word break characters array to BREAK_CHARS. This function 600 is useful as const-correct alternative to direct assignment to 601 rl_completer_word_break_characters, which is "char *", 602 not "const char *". */ 603 extern void set_rl_completer_word_break_characters (const char *break_chars); 604 605 /* Get the matching completer_handle_brkchars_ftype function for FN. 606 FN is one of the core completer functions above (filename, 607 location, symbol, etc.). This function is useful for cases when 608 the completer doesn't know the type of the completion until some 609 calculation is done (e.g., for Python functions). */ 610 611 extern completer_handle_brkchars_ftype * 612 completer_handle_brkchars_func_for_completer (completer_ftype *fn); 613 614 /* Exported to linespec.c */ 615 616 /* Return a list of all source files whose names begin with matching 617 TEXT. */ 618 extern completion_list complete_source_filenames (const char *text); 619 620 /* Complete on expressions. Often this means completing on symbol 621 names, but some language parsers also have support for completing 622 field names. */ 623 extern void complete_expression (completion_tracker &tracker, 624 const char *text, const char *word); 625 626 /* Called by custom word point completers that want to recurse into 627 the completion machinery to complete a command. Used to complete 628 COMMAND in "thread apply all COMMAND", for example. Note that 629 unlike command_completer, this fully recurses into the proper 630 completer for COMMAND, so that e.g., 631 632 (gdb) thread apply all print -[TAB] 633 634 does the right thing and show the print options. */ 635 extern void complete_nested_command_line (completion_tracker &tracker, 636 const char *text); 637 638 extern const char *skip_quoted_chars (const char *, const char *, 639 const char *); 640 641 extern const char *skip_quoted (const char *); 642 643 /* Maximum number of candidates to consider before the completer 644 bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values 645 disable limiting. */ 646 647 extern int max_completions; 648 649 #endif /* defined (COMPLETER_H) */ 650