DebugValue

java.lang.Object
- com.oracle.truffle.api.debug.DebugValue

```
public abstract class DebugValue
extends Object
```
Represents a value accessed using the debugger API. Please note that values can become invalid depending on the context in which they are used. For example stack values will only remain valid as long as the current stack element is active. Heap values on the other hand remain valid. If a value becomes invalid then setting or getting a value will throw an IllegalStateException . DebugValue instances neither support equality or preserve identity.
Clients may access the debug value only on the execution thread where the suspended event of the stack frame was created and notification received; access from other threads will throw IllegalStateException.

Since:

0.17

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract <T> T`	`as(Class<T> clazz)` Converts the debug value into a Java type.
`DebugValue`	`asInLanguage(LanguageInfo language)` Returns a debug value that presents itself as seen by the provided language.
`abstract String`	`asString()` Returns the `String` value if this value represents a string.
`boolean`	`canExecute()` Returns `true` if this value can be executed (represents a guest language function), else `false`.
`DebugValue`	`execute(DebugValue... arguments)` Executes the executable represented by this value.
`List<DebugValue>`	`getArray()` Provides array elements when this value represents an array.
`DebugValue`	`getMetaObject()` Get a meta-object of this value, if any.
`abstract String`	`getName()` Returns the name of this value as it is referred to from its origin.
`LanguageInfo`	`getOriginalLanguage()` Get the original language that created the value, if any.
`Collection<DebugValue>`	`getProperties()` Provides properties representing an internal structure of this value.
`DebugValue`	`getProperty(String name)` Get a property value by its name.
`DebugScope`	`getScope()` Get the scope where this value is declared in.
`SourceSection`	`getSourceLocation()` Get a source location where this value is declared, if any.
`abstract boolean`	`hasReadSideEffects()` Returns `true` if reading of this value can have side-effects, else `false`.
`abstract boolean`	`hasWriteSideEffects()` Returns `true` if setting a new value can have side-effects, else `false`.
`boolean`	`isArray()` Returns `true` if this value represents an array, `false` otherwise.
`abstract boolean`	`isInternal()` Returns `true` if this value represents an internal variable or property, `false` otherwise.
`boolean`	`isNull()` Test if the value represents 'null'.
`abstract boolean`	`isReadable()` Returns `true` if this value can be read else `false`.
`abstract boolean`	`isWritable()` Returns `true` if this value can be written to, else `false`.
`abstract void`	`set(DebugValue value)` Sets the value using another `DebugValue`.
`abstract void`	`set(Object primitiveValue)` Sets a primitive value.
`String`	`toString()` Returns a string representation of the debug value.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - set
```
public abstract void set(DebugValue value)
                  throws DebugException
```
    Sets the value using another DebugValue. Throws an IllegalStateException if the value is not writable, the passed value is not readable, this value or the passed value is invalid, or the guest language of the values do not match. Use DebugStackFrame.eval(String) to evaluate values to be set.
    
    Parameters:
    
    value - the value to set
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    0.17
  - set
```
public abstract void set(Object primitiveValue)
                  throws DebugException
```
    Sets a primitive value. Strings and boxed Java primitive types are considered primitive. Throws an IllegalStateException if the value is not writable and IllegalArgumentException if the value is not primitive.
    
    Parameters:
    
    primitiveValue - a primitive value to set
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    19.0
  - as
```
public abstract <T> T as(Class<T> clazz)
                  throws DebugException
```
    Converts the debug value into a Java type. Class conversions which are always supported:
    - String.class converts the value to its language specific string representation.
    - Number.class converts the value to a Number representation, if any.
    - Boolean.class converts the value to a Boolean representation, if any.
    No optional conversions are currently available. If a conversion is not supported then an UnsupportedOperationException is thrown. If the value is not readable then an IllegalStateException is thrown.
    Parameters:
    
    clazz - the type to convert to
    
    Returns:
    
    the converted Java type, or null when the conversion was not possible.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    0.17
  - asString
```
public abstract String asString()
                         throws DebugException
