SBValue.i revision d41abdc25bee7dd73b482d65c391255f55c1df0d 
1//===-- SWIG Interface for SBValue ------------------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10namespace lldb {
11
12%feature("docstring",
13"Represents the value of a variable, a register, or an expression.
14
15SBValue supports iteration through its child, which in turn is represented
16as an SBValue.  For example, we can get the general purpose registers of a
17frame as an SBValue, and iterate through all the registers,
18
19    registerSet = frame.GetRegisters() # Returns an SBValueList.
20    for regs in registerSet:
21        if 'general purpose registers' in regs.getName().lower():
22            GPRs = regs
23            break
24
25    print '%s (number of children = %d):' % (GPRs.GetName(), GPRs.GetNumChildren())
26    for reg in GPRs:
27        print 'Name: ', reg.GetName(), ' Value: ', reg.GetValue()
28
29produces the output:
30
31General Purpose Registers (number of children = 21):
32Name:  rax  Value:  0x0000000100000c5c
33Name:  rbx  Value:  0x0000000000000000
34Name:  rcx  Value:  0x00007fff5fbffec0
35Name:  rdx  Value:  0x00007fff5fbffeb8
36Name:  rdi  Value:  0x0000000000000001
37Name:  rsi  Value:  0x00007fff5fbffea8
38Name:  rbp  Value:  0x00007fff5fbffe80
39Name:  rsp  Value:  0x00007fff5fbffe60
40Name:  r8  Value:  0x0000000008668682
41Name:  r9  Value:  0x0000000000000000
42Name:  r10  Value:  0x0000000000001200
43Name:  r11  Value:  0x0000000000000206
44Name:  r12  Value:  0x0000000000000000
45Name:  r13  Value:  0x0000000000000000
46Name:  r14  Value:  0x0000000000000000
47Name:  r15  Value:  0x0000000000000000
48Name:  rip  Value:  0x0000000100000dae
49Name:  rflags  Value:  0x0000000000000206
50Name:  cs  Value:  0x0000000000000027
51Name:  fs  Value:  0x0000000000000010
52Name:  gs  Value:  0x0000000000000048
53
54See also linked_list_iter() for another perspective on how to iterate through an
55SBValue instance which interprets the value object as representing the head of a
56linked list."
57) SBValue;
58class SBValue
59{
60public:
61    SBValue ();
62
63    SBValue (const SBValue &rhs);
64
65    ~SBValue ();
66
67    bool
68    IsValid();
69
70    void
71    Clear();
72
73    SBError
74    GetError();
75
76    lldb::user_id_t
77    GetID ();
78
79    const char *
80    GetName();
81
82    const char *
83    GetTypeName ();
84
85    size_t
86    GetByteSize ();
87
88    bool
89    IsInScope ();
90
91    lldb::Format
92    GetFormat ();
93
94    void
95    SetFormat (lldb::Format format);
96
97    const char *
98    GetValue ();
99
100    int64_t
101    GetValueAsSigned(SBError& error, int64_t fail_value=0);
102
103    uint64_t
104    GetValueAsUnsigned(SBError& error, uint64_t fail_value=0);
105
106    int64_t
107    GetValueAsSigned(int64_t fail_value=0);
108
109    uint64_t
110    GetValueAsUnsigned(uint64_t fail_value=0);
111
112    ValueType
113    GetValueType ();
114
115    bool
116    GetValueDidChange ();
117
118    const char *
119    GetSummary ();
120
121    const char *
122    GetObjectDescription ();
123
124    lldb::SBValue
125    GetDynamicValue (lldb::DynamicValueType use_dynamic);
126
127    lldb::SBValue
128    GetStaticValue ();
129
130    lldb::SBValue
131    GetNonSyntheticValue ();
132
133    bool
134    IsDynamic();
135
136    const char *
137    GetLocation ();
138
139    bool
140    SetValueFromCString (const char *value_str);
141
142    lldb::SBTypeFormat
143    GetTypeFormat ();
144
145    lldb::SBTypeSummary
146    GetTypeSummary ();
147
148    lldb::SBTypeFilter
149    GetTypeFilter ();
150
151    lldb::SBTypeSynthetic
152    GetTypeSynthetic ();
153
154    lldb::SBValue
155    GetChildAtIndex (uint32_t idx);
156
157    %feature("docstring", "
158    //------------------------------------------------------------------
159    /// Get a child value by index from a value.
160    ///
161    /// Structs, unions, classes, arrays and and pointers have child
162    /// values that can be access by index.
163    ///
164    /// Structs and unions access child members using a zero based index
165    /// for each child member. For
166    ///
167    /// Classes reserve the first indexes for base classes that have
168    /// members (empty base classes are omitted), and all members of the
169    /// current class will then follow the base classes.
170    ///
171    /// Pointers differ depending on what they point to. If the pointer
172    /// points to a simple type, the child at index zero
173    /// is the only child value available, unless \a synthetic_allowed
174    /// is \b true, in which case the pointer will be used as an array
175    /// and can create 'synthetic' child values using positive or
176    /// negative indexes. If the pointer points to an aggregate type
177    /// (an array, class, union, struct), then the pointee is
178    /// transparently skipped and any children are going to be the indexes
179    /// of the child values within the aggregate type. For example if
180    /// we have a 'Point' type and we have a SBValue that contains a
181    /// pointer to a 'Point' type, then the child at index zero will be
182    /// the 'x' member, and the child at index 1 will be the 'y' member
183    /// (the child at index zero won't be a 'Point' instance).
184    ///
185    /// Arrays have a preset number of children that can be accessed by
186    /// index and will returns invalid child values for indexes that are
187    /// out of bounds unless the \a synthetic_allowed is \b true. In this
188    /// case the array can create 'synthetic' child values for indexes
189    /// that aren't in the array bounds using positive or negative
190    /// indexes.
191    ///
192    /// @param[in] idx
193    ///     The index of the child value to get
194    ///
195    /// @param[in] use_dynamic
196    ///     An enumeration that specifies wether to get dynamic values,
197    ///     and also if the target can be run to figure out the dynamic
198    ///     type of the child value.
199    ///
200    /// @param[in] synthetic_allowed
201    ///     If \b true, then allow child values to be created by index
202    ///     for pointers and arrays for indexes that normally wouldn't
203    ///     be allowed.
204    ///
205    /// @return
206    ///     A new SBValue object that represents the child member value.
207    //------------------------------------------------------------------
208    ") GetChildAtIndex;
209    lldb::SBValue
210    GetChildAtIndex (uint32_t idx,
211                     lldb::DynamicValueType use_dynamic,
212                     bool can_create_synthetic);
213
214    lldb::SBValue
215    CreateChildAtOffset (const char *name, uint32_t offset, lldb::SBType type);
216
217    lldb::SBValue
218    SBValue::Cast (lldb::SBType type);
219
220    lldb::SBValue
221    CreateValueFromExpression (const char *name, const char* expression);
222
223    lldb::SBValue
224    CreateValueFromAddress(const char* name, lldb::addr_t address, lldb::SBType type);
225
226	lldb::SBValue
227	CreateValueFromData (const char* name,
228	                     lldb::SBData data,
229	                     lldb::SBType type);
230
231    lldb::SBType
232    GetType();
233
234    %feature("docstring", "
235    //------------------------------------------------------------------
236    /// Returns the child member index.
237    ///
238    /// Matches children of this object only and will match base classes and
239    /// member names if this is a clang typed object.
240    ///
241    /// @param[in] name
242    ///     The name of the child value to get
243    ///
244    /// @return
245    ///     An index to the child member value.
246    //------------------------------------------------------------------
247    ") GetIndexOfChildWithName;
248    uint32_t
249    GetIndexOfChildWithName (const char *name);
250
251    lldb::SBValue
252    GetChildMemberWithName (const char *name);
253
254    %feature("docstring", "
255    //------------------------------------------------------------------
256    /// Returns the child member value.
257    ///
258    /// Matches child members of this object and child members of any base
259    /// classes.
260    ///
261    /// @param[in] name
262    ///     The name of the child value to get
263    ///
264    /// @param[in] use_dynamic
265    ///     An enumeration that specifies wether to get dynamic values,
266    ///     and also if the target can be run to figure out the dynamic
267    ///     type of the child value.
268    ///
269    /// @return
270    ///     A new SBValue object that represents the child member value.
271    //------------------------------------------------------------------
272    ") GetChildMemberWithName;
273    lldb::SBValue
274    GetChildMemberWithName (const char *name, lldb::DynamicValueType use_dynamic);
275
276    %feature("docstring", "Expands nested expressions like .a->b[0].c[1]->d."
277    ) GetValueForExpressionPath;
278    lldb::SBValue
279    GetValueForExpressionPath(const char* expr_path);
280
281    uint32_t
282    GetNumChildren ();
283
284    void *
285    GetOpaqueType();
286
287    lldb::SBValue
288    Dereference ();
289
290    lldb::SBValue
291    AddressOf();
292
293    bool
294    TypeIsPointerType ();
295
296    lldb::SBTarget
297    GetTarget();
298
299    lldb::SBProcess
300    GetProcess();
301
302    lldb::SBThread
303    GetThread();
304
305    lldb::SBFrame
306    GetFrame();
307
308    %feature("docstring", "
309    /// Find and watch a variable.
310    /// It returns an SBWatchpoint, which may be invalid.
311    ") Watch;
312    lldb::SBWatchpoint
313    Watch (bool resolve_location, bool read, bool write);
314
315    %feature("docstring", "
316    /// Find and watch the location pointed to by a variable.
317    /// It returns an SBWatchpoint, which may be invalid.
318    ") WatchPointee;
319    lldb::SBWatchpoint
320    WatchPointee (bool resolve_location, bool read, bool write);
321
322    bool
323    GetDescription (lldb::SBStream &description);
324
325    bool
326    GetExpressionPath (lldb::SBStream &description);
327
328	%feature("docstring", "
329	//------------------------------------------------------------------
330    /// Get an SBData wrapping what this SBValue points to.
331    ///
332    /// This method will dereference the current SBValue, if its
333    /// data type is a T* or T[], and extract item_count elements
334    /// of type T from it, copying their contents in an SBData.
335    ///
336    /// @param[in] item_idx
337    ///     The index of the first item to retrieve. For an array
338    ///     this is equivalent to array[item_idx], for a pointer
339    ///     to *(pointer + item_idx). In either case, the measurement
340    ///     unit for item_idx is the sizeof(T) rather than the byte
341    ///
342    /// @param[in] item_count
343    ///     How many items should be copied into the output. By default
344    ///     only one item is copied, but more can be asked for.
345    ///
346    /// @return
347    ///     An SBData with the contents of the copied items, on success.
348    ///     An empty SBData otherwise.
349    //------------------------------------------------------------------
350	") GetPointeeData;
351	lldb::SBData
352	GetPointeeData (uint32_t item_idx = 0,
353					uint32_t item_count = 1);
354
355    %feature("docstring", "
356	//------------------------------------------------------------------
357    /// Get an SBData wrapping the contents of this SBValue.
358    ///
359    /// This method will read the contents of this object in memory
360    /// and copy them into an SBData for future use.
361    ///
362    /// @return
363    ///     An SBData with the contents of this SBValue, on success.
364    ///     An empty SBData otherwise.
365    //------------------------------------------------------------------
366	") GetData;
367    lldb::SBData
368    GetData ();
369
370	lldb::addr_t
371	GetLoadAddress();
372
373	lldb::SBAddress
374	GetAddress();
375
376    %feature("docstring", "Returns an expression path for this value."
377    ) GetExpressionPath;
378    bool
379    GetExpressionPath (lldb::SBStream &description, bool qualify_cxx_base_classes);
380
381    %pythoncode %{
382        def __get_dynamic__ (self):
383            '''Helper function for the "SBValue.dynamic" property.'''
384            return self.GetDynamicValue (eDynamicCanRunTarget)
385
386        __swig_getmethods__["name"] = GetName
387        if _newclass: name = property(GetName, None, doc='Returns the name of this SBValue as a string')
388
389        __swig_getmethods__["type"] = GetType
390        if _newclass: type = property(GetType, None, doc='Returns an SBType that represents the type of this SBValue')
391
392        __swig_getmethods__["size"] = GetByteSize
393        if _newclass: size = property(GetByteSize, None, doc='Returns the size (in bytes) of the data contained in this SBValue')
394
395        __swig_getmethods__["is_in_scope"] = IsInScope
396        if _newclass: is_in_scope = property(IsInScope, None, doc='Returns True if this SBValue represents an item that is currently in lexical scope')
397
398        __swig_getmethods__["format"] = GetFormat
399        __swig_setmethods__["format"] = SetFormat
400        if _newclass: format = property(GetName, SetFormat, doc='Returns the format for this SBValue')
401
402        __swig_getmethods__["value"] = GetValue
403        __swig_setmethods__["value"] = SetValueFromCString
404        if _newclass: value = property(GetValue, SetValueFromCString, doc='Returns the value of this SBValue as a string')
405
406        __swig_getmethods__["value_type"] = GetValueType
407        if _newclass: value_type = property(GetValueType, None, doc='Returns the type of entry stored in this SBValue')
408
409        __swig_getmethods__["changed"] = GetValueDidChange
410        if _newclass: changed = property(GetValueDidChange, None, doc='Returns True if this SBValue represents an item that has changed')
411
412        __swig_getmethods__["data"] = GetData
413        if _newclass: data = property(GetData, None, doc='Returns an SBData wrapping the contents of this SBValue')
414
415        __swig_getmethods__["load_addr"] = GetLoadAddress
416        if _newclass: load_addr = property(GetLoadAddress, None, doc='Returns the load address (target address) of this SBValue as a number')
417
418        __swig_getmethods__["addr"] = GetAddress
419        if _newclass: addr = property(GetAddress, None, doc='Returns the address of this SBValue as an SBAddress')
420
421        __swig_getmethods__["deref"] = Dereference
422        if _newclass: deref = property(Dereference, None, doc='Returns an SBValue that is created by dereferencing this SBValue')
423
424        __swig_getmethods__["address_of"] = AddressOf
425        if _newclass: address_of = property(AddressOf, None, doc='Returns an SBValue that wraps the address-of this SBValue')
426
427        __swig_getmethods__["error"] = GetError
428        if _newclass: error = property(GetError, None, doc='Returns the SBError currently associated to this SBValue')
429
430        __swig_getmethods__["summary"] = GetSummary
431        if _newclass: summary = property(GetSummary, None, doc='Returns the summary for this SBValue as a string')
432
433        __swig_getmethods__["description"] = GetObjectDescription
434        if _newclass: description = property(GetObjectDescription, None, doc='Returns the language-specific description of this SBValue as a string')
435
436        __swig_getmethods__["dynamic"] = __get_dynamic__
437        if _newclass: description = property(__get_dynamic__, None, doc='Gets the dynamic type for a value')
438
439        __swig_getmethods__["location"] = GetLocation
440        if _newclass: location = property(GetLocation, None, doc='Returns the location of this SBValue as a string')
441
442        __swig_getmethods__["target"] = GetTarget
443        if _newclass: target = property(GetTarget, None, doc='Returns an SBTarget for the target from which this SBValue comes')
444
445        __swig_getmethods__["process"] = GetProcess
446        if _newclass: process = property(GetProcess, None, doc='Returns an SBProcess for the process from which this SBValue comes')
447
448        __swig_getmethods__["thread"] = GetThread
449        if _newclass: thread = property(GetThread, None, doc='Returns an SBThread for the thread from which this SBValue comes')
450
451        __swig_getmethods__["frame"] = GetFrame
452        if _newclass: frame = property(GetFrame, None, doc='Returns an SBFrame for the stack frame from which this SBValue comes')
453
454        __swig_getmethods__["num_children"] = GetNumChildren
455        if _newclass: num_children = property(GetNumChildren, None, doc='Returns the number of child SBValues that this SBValue has')
456
457        __swig_getmethods__["unsigned"] = GetValueAsUnsigned
458        if _newclass: unsigned = property(GetValueAsUnsigned, None, doc='Returns the value of this SBValue as an unsigned number')
459
460        __swig_getmethods__["signed"] = GetValueAsSigned
461        if _newclass: signed = property(GetValueAsSigned, None, doc='Returns the value of this SBValue as a signed number')
462
463        def get_expr_path(self):
464            s = SBStream()
465            self.GetExpressionPath (s)
466            return s.GetData()
467
468        __swig_getmethods__["path"] = get_expr_path
469        if _newclass: path = property(get_expr_path, None, doc='Returns the expression path that one can use to reach this SBValue')
470    %}
471
472};
473
474} // namespace lldb
475