Package 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:

  • Method Details

    • 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

    • getArguments

      @Deprecated(since="20.3") public Iterable<DebugValue> getArguments() throws DebugException
      Deprecated.
      since 20.3 Use getDeclaredValues() on the SourceElement.ROOT.
      Get arguments of this scope. If this scope is a function scope, function arguments are returned.

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

      Returns:
      an iterable of arguments, or null when this scope does not have a concept of arguments.
      Throws:
      DebugException - when guest language code throws an exception
      Since:
      0.26

    • 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