gdb/linespec.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 (LINESPEC_H)
  18 #define LINESPEC_H 1
  19
  20 struct symtab;
  21
  22 #include "location.h"
  23 #include "vec.h"
  24
  25 /* Flags to pass to decode_line_1 and decode_line_full.  */
  26
  27 enum decode_line_flags
  28   {
  29     /* Set this flag if you want the resulting SALs to describe the
  30        first line of indicated functions.  */
  31     DECODE_LINE_FUNFIRSTLINE = 1,
  32
  33     /* Set this flag if you want "list mode".  In this mode, a
  34        FILE:LINE linespec will always return a result, and such
  35        linespecs will not be expanded to all matches.  */
  36     DECODE_LINE_LIST_MODE = 2
  37   };
  38
  39 /* decode_line_full returns a vector of these.  */
  40
  41 struct linespec_sals
  42 {
  43   /* This is the location corresponding to the sals contained in this
  44      object.  It can be passed as the FILTER argument to future calls
  45      to decode_line_full.  This is freed by the linespec_result
  46      destructor.  */
  47   char *canonical;
  48
  49   /* Sals.  The 'sals' field is destroyed by the linespec_result
  50      destructor.  */
  51   struct symtabs_and_lines sals;
  52 };
  53
  54 typedef struct linespec_sals linespec_sals;
  55 DEF_VEC_O (linespec_sals);
  56
  57 /* An instance of this may be filled in by decode_line_1.  The caller
  58    must make copies of any data that it needs to keep.  */
  59
  60 struct linespec_result
  61 {
  62   linespec_result ()
  63     : special_display (0),
  64       pre_expanded (0),
  65       sals (NULL)
  66   {
  67   }
  68
  69   ~linespec_result ();
  70
  71   linespec_result (const linespec_result &) = delete;
  72   linespec_result &operator= (const linespec_result &) = delete;
  73
  74   /* If non-zero, the linespec should be displayed to the user.  This
  75      is used by "unusual" linespecs where the ordinary `info break'
  76      display mechanism would do the wrong thing.  */
  77   int special_display;
  78
  79   /* If non-zero, the linespec result should be considered to be a
  80      "pre-expanded" multi-location linespec.  A pre-expanded linespec
  81      holds all matching locations in a single linespec_sals
  82      object.  */
  83   int pre_expanded;
  84
  85   /* If PRE_EXPANDED is non-zero, this is set to the location entered
  86      by the user.  */
  87   event_location_up location;
  88
  89   /* The sals.  The vector will be freed by the destructor.  */
  90   VEC (linespec_sals) *sals;
  91 };
  92
  93 /* Decode a linespec using the provided default symtab and line.  */
  94
  95 extern struct symtabs_and_lines
  96         decode_line_1 (const struct event_location *location, int flags,
  97                        struct program_space *search_pspace,
  98                        struct symtab *default_symtab, int default_line);
  99
 100 /* Parse LOCATION and return results.  This is the "full"
 101    interface to this module, which handles multiple results
 102    properly.
 103
 104    For FLAGS, see decode_line_flags.  DECODE_LINE_LIST_MODE is not
 105    valid for this function.
 106
 107    If SEARCH_PSPACE is not NULL, symbol search is restricted to just
 108    that program space.
 109
 110    DEFAULT_SYMTAB and DEFAULT_LINE describe the default location.
 111    DEFAULT_SYMTAB can be NULL, in which case the current symtab and
 112    line are used.
 113
 114    CANONICAL is where the results are stored.  It must not be NULL.
 115
 116    SELECT_MODE must be one of the multiple_symbols_* constants, or
 117    NULL.  It determines how multiple results will be handled.  If
 118    NULL, the appropriate CLI value will be used.
 119
 120    FILTER can either be NULL or a string holding a canonical name.
 121    This is only valid when SELECT_MODE is multiple_symbols_all.
 122
 123    Multiple results are handled differently depending on the
 124    arguments:
 125
 126    . With multiple_symbols_cancel, an exception is thrown.
 127
 128    . With multiple_symbols_ask, a menu is presented to the user.  The
 129    user may select none, in which case an exception is thrown; or all,
 130    which is handled like multiple_symbols_all, below.  Otherwise,
 131    CANONICAL->SALS will have one entry for each name the user chose.
 132
 133    . With multiple_symbols_all, CANONICAL->SALS will have a single
 134    entry describing all the matching locations.  If FILTER is
 135    non-NULL, then only locations whose canonical name is equal (in the
 136    strcmp sense) to FILTER will be returned; all others will be
 137    filtered out.  */
 138
 139 extern void decode_line_full (const struct event_location *location, int flags,
 140                               struct program_space *search_pspace,
 141                               struct symtab *default_symtab, int default_line,
 142                               struct linespec_result *canonical,
 143                               const char *select_mode,
 144                               const char *filter);
 145
 146 /* Given a string, return the line specified by it, using the current
 147    source symtab and line as defaults.
 148    This is for commands like "list" and "breakpoint".  */
 149
 150 extern struct symtabs_and_lines decode_line_with_current_source (char *, int);
 151
 152 /* Given a string, return the line specified by it, using the last displayed
 153    codepoint's values as defaults, or nothing if they aren't valid.  */
 154
 155 extern struct symtabs_and_lines decode_line_with_last_displayed (char *, int);
 156
 157 /* Does P represent one of the keywords?  If so, return
 158    the keyword.  If not, return NULL.  */
 159
 160 extern const char *linespec_lexer_lex_keyword (const char *p);
 161
 162 /* Parse a line offset from STRING.  */
 163
 164 extern struct line_offset linespec_parse_line_offset (const char *string);
 165
 166 /* Return the quote characters permitted by the linespec parser.  */
 167
 168 extern const char *get_gdb_linespec_parser_quote_characters (void);
 169
 170 /* Does STRING represent an Ada operator?  If so, return the length
 171    of the decoded operator name.  If not, return 0.  */
 172
 173 extern int is_ada_operator (const char *string);
 174
 175 /* Find an instance of the character C in the string S that is outside
 176    of all parenthesis pairs, single-quoted strings, and double-quoted
 177    strings.  Also, ignore the char within a template name, like a ','
 178    within foo<int, int>.  */
 179
 180 extern const char *find_toplevel_char (const char *s, char c);
 181
 182 /* Find the end of the (first) linespec pointed to by *STRINGP.
 183    STRINGP will be advanced to this point.  */
 184
 185 extern void linespec_lex_to_end (char **stringp);
 186
 187 extern const char * const linespec_keywords[];
 188
 189 /* Complete a linespec.  */
 190
 191 extern void linespec_complete (completion_tracker &tracker,
 192                                const char *text);
 193
 194 /* Complete a function symbol, in linespec mode.  If SOURCE_FILENAME
 195    is non-NULL, limits completion to the list of functions defined in
 196    source files that match SOURCE_FILENAME.  */
 197
 198 extern void linespec_complete_function (completion_tracker &tracker,
 199                                         const char *function,
 200                                         const char *source_filename);
 201
 202 /* Complete a label symbol, in linespec mode.  Only labels of
 203    functions named FUNCTION_NAME are considered.  If SOURCE_FILENAME
 204    is non-NULL, limits completion to labels of functions defined in
 205    source files that match SOURCE_FILENAME.  */
 206
 207 extern void linespec_complete_label (completion_tracker &tracker,
 208                                      const struct language_defn *language,
 209                                      const char *source_filename,
 210                                      const char *function_name,
 211                                      const char *label_name);
 212
 213 /* Evaluate the expression pointed to by EXP_PTR into a CORE_ADDR,
 214    advancing EXP_PTR past any parsed text.  */
 215
 216 extern CORE_ADDR linespec_expression_to_pc (const char **exp_ptr);
 217 #endif /* defined (LINESPEC_H) */