com.oracle.truffle.api.debug

Class DebugScope

java.lang.Object

com.oracle.truffle.api.debug.DebugScope

public final class DebugScope
extends Object

Representation of guest language scope at the current suspension point, or a top scope. It contains a set of declared and valid variables, if any. The scope associated with a frame is only valid as long as the associated frame is valid and methods on such scope need to be called on the frame's thread.

Since:

0.26

See Also:

DebugStackFrame.getScope(), DebuggerSession.getTopScope(String)

Method Summary

Modifier and Type	Method and Description
DebugValue	convertRawValue(Class<? extends TruffleLanguage<?>> languageClass, Object rawValue) Converts the value to a DebugValue, or returns null if the requesting language class does not match the root node guest language.
DebugValue	getDeclaredValue(String name) Get a local variable declared in this scope by name.
Iterable<DebugValue>	getDeclaredValues() Get local variables declared in this scope, valid at the current suspension point.
String	getName() Get a human readable name of this scope.
DebugScope	getParent() Get a parent scope.
DebugValue	getReceiver() Get value that represents the receiver object of this scope.
DebugValue	getRootInstance() Get value that represents root instance of this scope.
SourceSection	getSourceSection() Get a source section representing this scope.
boolean	isFunctionScope() Test if this scope represents the function scope at the frame it was obtained from.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getName

public String getName()

Get a human readable name of this scope.

Since:

0.26

getParent

public DebugScope getParent()
                     throws DebugException

Get a parent scope.

Returns:

the parent scope, or null.

Throws:

DebugException - when guest language code throws an exception

Since:

0.26

isFunctionScope

public boolean isFunctionScope()

Test if this scope represents the function scope at the frame it was obtained from.

Since:

0.26

getSourceSection

public SourceSection getSourceSection()
                               throws DebugException

Get a source section representing this scope. Please note that while this scope does not provide variables that are valid only after the suspension point, the source section can actually span after the suspension point.

Returns:

the source section, or null when not available.

Throws:

DebugException - when guest language code throws an exception

Since:

0.29

getReceiver

public DebugValue getReceiver()

Get value that represents the receiver object of this scope. The receiver object is represented as this in Java or JavaScript and self in Ruby, for instance.

The returned value has a name that represents the receiver in the guest language. The scope that represents the function provide receiver object, if there is one, other scopes do not provide it, unless they override it.

Returns:

value that represents the receiver, or null when there is no receiver object

Since:

19.0

getRootInstance

public DebugValue getRootInstance()

Get value that represents root instance of this scope. The value is an instance of guest language representation of the root node of this scope, e.g. a guest language function.

Returns:

the root instance value, or null when no such value exists.

Since:

19.3.0

getDeclaredValues

public Iterable<DebugValue> getDeclaredValues()
                                       throws DebugException

Get local variables declared in this scope, valid at the current suspension point. Call this method on parent, to get values of variables declared in parent scope, if any. The declared values do not contain a receiver.

This method is not thread-safe and will throw an IllegalStateException if called on another thread than it was created with.

Throws:

DebugException - when guest language code throws an exception

Since:

0.26

getDeclaredValue

public DebugValue getDeclaredValue(String name)
                            throws DebugException

Get a local variable declared in this scope by name. Call this method on parent, to get value of a variable declared in parent scope, if any.

This method is not thread-safe and will throw an IllegalStateException if called on another thread than it was created with.

Returns:

a value of requested name, or null when no such value was found.

Throws:

DebugException - when guest language code throws an exception

Since:

0.26

convertRawValue

public DebugValue convertRawValue(Class<? extends TruffleLanguage<?>> languageClass,
                                  Object rawValue)

Converts the value to a DebugValue, or returns null if the requesting language class does not match the root node guest language. 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 DebugValue.getRawValue(Class) where the raw guest language value is obtained from the DebugValue. Note that the rawValue must be a valid Interop value. If not, the method throws IllegalArgumentException.

Parameters:

languageClass - the Truffle language class for a given guest language

rawValue - the raw value

Returns:

the wrapped DebugValue

Throws:

IllegalArgumentException - when rawValue is not an Interop value

Since:

21.1