varobj.h revision 1.6 
1/* GDB variable objects API.
2   Copyright (C) 1999-2016 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#ifndef VAROBJ_H
18#define VAROBJ_H 1
19
20#include "symtab.h"
21#include "gdbtypes.h"
22#include "vec.h"
23
24/* Enumeration for the format types */
25enum varobj_display_formats
26  {
27    FORMAT_NATURAL,		/* What gdb actually calls 'natural' */
28    FORMAT_BINARY,		/* Binary display                    */
29    FORMAT_DECIMAL,		/* Decimal display                   */
30    FORMAT_HEXADECIMAL,		/* Hex display                       */
31    FORMAT_OCTAL,		/* Octal display                     */
32    FORMAT_ZHEXADECIMAL		/* Zero padded hexadecimal	     */
33  };
34
35enum varobj_type
36  {
37    USE_SPECIFIED_FRAME,        /* Use the frame passed to varobj_create.  */
38    USE_CURRENT_FRAME,          /* Use the current frame.  */
39    USE_SELECTED_FRAME          /* Always reevaluate in selected frame.  */
40  };
41
42/* Enumerator describing if a variable object is in scope.  */
43enum varobj_scope_status
44  {
45    VAROBJ_IN_SCOPE = 0,        /* Varobj is scope, value available.  */
46    VAROBJ_NOT_IN_SCOPE = 1,    /* Varobj is not in scope, value not
47				   available, but varobj can become in
48				   scope later.  */
49    VAROBJ_INVALID = 2,         /* Varobj no longer has any value, and never
50				   will.  */
51  };
52
53/* String representations of gdb's format codes (defined in varobj.c).  */
54extern char *varobj_format_string[];
55
56/* Struct that describes a variable object instance.  */
57
58struct varobj;
59
60typedef struct varobj *varobj_p;
61DEF_VEC_P (varobj_p);
62
63typedef struct varobj_update_result_t
64{
65  struct varobj *varobj;
66  int type_changed;
67  int children_changed;
68  int changed;
69  enum varobj_scope_status status;
70  /* This variable is used internally by varobj_update to indicate if the
71     new value of varobj is already computed and installed, or has to
72     be yet installed.  Don't use this outside varobj.c.  */
73  int value_installed;
74
75  /* This will be non-NULL when new children were added to the varobj.
76     It lists the new children (which must necessarily come at the end
77     of the child list) added during an update.  The caller is
78     responsible for freeing this vector.  */
79  VEC (varobj_p) *newobj;
80} varobj_update_result;
81
82DEF_VEC_O (varobj_update_result);
83
84struct varobj_root;
85struct varobj_dynamic;
86
87/* Every variable in the system has a structure of this type defined
88   for it.  This structure holds all information necessary to manipulate
89   a particular object variable.  Members which must be freed are noted.  */
90struct varobj
91{
92  /* Alloc'd name of the variable for this object.  If this variable is a
93     child, then this name will be the child's source name.
94     (bar, not foo.bar).  */
95  /* NOTE: This is the "expression".  */
96  char *name;
97
98  /* Alloc'd expression for this child.  Can be used to create a
99     root variable corresponding to this child.  */
100  char *path_expr;
101
102  /* The alloc'd name for this variable's object.  This is here for
103     convenience when constructing this object's children.  */
104  char *obj_name;
105
106  /* Index of this variable in its parent or -1.  */
107  int index;
108
109  /* The type of this variable.  This can be NULL
110     for artificial variable objects -- currently, the "accessibility"
111     variable objects in C++.  */
112  struct type *type;
113
114  /* The value of this expression or subexpression.  A NULL value
115     indicates there was an error getting this value.
116     Invariant: if varobj_value_is_changeable_p (this) is non-zero,
117     the value is either NULL, or not lazy.  */
118  struct value *value;
119
120  /* The number of (immediate) children this variable has.  */
121  int num_children;
122
123  /* If this object is a child, this points to its immediate parent.  */
124  const struct varobj *parent;
125
126  /* Children of this object.  */
127  VEC (varobj_p) *children;
128
129  /* Description of the root variable.  Points to root variable for
130     children.  */
131  struct varobj_root *root;
132
133  /* The format of the output for this object.  */
134  enum varobj_display_formats format;
135
136  /* Was this variable updated via a varobj_set_value operation.  */
137  int updated;
138
139  /* Last print value.  */
140  char *print_value;
141
142  /* Is this variable frozen.  Frozen variables are never implicitly
143     updated by -var-update *
144     or -var-update <direct-or-indirect-parent>.  */
145  int frozen;
146
147  /* Is the value of this variable intentionally not fetched?  It is
148     not fetched if either the variable is frozen, or any parents is
149     frozen.  */
150  int not_fetched;
151
152  /* Sub-range of children which the MI consumer has requested.  If
153     FROM < 0 or TO < 0, means that all children have been
154     requested.  */
155  int from;
156  int to;
157
158  /* Dynamic part of varobj.  */
159  struct varobj_dynamic *dynamic;
160};
161
162/* Is the variable X one of our "fake" children?  */
163#define CPLUS_FAKE_CHILD(x) \
164((x) != NULL && (x)->type == NULL && (x)->value == NULL)
165
166/* The language specific vector */
167
168struct lang_varobj_ops
169{
170  /* The number of children of PARENT.  */
171  int (*number_of_children) (const struct varobj *parent);
172
173  /* The name (expression) of a root varobj.  The returned value must be freed
174     by the caller.  */
175  char *(*name_of_variable) (const struct varobj *parent);
176
177  /* The name of the INDEX'th child of PARENT.  The returned value must be
178     freed by the caller.  */
179  char *(*name_of_child) (const struct varobj *parent, int index);
180
181  /* Returns the rooted expression of CHILD, which is a variable
182     obtain that has some parent.  The returned value must be freed by the
183     caller.  */
184  char *(*path_expr_of_child) (const struct varobj *child);
185
186  /* The ``struct value *'' of the INDEX'th child of PARENT.  */
187  struct value *(*value_of_child) (const struct varobj *parent, int index);
188
189  /* The type of the INDEX'th child of PARENT.  */
190  struct type *(*type_of_child) (const struct varobj *parent, int index);
191
192  /* The current value of VAR.  The returned value must be freed by the
193     caller.  */
194  char *(*value_of_variable) (const struct varobj *var,
195			      enum varobj_display_formats format);
196
197  /* Return non-zero if changes in value of VAR must be detected and
198     reported by -var-update.  Return zero if -var-update should never
199     report changes of such values.  This makes sense for structures
200     (since the changes in children values will be reported separately),
201     or for artificial objects (like 'public' pseudo-field in C++).
202
203     Return value of 0 means that gdb need not call value_fetch_lazy
204     for the value of this variable object.  */
205  int (*value_is_changeable_p) (const struct varobj *var);
206
207  /* Return nonzero if the type of VAR has mutated.
208
209     VAR's value is still the varobj's previous value, while NEW_VALUE
210     is VAR's new value and NEW_TYPE is the var's new type.  NEW_VALUE
211     may be NULL indicating that there is no value available (the varobj
212     may be out of scope, of may be the child of a null pointer, for
213     instance).  NEW_TYPE, on the other hand, must never be NULL.
214
215     This function should also be able to assume that var's number of
216     children is set (not < 0).
217
218     Languages where types do not mutate can set this to NULL.  */
219  int (*value_has_mutated) (const struct varobj *var, struct value *new_value,
220			    struct type *new_type);
221
222  /* Return nonzero if VAR is a suitable path expression parent.
223
224     For C like languages with anonymous structures and unions an anonymous
225     structure or union is not a suitable parent.  */
226  int (*is_path_expr_parent) (const struct varobj *var);
227};
228
229extern const struct lang_varobj_ops c_varobj_ops;
230extern const struct lang_varobj_ops cplus_varobj_ops;
231extern const struct lang_varobj_ops java_varobj_ops;
232extern const struct lang_varobj_ops ada_varobj_ops;
233
234#define default_varobj_ops c_varobj_ops
235/* API functions */
236
237extern struct varobj *varobj_create (char *objname,
238				     char *expression, CORE_ADDR frame,
239				     enum varobj_type type);
240
241extern char *varobj_gen_name (void);
242
243extern struct varobj *varobj_get_handle (char *name);
244
245extern char *varobj_get_objname (const struct varobj *var);
246
247extern char *varobj_get_expression (const struct varobj *var);
248
249/* Delete a varobj and all its children if only_children == 0, otherwise delete
250   only the children.  Return the number of deleted variables.  */
251
252extern int varobj_delete (struct varobj *var, int only_children);
253
254extern enum varobj_display_formats varobj_set_display_format (
255							 struct varobj *var,
256					enum varobj_display_formats format);
257
258extern enum varobj_display_formats varobj_get_display_format (
259						const struct varobj *var);
260
261extern int varobj_get_thread_id (const struct varobj *var);
262
263extern void varobj_set_frozen (struct varobj *var, int frozen);
264
265extern int varobj_get_frozen (const struct varobj *var);
266
267extern void varobj_get_child_range (const struct varobj *var, int *from,
268				    int *to);
269
270extern void varobj_set_child_range (struct varobj *var, int from, int to);
271
272extern char *varobj_get_display_hint (const struct varobj *var);
273
274extern int varobj_get_num_children (struct varobj *var);
275
276/* Return the list of children of VAR.  The returned vector should not
277   be modified in any way.  FROM and TO are in/out parameters
278   indicating the range of children to return.  If either *FROM or *TO
279   is less than zero on entry, then all children will be returned.  On
280   return, *FROM and *TO will be updated to indicate the real range
281   that was returned.  The resulting VEC will contain at least the
282   children from *FROM to just before *TO; it might contain more
283   children, depending on whether any more were available.  */
284extern VEC (varobj_p)* varobj_list_children (struct varobj *var,
285					     int *from, int *to);
286
287extern char *varobj_get_type (struct varobj *var);
288
289extern struct type *varobj_get_gdb_type (const struct varobj *var);
290
291extern char *varobj_get_path_expr (const struct varobj *var);
292
293extern const struct language_defn *
294  varobj_get_language (const struct varobj *var);
295
296extern int varobj_get_attributes (const struct varobj *var);
297
298extern char *varobj_get_formatted_value (struct varobj *var,
299					 enum varobj_display_formats format);
300
301extern char *varobj_get_value (struct varobj *var);
302
303extern int varobj_set_value (struct varobj *var, char *expression);
304
305extern void all_root_varobjs (void (*func) (struct varobj *var, void *data),
306			      void *data);
307
308extern VEC(varobj_update_result) *varobj_update (struct varobj **varp,
309						 int is_explicit);
310
311extern void varobj_invalidate (void);
312
313extern int varobj_editable_p (const struct varobj *var);
314
315extern int varobj_floating_p (const struct varobj *var);
316
317extern void varobj_set_visualizer (struct varobj *var,
318				   const char *visualizer);
319
320extern void varobj_enable_pretty_printing (void);
321
322extern int varobj_has_more (const struct varobj *var, int to);
323
324extern int varobj_is_dynamic_p (const struct varobj *var);
325
326extern struct cleanup *varobj_ensure_python_env (const struct varobj *var);
327
328extern int varobj_default_value_is_changeable_p (const struct varobj *var);
329extern int varobj_value_is_changeable_p (const struct varobj *var);
330
331extern struct type *varobj_get_value_type (const struct varobj *var);
332
333extern int varobj_is_anonymous_child (const struct varobj *child);
334
335extern const struct varobj *
336  varobj_get_path_expr_parent (const struct varobj *var);
337
338extern char *varobj_value_get_print_value (struct value *value,
339					   enum varobj_display_formats format,
340					   const struct varobj *var);
341
342extern void varobj_formatted_print_options (struct value_print_options *opts,
343					    enum varobj_display_formats format);
344
345extern void varobj_restrict_range (VEC (varobj_p) *children, int *from,
346				   int *to);
347
348extern int varobj_default_is_path_expr_parent (const struct varobj *var);
349
350#endif /* VAROBJ_H */
351