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