gdb/completer.h

   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 extern void gdb_display_match_list (char **matches, int len, int max,
  67                                     const struct match_list_displayer *);
  68
  69 extern const char *get_max_completions_reached_message (void);
  70
  71 extern VEC (char_ptr) *complete_line (const char *text,
  72                                       const char *line_buffer,
  73                                       int point);
  74
  75 extern char *readline_line_completion_function (const char *text,
  76                                                 int matches);
  77
  78 extern VEC (char_ptr) *noop_completer (struct cmd_list_element *,
  79                                        const char *, const char *);
  80
  81 extern VEC (char_ptr) *filename_completer (struct cmd_list_element *,
  82                                            const char *, const char *);
  83
  84 extern VEC (char_ptr) *expression_completer (struct cmd_list_element *,
  85                                              const char *, const char *);
  86
  87 extern VEC (char_ptr) *location_completer (struct cmd_list_element *,
  88                                            const char *, const char *);
  89
  90 extern VEC (char_ptr) *symbol_completer (struct cmd_list_element *,
  91                                          const char *, const char *);
  92
  93 extern VEC (char_ptr) *command_completer (struct cmd_list_element *,
  94                                           const char *, const char *);
  95
  96 extern VEC (char_ptr) *signal_completer (struct cmd_list_element *,
  97                                          const char *, const char *);
  98
  99 extern VEC (char_ptr) *reg_or_group_completer (struct cmd_list_element *,
 100                                                const char *, const char *);
 101
 102 extern VEC (char_ptr) *reggroup_completer (struct cmd_list_element *,
 103                                            const char *, const char *);
 104
 105 extern const char *get_gdb_completer_quote_characters (void);
 106
 107 extern char *gdb_completion_word_break_characters (void);
 108
 109 /* Set the word break characters array to BREAK_CHARS.  This function
 110    is useful as const-correct alternative to direct assignment to
 111    rl_completer_word_break_characters, which is "char *",
 112    not "const char *".  */
 113 extern void set_rl_completer_word_break_characters (const char *break_chars);
 114
 115 /* Get the matching completer_handle_brkchars_ftype function for FN.
 116    FN is one of the core completer functions above (filename,
 117    location, symbol, etc.).  This function is useful for cases when
 118    the completer doesn't know the type of the completion until some
 119    calculation is done (e.g., for Python functions).  */
 120
 121 extern completer_handle_brkchars_ftype *
 122   completer_handle_brkchars_func_for_completer (completer_ftype *fn);
 123
 124 /* Exported to linespec.c */
 125
 126 extern const char *skip_quoted_chars (const char *, const char *,
 127                                       const char *);
 128
 129 extern const char *skip_quoted (const char *);
 130
 131 /* Maximum number of candidates to consider before the completer
 132    bails by throwing MAX_COMPLETIONS_REACHED_ERROR.  Negative values
 133    disable limiting.  */
 134
 135 extern int max_completions;
 136
 137 /* Object to track how many unique completions have been generated.
 138    Used to limit the size of generated completion lists.  */
 139
 140 typedef htab_t completion_tracker_t;
 141
 142 /* Create a new completion tracker.
 143    The result is a hash table to track added completions, or NULL
 144    if max_completions <= 0.  If max_completions < 0, tracking is disabled.
 145    If max_completions == 0, the max is indeed zero.  */
 146
 147 extern completion_tracker_t new_completion_tracker (void);
 148
 149 /* Make a cleanup to free a completion tracker, and reset its pointer
 150    to NULL.  */
 151
 152 extern struct cleanup *make_cleanup_free_completion_tracker
 153                       (completion_tracker_t *tracker_ptr);
 154
 155 /* Return values for maybe_add_completion.  */
 156
 157 enum maybe_add_completion_enum
 158 {
 159   /* NAME has been recorded and max_completions has not been reached,
 160      or completion tracking is disabled (max_completions < 0).  */
 161   MAYBE_ADD_COMPLETION_OK,
 162
 163   /* NAME has been recorded and max_completions has been reached
 164      (thus the caller can stop searching).  */
 165   MAYBE_ADD_COMPLETION_OK_MAX_REACHED,
 166
 167   /* max-completions entries has been reached.
 168      Whether NAME is a duplicate or not is not determined.  */
 169   MAYBE_ADD_COMPLETION_MAX_REACHED,
 170
 171   /* NAME has already been recorded.
 172      Note that this is never returned if completion tracking is disabled
 173      (max_completions < 0).  */
 174   MAYBE_ADD_COMPLETION_DUPLICATE
 175 };
 176
 177 /* Add the completion NAME to the list of generated completions if
 178    it is not there already.
 179    If max_completions is negative, nothing is done, not even watching
 180    for duplicates, and MAYBE_ADD_COMPLETION_OK is always returned.
 181
 182    If MAYBE_ADD_COMPLETION_MAX_REACHED is returned, callers are required to
 183    record at least one more completion.  The final list will be pruned to
 184    max_completions, but recording at least one more than max_completions is
 185    the signal to the completion machinery that too many completions were
 186    found.  */
 187
 188 extern enum maybe_add_completion_enum
 189   maybe_add_completion (completion_tracker_t tracker, char *name);
 190
 191 /* Wrapper to throw MAX_COMPLETIONS_REACHED_ERROR.  */
 192
 193 extern void throw_max_completions_reached_error (void);
 194
 195 #endif /* defined (COMPLETER_H) */