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
`boolean`	`asBoolean()` Returns a `boolean` representation of this value if it is `boolean`.
`byte`	`asByte()` Returns a `byte` representation of this value if it is `number` and the value `fits`.
`LocalDate`	`asDate()` Returns this value as date if it is a `date`.
`double`	`asDouble()` Returns a `double` representation of this value if it is `number` and the value `fits`.
`Duration`	`asDuration()` Returns this value as duration if this object represents a `duration`.
`float`	`asFloat()` Returns a `float` representation of this value if it is `number` and the value `fits`.
`DebugValue`	`asInLanguage(LanguageInfo language)` Returns a debug value that presents itself as seen by the provided language.
`Instant`	`asInstant()` Returns this value as instant if it is an `instant`.
`int`	`asInt()` Returns an `int` representation of this value if it is `number` and the value `fits`.
`long`	`asLong()` Returns a `long` representation of this value if it is `number` and the value `fits`.
`short`	`asShort()` Returns a `short` representation of this value if it is `number` and the value `fits`.
`String`	`asString()` Returns the `String` value if this value represents a string.
`LocalTime`	`asTime()` Returns this value as time if it is a `time`.
`ZoneId`	`asTimeZone()` Returns this value as timestamp if it represents a `timezone`.
`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.
`boolean`	`fitsInByte()` Returns `true` if this value represents a `number` and the value fits in `byte`, else `false`.
`boolean`	`fitsInDouble()` Returns `true` if this value represents a `number` and the value fits in `double`, else `false`.
`boolean`	`fitsInFloat()` Returns `true` if this value represents a `number` and the value fits in `float`, else `false`.
`boolean`	`fitsInInt()` Returns `true` if this value represents a `number` and the value fits in `int`, else `false`.
`boolean`	`fitsInLong()` Returns `true` if this value represents a `number` and the value fits in `long`, else `false`.
`boolean`	`fitsInShort()` Returns `true` if this value represents a `number` and the value fits in `short`, else `false`.
`List<DebugValue>`	`getArray()` Provides array elements when this value represents an array.
`DebugValue`	`getMetaObject()` Get a meta-object of this value, if any.
`String`	`getMetaQualifiedName()` Returns the qualified name of a metaobject as `String`.
`String`	`getMetaSimpleName()` Returns the simple name of a metaobject as `string`.
`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.
`Object`	`getRawValue(Class<? extends TruffleLanguage<?>> languageClass)` Returns the underlying guest value object held by this `DebugValue`.
`List<Breakpoint>`	`getRootInstanceBreakpoints()` Get a list of breakpoints installed to the value's session and whose `root instance` is this value.
`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.
`boolean`	`isBoolean()` Returns `true` if and only if this value represents a boolean value.
`boolean`	`isDate()` Returns `true` if this value represents a date, else `false`.
`boolean`	`isDuration()` Returns `true` if this object represents a duration, else `false`.
`boolean`	`isInstant()` Returns `true` if this value represents an instant.
`abstract boolean`	`isInternal()` Returns `true` if this value represents an internal variable or property, `false` otherwise.
`boolean`	`isMetaInstance(DebugValue instance)` Returns `true` if the given instance is an instance of this value, else `false`.
`boolean`	`isMetaObject()` Returns `true` if the value represents a metaobject.
`boolean`	`isNull()` Test if the value represents 'null'.
`boolean`	`isNumber()` Returns `true` if and only if this value represents a number.
`abstract boolean`	`isReadable()` Returns `true` if this value can be read else `false`.
`boolean`	`isString()` Returns `true` if and only if this value represents a string.
`boolean`	`isTime()` Returns `true` if this value represents a time, else `false`.
`boolean`	`isTimeZone()` Returns `true` if this object represents a timezone, 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`	`toDisplayString()` Converts the value to a language-specific string representation.
`String`	`toDisplayString(boolean allowSideEffects)` Converts the value to a language-specific string representation.
`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
  - 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
  - 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
  - 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'.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    19.0
  - isString
```
public boolean isString()
```
    Returns true if and only if this value represents a string.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
  - asString
```
public final 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
  - fitsInInt
