public abstract class DebugValue extends Object
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
.
Modifier and Type | Method and Description |
---|---|
BigInteger |
asBigInteger()
|
boolean |
asBoolean()
Returns a
boolean representation of this value if it is boolean . |
byte |
asByte()
|
LocalDate |
asDate()
Returns this value as date if it is a
date . |
double |
asDouble()
|
Duration |
asDuration()
Returns this value as duration if this object represents a
duration . |
float |
asFloat()
|
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()
|
long |
asLong()
|
short |
asShort()
|
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 . |
boolean |
equals(Object obj)
Indicates whether another
DebugValue is equal to this. |
DebugValue |
execute(DebugValue... arguments)
Executes the executable represented by this value.
|
boolean |
fitsInBigInteger()
|
boolean |
fitsInByte()
|
boolean |
fitsInDouble()
|
boolean |
fitsInFloat()
|
boolean |
fitsInInt()
|
boolean |
fitsInLong()
|
boolean |
fitsInShort()
|
List<DebugValue> |
getArray()
Provides array elements when this value represents an array.
|
DebugValue |
getHashEntriesIterator()
Returns the entries iterator of the hash map.
|
DebugValue |
getHashKeysIterator()
Returns the keys iterator of the hash map.
|
long |
getHashSize()
Returns the number of hash map entries.
|
DebugValue |
getHashValue(DebugValue key)
Get value of a hash map for the specified key or
null if the mapping for the
specified key does not exist. |
DebugValue |
getHashValueOrDefault(DebugValue key,
DebugValue defaultValue)
Get value of a hash map for the specified key or return the
defaultValue when the
mapping for the specified key does not exist or is not readable. |
DebugValue |
getHashValuesIterator()
Returns the values iterator of the hash map.
|
DebugValue |
getIterator()
Returns the iterator value.
|
DebugValue |
getIteratorNextElement()
Returns the next element in the iteration.
|
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.
|
abstract DebuggerSession |
getSession()
Get the debugger session associated with this value.
|
SourceSection |
getSourceLocation()
Get a source location where this value is declared, if any.
|
boolean |
hasHashEntries()
Returns
true if the value may have hash map entries. |
int |
hashCode()
Provides hash code of the value.
|
boolean |
hasIterator()
Returns
true if the value provides an iterator. |
boolean |
hasIteratorNextElement()
|
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 |
isHashEntryExisting(DebugValue key)
Returns
true if mapping for a given key is existing. |
boolean |
isHashEntryInsertable(DebugValue key)
Returns
true if mapping for the specified key does not exist and is
writable . |
boolean |
isHashEntryModifiable(DebugValue key)
Returns
true if mapping for the specified key exists and is
writable . |
boolean |
isHashEntryReadable(DebugValue key)
Returns
true if mapping for the specified key exists and is readable. |
boolean |
isHashEntryRemovable(DebugValue key)
Returns
true if mapping for the specified key exists and is removable. |
boolean |
isHashEntryWritable(DebugValue key)
|
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 |
isIterator()
Returns
true if this value represents an iterator. |
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 . |
void |
putHashEntry(DebugValue key,
DebugValue value)
Associates the specified value with the specified key in the hash map.
|
boolean |
removeHashEntry(DebugValue key)
Removes the mapping for a given key from the hash map.
|
abstract void |
set(DebugValue value)
Sets the value using another
DebugValue . |
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.
|
public abstract void set(DebugValue value) throws DebugException
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.value
- the value to setDebugException
- when guest language code throws an exceptionpublic abstract String getName()
null
is returned.public abstract boolean isReadable()
true
if this value can be read else false
.public abstract boolean hasReadSideEffects()
true
if reading of this value can have side-effects, else
false
. Read has side-effects if it changes runtime state.public abstract boolean hasWriteSideEffects()
true
if setting a new value can have side-effects, else
false
. Write has side-effects if it changes runtime state besides this value.public abstract boolean isWritable()
true
if this value can be written to, else false
.public abstract boolean isInternal()
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.
public DebugScope getScope()
null
for object properties and other heap
values.null
when this value does not belong into any scope.public final boolean isNull()
DebugException
- when guest language code throws an exceptionpublic boolean isString()
true
if and only if this value represents a string.DebugException
- when guest language code throws an exceptionpublic final String asString() throws DebugException
String
value if this value represents a string. This method returns
null
otherwise.DebugException
- when guest language code throws an exceptionpublic boolean fitsInInt()
DebugException
- when guest language code throws an exceptionDebugValue.asInt()
public int asInt()
UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.fitsInInt()
public boolean isBoolean()
true
if and only if this value represents a boolean value.DebugException
- when guest language code throws an exceptionDebugValue.asBoolean()
public boolean asBoolean()
boolean
representation of this value if it is boolean
.UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.isBoolean()
public boolean isNumber()
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.DebugException
- when guest language code throws an exceptionpublic boolean fitsInLong()
DebugException
- when guest language code throws an exceptionDebugValue.asLong()
public long asLong()
UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.fitsInLong()
public boolean fitsInBigInteger()
DebugException
- when guest language code throws an exceptionDebugValue.asBigInteger()
public BigInteger asBigInteger()
UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.fitsInBigInteger()
public boolean fitsInDouble()
DebugException
- when guest language code throws an exceptionDebugValue.asDouble()
public double asDouble()
UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.fitsInDouble()
public boolean fitsInFloat()
DebugException
- when guest language code throws an exceptionDebugValue.asFloat()
public float asFloat()
UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.fitsInFloat()
public boolean fitsInByte()
DebugException
- when guest language code throws an exceptionDebugValue.asByte()
public byte asByte()
UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.fitsInByte()
public boolean fitsInShort()
DebugException
- when guest language code throws an exceptionDebugValue.asShort()
public short asShort()
UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.fitsInShort()
public boolean isDate()
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.DebugException
- when guest language code throws an exceptionDebugValue.asDate()
public LocalDate asDate()
date
. The returned date is either
aware if the value has a timezone
otherwise it is naive.UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.isDate()
public boolean isTime()
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.DebugException
- when guest language code throws an exceptionDebugValue.asTime()
public LocalTime asTime()
time
. The returned time is either
aware if the value has a timezone
otherwise it is naive.UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.isTime()
public boolean isInstant()
true
if this value represents an instant. See
InteropLibrary.isInstant(Object)
for detailed description.DebugException
- when guest language code throws an exceptionDebugValue.isDate()
,
DebugValue.isTime()
,
DebugValue.isInstant()
,
DebugValue.asInstant()
public Instant asInstant()
instant
. See
InteropLibrary.asInstant(Object)
for detailed description.UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.isDate()
,
DebugValue.isTime()
,
DebugValue.isTimeZone()
public boolean isTimeZone()
true
if this object represents a timezone, else false
. See
InteropLibrary.isTimeZone(Object)
for detailed description.UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.asTimeZone()
,
DebugValue.asInstant()
public ZoneId asTimeZone()
timezone
.UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.isTimeZone()
public boolean isDuration()
true
if this object represents a duration, else false
.UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDuration
,
DebugValue.asDuration()
public Duration asDuration()
duration
.UnsupportedOperationException
- if this value could not be converted.DebugException
- when guest language code throws an exceptionDebugValue.isDuration()
public boolean isMetaObject()
true
if the value represents a metaobject. See
InteropLibrary.isMetaObject(Object)
for detailed description.DebugException
- when guest language code throws an exceptionDebugValue.getMetaQualifiedName()
,
DebugValue.getMetaSimpleName()
,
DebugValue.isMetaInstance(DebugValue)
,
DebugValue.getMetaObject()
public String getMetaQualifiedName()
String
. See
InteropLibrary.getMetaQualifiedName(Object)
for detailed description.UnsupportedOperationException
- if and only if DebugValue.isMetaObject()
returns
false
for the same value.DebugException
- when guest language code throws an exceptionDebugValue.isMetaObject()
public String getMetaSimpleName()
string
. See
InteropLibrary.getMetaSimpleName(Object)
for detailed description.UnsupportedOperationException
- if and only if DebugValue.isMetaObject()
returns
false
for the same value.DebugException
- when guest language code throws an exceptionDebugValue.isMetaObject()
public boolean isMetaInstance(DebugValue instance)
true
if the given instance is an instance of this value, else
false
. See InteropLibrary.isMetaInstance(Object, Object)
for detailed
description.instance
- the instance value to check.UnsupportedOperationException
- if and only if DebugValue.isMetaObject()
returns
false
for the same value.DebugException
- when guest language code throws an exceptionDebugValue.isMetaObject()
public final List<Breakpoint> getRootInstanceBreakpoints()
root instance
is this value.public final Collection<DebugValue> getProperties() throws DebugException
readable
then null
is returned.DebugException
- when guest language code throws an exceptionpublic final DebugValue getProperty(String name) throws DebugException
name
- name of a propertynull
if the property does not exist.DebugException
- when guest language code throws an exceptionpublic final boolean isArray() throws DebugException
true
if this value represents an array, false
otherwise.DebugException
- when guest language code throws an exceptionpublic List<DebugValue> getArray() throws DebugException
DebugValue.isArray()
.null
when the value does not represent an
array.DebugException
- when guest language code throws an exceptionpublic Object getRawValue(Class<? extends TruffleLanguage<?>> languageClass)
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.languageClass
- the Truffle language class for a given guest languageDebugValue
public final String toDisplayString()
toDisplayString(true)
.DebugValue.toDisplayString(boolean)
public final String toDisplayString(boolean allowSideEffects) throws DebugException
allowSideEffects
- whether side-effects are allowed in the production of the string.DebugException
public final DebugValue getMetaObject() throws DebugException
InteropLibrary.getMetaObject(Object)
for detailed description.null
DebugException
- when guest language code throws an exceptionpublic final SourceSection getSourceLocation() throws DebugException
null
DebugException
- when guest language code throws an exceptionpublic final boolean canExecute() throws DebugException
true
if this value can be executed (represents a guest language
function), else false
.DebugException
public final DebugValue execute(DebugValue... arguments) throws DebugException
arguments
- Arguments passed to the executableDebugException
- when guest language code throws an exceptionDebugValue.canExecute()
public boolean hasIterator() throws DebugException
true
if the value provides an iterator. For details see
InteropLibrary.hasIterator(Object)
.DebugException
- if guest language code throws an exception.DebugValue.getIterator()
public DebugValue getIterator() throws DebugException
iterator
. For
details see InteropLibrary.getIterator(Object)
.DebugException
- if DebugValue.hasIterator()
returns false
or guest language code
throws an exception.DebugValue.hasIterator()
public boolean isIterator() throws DebugException
true
if this value represents an iterator. For details see
InteropLibrary.isIterator(Object)
.DebugException
- if guest language code throws an exception.DebugValue.hasIterator()
,
DebugValue.getIterator()
public boolean hasIteratorNextElement() throws DebugException
true
if the value is an iterator
which has more
elements, else false
. For details see
InteropLibrary.hasIteratorNextElement(Object)
.DebugException
- if DebugValue.isIterator()
returns false
or guest language code
throws an exception.DebugValue.isIterator()
,
DebugValue.getIteratorNextElement()
public DebugValue getIteratorNextElement() throws NoSuchElementException, DebugException
DebugValue.getIteratorNextElement()
may throw the NoSuchElementException
despite the
DebugValue.hasIteratorNextElement()
returned true
.DebugException
- if DebugValue.isIterator()
returns false
or when the underlying
iterator element exists but is not readable, or guest language code throws an
exception.NoSuchElementException
- if the iteration has no more elements.DebugValue.isIterator()
,
DebugValue.hasIteratorNextElement()
,
InteropLibrary.getIteratorNextElement(Object)
public boolean hasHashEntries() throws DebugException
true
if the value may have hash map entries. For details see
InteropLibrary.hasHashEntries(Object)
.DebugException
- if guest language code throws an exception.DebugValue.getHashEntriesIterator()
,
DebugValue.getHashSize()
,
DebugValue.isHashEntryReadable(DebugValue)
,
DebugValue.isHashEntryWritable(DebugValue)
,
DebugValue.isHashEntryInsertable(DebugValue)
,
DebugValue.isHashEntryRemovable(DebugValue)
,
DebugValue.getHashValue(DebugValue)
,
DebugValue.getHashValueOrDefault(DebugValue, DebugValue)
,
DebugValue.putHashEntry(DebugValue, DebugValue)
,
DebugValue.removeHashEntry(DebugValue)
public long getHashSize() throws DebugException
DebugException
- if DebugValue.hasHashEntries()
returns false
or guest language
code throws an exception.DebugValue.hasHashEntries()
public boolean isHashEntryReadable(DebugValue key) throws DebugException
true
if mapping for the specified key exists and is readable. If the
key
is obtained from DebugValue.getHashEntriesIterator()
or
DebugValue.getHashKeysIterator()
, it returns the same value as
key.
DebugValue.isReadable()
. For details see
InteropLibrary.isHashEntryReadable(Object, Object)
.DebugException
- if guest language code throws an exception.DebugValue.getHashValue(DebugValue)
public DebugValue getHashValue(DebugValue key) throws DebugException
null
if the mapping for the
specified key does not exist. The returned value, if any, is writable
if and only if DebugValue.isHashEntryWritable(DebugValue)
returns true for the entry key.DebugException
- if the value has no hash entries
, or guest
language code throws an exception.DebugValue.isHashEntryReadable(DebugValue)
,
DebugValue.getHashValueOrDefault(DebugValue, DebugValue)
public DebugValue getHashValueOrDefault(DebugValue key, DebugValue defaultValue) throws DebugException
defaultValue
when the
mapping for the specified key does not exist or is not readable.DebugException
- if the hash map does not support reading at all, or guest language
code throws an exception.DebugValue.isHashEntryReadable(DebugValue)
,
DebugValue.getHashValue(DebugValue)
public boolean isHashEntryModifiable(DebugValue key) throws DebugException
true
if mapping for the specified key exists and is
writable
. If the corresponding value is
obtained from DebugValue.getHashValue(DebugValue)
or from DebugValue.getHashEntriesIterator()
,
then it returns the same value as value.
DebugValue.isWritable()
. For details see
InteropLibrary.isHashEntryModifiable(Object, Object)
.DebugException
- if guest language code throws an exception.DebugValue.putHashEntry(DebugValue, DebugValue)
public boolean isHashEntryInsertable(DebugValue key) throws DebugException
true
if mapping for the specified key does not exist and is
writable
. For details see
InteropLibrary.isHashEntryInsertable(Object, Object)
.DebugException
- if guest language code throws an exception.DebugValue.putHashEntry(DebugValue, DebugValue)
public boolean isHashEntryWritable(DebugValue key) throws DebugException
DebugException
- if guest language code throws an exception.public void putHashEntry(DebugValue key, DebugValue value) throws DebugException
modifiable
, or not
existing and insertable
.DebugException
- if the hash map does not support writing at all, or mapping for the
specified key is not modifiable
nor
insertable
, or the provided key type
or value type is not allowed to be written, or guest language code throws an
exception.public boolean isHashEntryRemovable(DebugValue key) throws DebugException
true
if mapping for the specified key exists and is removable. For details
see InteropLibrary.isHashEntryRemovable(Object, Object)
.DebugException
- if guest language code throws an exception.DebugValue.removeHashEntry(DebugValue)
public boolean removeHashEntry(DebugValue key) throws DebugException
removable
.true
if the mapping was successfully removed, false
if mapping for a
given key does not exist.DebugException
- if the value does not have any hash entries
or if mapping for specified key exists
but cannot be removed.DebugValue.isHashEntryRemovable(DebugValue)
public boolean isHashEntryExisting(DebugValue key) throws DebugException
true
if mapping for a given key is existing. For details see
InteropLibrary.isHashEntryExisting(Object, Object)
.DebugException
- if guest language code throws an exception.public DebugValue getHashEntriesIterator() throws DebugException
iterator
of array
elements. The first array element
is a key, the second array element is the associated value. Array elements returned by the
iterator may be modifiable. Set
of the elements updates the hash
map.DebugException
- if DebugValue.hasHashEntries()
returns false
, or if guest
language code throws an exception.public DebugValue getHashKeysIterator() throws DebugException
iterator
.DebugException
- if DebugValue.hasHashEntries()
returns false
, or if guest
language code throws an exception.public DebugValue getHashValuesIterator() throws DebugException
iterator
.DebugException
- if DebugValue.hasHashEntries()
returns false
, or if guest
language code throws an exception.public int hashCode() throws DebugException
hashCode
in class Object
identity hash code
of the guest
object, if the object has identity
.DebugException
- when guest language code throws an exceptionpublic boolean equals(Object obj) throws DebugException
DebugValue
is equal to this. Two DebugValue
objects
are equal if and only if their guest objects are
identical
.equals
in class Object
DebugException
- when guest language code throws an exceptionpublic final LanguageInfo getOriginalLanguage() throws DebugException
null
for values representing a primitive value, or objects that are not
associated with any language.null
when no language can be identified as the creator
of the value.DebugException
- when guest language code throws an exceptionpublic final DebugValue asInLanguage(LanguageInfo language)
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.language
- a language to get the value representation ofpublic abstract DebuggerSession getSession()