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