```
    Returns the String value if this value represents a string. This method returns null otherwise.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    19.0
  - getName
```
public abstract String getName()
```
    Returns the name of this value as it is referred to from its origin. If this value is originated from the stack it returns the name of the local variable. If the value was returned from another objects then it returns the name of the property or field it is contained in. If no name is available null is returned.
    
    Since:
    
    0.17
  - isReadable
```
public abstract boolean isReadable()
```
    Returns true if this value can be read else false.
    
    Since:
    
    0.17
    
    See Also:
    
    DebugValue.as(Class)
  - hasReadSideEffects
```
public abstract boolean hasReadSideEffects()
```
    Returns true if reading of this value can have side-effects, else false. Read has side-effects if it changes runtime state.
    
    Since:
    
    19.0
  - hasWriteSideEffects
```
public abstract boolean hasWriteSideEffects()
```
    Returns true if setting a new value can have side-effects, else false. Write has side-effects if it changes runtime state besides this value.
    
    Since:
    
    19.0
  - isWritable
```
public abstract boolean isWritable()
```
    Returns true if this value can be written to, else false.
    
    Since:
    
    0.26
    
    See Also:
    
    DebugValue.as(Class)
  - isInternal
```
public abstract boolean isInternal()
```
    Returns true if this value represents an internal variable or property, false otherwise.
    Languages might have extra object properties or extra scope variables that are a part of the runtime, but do not correspond to anything what is an explicit part of the guest language representation. They may represent additional language artifacts, providing more in-depth information that can be valuable during debugging. Language implementors mark these variables as internal. An example of such internal values are internal slots in ECMAScript.
    
    Since:
    
    0.26
  - getScope
```
public DebugScope getScope()
```
    Get the scope where this value is declared in. It returns a non-null value for local variables declared on a stack. It's null for object properties and other heap values.
    Returns: the scope, or null when this value does not belong into any scope. Since: 0.26
  isNull public final boolean isNull() Test if the value represents 'null'. Since: 19.0
  - getProperties public final Collection<DebugValue> getProperties() throws DebugException Provides properties representing an internal structure of this value. The returned collection is not thread-safe. If the value is not readable then an IllegalStateException is thrown.
    Returns:
    a collection of property values, or null when the value does not have any concept of properties.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    IllegalStateException - if the value is not readable
    
    Since:
    
    0.19
  - getProperty
```
public final DebugValue getProperty(String name)
                             throws DebugException
```
    Get a property value by its name.
    
    Parameters:
    
    name - name of a property
    
    Returns:
    
    the property value, or null if the property does not exist.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    IllegalStateException - if the value is not readable
    
    Since:
    
    19.0
  - isArray
```
public final boolean isArray()
                      throws DebugException
```
    Returns true if this value represents an array, false otherwise.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    0.19
  - getArray
```
public final List<DebugValue> getArray()
                                throws DebugException
```
    Provides array elements when this value represents an array. To test if this value represents an array, check DebugValue.isArray().
    
    Returns:
    
    a list of array elements, or null when the value does not represent an array.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    0.19
  - getMetaObject
```
public final DebugValue getMetaObject()
                               throws DebugException
```
    Get a meta-object of this value, if any. The meta-object represents a description of the value, reveals it's kind and it's features.
    
    Returns:
    
    a value representing the meta-object, or null
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    0.22
  - getSourceLocation
```
public final SourceSection getSourceLocation()
                                      throws DebugException
```
    Get a source location where this value is declared, if any.
    
    Returns:
    
    a source location of the object, or null
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    0.22
  - canExecute
```
public final boolean canExecute()
                         throws DebugException
```
    Returns true if this value can be executed (represents a guest language function), else false.
    
    Throws:
    
    DebugException
    
    Since:
    
    19.0
  - execute
```
public final DebugValue execute(DebugValue... arguments)
                         throws DebugException
```
    Executes the executable represented by this value.
    
    Parameters:
    
    arguments - Arguments passed to the executable
    
    Returns:
    
    the result of the execution
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    19.0
    
    See Also:
    
    DebugValue.canExecute()
  - getOriginalLanguage
```
public final LanguageInfo getOriginalLanguage()
                                       throws DebugException
```
    Get the original language that created the value, if any. This method will return null for values representing a primitive value, or objects that are not associated with any language.
    
    Returns:
    
    the language, or null when no language can be identified as the creator of the value.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    0.27
  - asInLanguage
```
public final DebugValue asInLanguage(LanguageInfo language)
```
    Returns a debug value that presents itself as seen by the provided language. The language affects the output of DebugValue.as(java.lang.Class), DebugValue.getMetaObject() and DebugValue.getSourceLocation(). Properties, array elements and other attributes are not affected by a language. The original language of the returned value remains the same as of this value.
    
    Parameters:
    
    language - a language to get the value representation of
    
    Returns:
    
    the value as represented in the language
    
    Since:
    
    0.27
  - toString
```
public String toString()
```
    Returns a string representation of the debug value.
    
    Overrides:
    
    toString in class Object
    
    Since:
    
    0.17

Class DebugValue

Method Summary

Methods inherited from class java.lang.Object

Method Detail

set

set

as

asString

getName

isReadable

hasReadSideEffects

hasWriteSideEffects

isWritable

isInternal

getScope

isNull

getProperties

getProperty

isArray

getArray

getMetaObject

getSourceLocation

canExecute

execute

getOriginalLanguage

asInLanguage

toString