com.oracle.truffle.api.metadata

Class Scope

java.lang.Object

com.oracle.truffle.api.metadata.Scope

public final class Scope
extends Object

Representation of a scope in a guest language program. The scope is a section of a program that contains a set of declared and valid variables. The scopes can be both lexical and dynamic.

Since:

0.26

See Also:

Scope.findScopes(com.oracle.truffle.api.instrumentation.TruffleInstrument.Env, com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.Frame)

Method Summary

Modifier and Type	Method and Description
static Iterable<Scope>	findScopes(TruffleInstrument.Env instrumentEnv, Node node, Frame frame) Find a list of scopes enclosing the given node.
Object	getArguments(Frame frame) Get arguments of this scope.
String	getName() Human readable name of this scope.
Node	getNode() Get a node representing this scope.
Object	getVariables(Frame frame) Get variables declared in this scope and valid at the Node passed to Scope.findScopes(com.oracle.truffle.api.instrumentation.TruffleInstrument.Env, com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.Frame) .

Methods inherited from class java.lang.Object

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

Method Detail

findScopes

public static Iterable<Scope> findScopes(TruffleInstrument.Env instrumentEnv,
                                         Node node,
                                         Frame frame)

Find a list of scopes enclosing the given node. There is at least one scope provided, that corresponds to the enclosing function. The iteration order corresponds with the scope nesting, from the inner-most to the outer-most. The scopes contain variables valid at the provided node.

In general, there can be a different list of scopes with different variables and arguments returned for different Frame instances, as scopes may depend on runtime information. Known lexical scopes are returned when frame argument is null.

Parameters:

instrumentEnv - the instrument environment that is used to look-up the ScopeProvider service.

node - a node to get the enclosing scopes for. The node needs to be inside a RootNode associated with a language.

frame - The current frame the node is in, or null for lexical access when the program is not running, or is not suspended at the node's location.

Returns:

an Iterable providing list of scopes from the inner-most to the outer-most.

Since:

0.26

See Also:

ScopeProvider.findScope(java.lang.Object, com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.Frame)

getName

public String getName()

Human readable name of this scope. A name description like block, name of a function, closure, script, module, etc.

Since:

0.26

getNode

public Node getNode()

Get a node representing this scope. Functional scopes return the appropriate RootNode .

Returns:

the node, or null when no node is associated.

Since:

0.26

getVariables

public Object getVariables(Frame frame)

Get variables declared in this scope and valid at the Node passed to Scope.findScopes(com.oracle.truffle.api.instrumentation.TruffleInstrument.Env, com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.Frame) . In general, there can be different variables returned when different Frame instances are provided.

Parameters:

frame - The current frame, or null for lexical access when the program is not running, or is not suspended at the scope's location. The variables might not be readable/writable with the null frame.

Returns:

A TruffleObject containing the variables as its properties, not null.

Since:

0.26

getArguments

public Object getArguments(Frame frame)

Get arguments of this scope. In general, there can be different arguments returned when different Frame instances are provided.

Parameters:

frame - The current frame, or null for lexical access when the program is not running, or is not suspended at the scope's location. The arguments might not be readable/writable with the null frame.

Returns:

A TruffleObject containing the arguments as its properties for named arguments, or as its array for unnamed arguments. A null is returned when this scope does not have a concept of arguments. An empty TruffleObject is provided when it has a sense to have arguments (e.g. function scope), but there are none.

Since:

0.26