```
public boolean fitsInInt()
```
    Returns true if this value represents a number and the value fits in int, else false.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asInt()
  - asInt
```
public int asInt()
```
    Returns an int representation of this value if it is number and the value fits.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.fitsInInt()
  - isBoolean
```
public boolean isBoolean()
```
    Returns true if and only if this value represents a boolean value.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asBoolean()
  - asBoolean
```
public boolean asBoolean()
```
    Returns a boolean representation of this value if it is boolean.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isBoolean()
  - isNumber
```
public boolean isNumber()
```
    Returns true if and only if this value represents a number. The number value may be accessed as byte, short, int, long, float or double value.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
  - fitsInLong
```
public boolean fitsInLong()
```
    Returns true if this value represents a number and the value fits in long, else false.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asLong()
  - asLong
```
public long asLong()
```
    Returns a long representation of this value if it is number and the value fits.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.fitsInLong()
  - fitsInDouble
```
public boolean fitsInDouble()
```
    Returns true if this value represents a number and the value fits in double, else false.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asDouble()
  - asDouble
```
public double asDouble()
```
    Returns a double representation of this value if it is number and the value fits.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.fitsInDouble()
  - fitsInFloat
```
public boolean fitsInFloat()
```
    Returns true if this value represents a number and the value fits in float, else false.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asFloat()
  - asFloat
```
public float asFloat()
```
    Returns a float representation of this value if it is number and the value fits.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.fitsInFloat()
  - fitsInByte
```
public boolean fitsInByte()
```
    Returns true if this value represents a number and the value fits in byte, else false.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asByte()
  - asByte
```
public byte asByte()
```
    Returns a byte representation of this value if it is number and the value fits.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.fitsInByte()
  - fitsInShort
```
public boolean fitsInShort()
```
    Returns true if this value represents a number and the value fits in short, else false.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asShort()
  - asShort
```
public short asShort()
```
    Returns a short representation of this value if it is number and the value fits.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.fitsInShort()
  - isDate
```
public boolean isDate()
```
    Returns true if this value represents a date, else false. If this value is also a timezone then the date is aware, otherwise it is naive.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asDate()
  - asDate
```
public LocalDate asDate()
```
    Returns this value as date if it is a date. The returned date is either aware if the value has a timezone otherwise it is naive.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isDate()
  - isTime
```
public boolean isTime()
```
    Returns true if this value represents a time, else false. If the value is also a timezone then the time is aware, otherwise it is naive.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asTime()
  - asTime
```
public LocalTime asTime()
```
    Returns this value as time if it is a time. The returned time is either aware if the value has a timezone otherwise it is naive.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isTime()
  - isInstant
```
public boolean isInstant()
```
    Returns true if this value represents an instant. See InteropLibrary.isInstant(Object) for detailed description.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isDate(), DebugValue.isTime(), DebugValue.isInstant(), DebugValue.asInstant()
  - asInstant
```
public Instant asInstant()
```
    Returns this value as instant if it is an instant. See InteropLibrary.asInstant(Object) for detailed description.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isDate(), DebugValue.isTime(), DebugValue.isTimeZone()
  - isTimeZone
```
public boolean isTimeZone()
```
    Returns true if this object represents a timezone, else false. See InteropLibrary.isTimeZone(Object) for detailed description.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.asTimeZone(), DebugValue.asInstant()
  - asTimeZone
```
public ZoneId asTimeZone()
```
    Returns this value as timestamp if it represents a timezone.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isTimeZone()
  - isDuration
```
public boolean isDuration()
```
    Returns true if this object represents a duration, else false.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    Duration, DebugValue.asDuration()
  - asDuration
```
public Duration asDuration()
```
    Returns this value as duration if this object represents a duration.
    
    Throws:
    
    UnsupportedOperationException - if this value could not be converted.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isDuration()
  - isMetaObject
