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