```
public boolean isMetaObject()
```
    Returns true if the value represents a metaobject. See InteropLibrary.isMetaObject(Object) for detailed description.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1
    
    See Also:
    
    DebugValue.getMetaQualifiedName(), DebugValue.getMetaSimpleName(), DebugValue.isMetaInstance(DebugValue), DebugValue.getMetaObject()
  - getMetaQualifiedName
```
public String getMetaQualifiedName()
```
    Returns the qualified name of a metaobject as String. See InteropLibrary.getMetaQualifiedName(Object) for detailed description.
    
    Throws:
    
    UnsupportedOperationException - if and only if DebugValue.isMetaObject() returns false for the same value.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isMetaObject()
  - getMetaSimpleName
```
public String getMetaSimpleName()
```
    Returns the simple name of a metaobject as string. See InteropLibrary.getMetaSimpleName(Object) for detailed description.
    
    Throws:
    
    UnsupportedOperationException - if and only if DebugValue.isMetaObject() returns false for the same value.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isMetaObject()
  - isMetaInstance
```
public boolean isMetaInstance(DebugValue instance)
```
    Returns true if the given instance is an instance of this value, else false. See InteropLibrary.isMetaInstance(Object, Object) for detailed description.
    
    Parameters:
    
    instance - the instance value to check.
    
    Throws:
    
    UnsupportedOperationException - if and only if DebugValue.isMetaObject() returns false for the same value.
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    20.1.0
    
    See Also:
    
    DebugValue.isMetaObject()
  - getRootInstanceBreakpoints
```
public final List<Breakpoint> getRootInstanceBreakpoints()
```
    Get a list of breakpoints installed to the value's session and whose root instance is this value.
    
    Returns:
    
    a list of breakpoints with this value as root instance
    
    Since:
    
    19.3.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 null is returned.
    
    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
    
    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
    
    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
  - getRawValue
```
public Object getRawValue(Class<? extends TruffleLanguage<?>> languageClass)
```
    Returns the underlying guest value object held by this DebugValue. This method is permitted only if the guest language class is available. This is the case if you want to utilize the Debugger API directly from within a guest language, or if you are an instrument bound/dependent on a specific language. This method is opposite to DebugScope.convertRawValue(Class, Object) where a raw guest language value is wrapped in a DebugValue.
    
    Parameters:
    
    languageClass - the Truffle language class for a given guest language
    
    Returns:
    
    the guest language object or null if the language differs from the language that created the underlying DebugValue
    
    Since:
    
    20.1
  - toDisplayString
```
public final String toDisplayString()
```
    Converts the value to a language-specific string representation. Is the same as toDisplayString(true).
    
    Since:
    
    20.1
    
    See Also:
    
    DebugValue.toDisplayString(boolean)
  - toDisplayString
```
public final String toDisplayString(boolean allowSideEffects)
                             throws DebugException
```
    Converts the value to a language-specific string representation.
    
    Parameters:
    
    allowSideEffects - whether side-effects are allowed in the production of the string.
    
    Throws:
    
    DebugException
    
    Since:
    
    20.1
  - 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. See InteropLibrary.getMetaObject(Object) for detailed description.
    
    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.toDisplayString(), DebugValue.getMetaObject(), DebugValue.getSourceLocation() and other methods that provide various representations of the value. 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

getName

isReadable

hasReadSideEffects

hasWriteSideEffects

isWritable

isInternal

getScope

isNull

isString

asString

fitsInInt

asInt

isBoolean

asBoolean

isNumber

fitsInLong

asLong

fitsInDouble

asDouble

fitsInFloat

asFloat

fitsInByte

asByte

fitsInShort

asShort

isDate

asDate

isTime

asTime

isInstant

asInstant

isTimeZone

asTimeZone

isDuration

asDuration

isMetaObject

getMetaQualifiedName

getMetaSimpleName

isMetaInstance

getRootInstanceBreakpoints

getProperties

getProperty

isArray

getArray

getRawValue

toDisplayString

toDisplayString

getMetaObject

getSourceLocation

canExecute

execute

getOriginalLanguage

asInLanguage

toString