public abstract class NodeLibrary extends Library
Node
location. The receiver of this library must be an
instrumentable
Node
that has a root node
.Node.Child, Node.Children
Modifier | Constructor and Description |
---|---|
protected |
NodeLibrary() |
Modifier and Type | Method and Description |
---|---|
static LibraryFactory<NodeLibrary> |
getFactory()
Returns the library factory for the node library.
|
Object |
getReceiverMember(Object node,
Frame frame)
Returns an object that represents the receiver name when available.
|
Object |
getRootInstance(Object node,
Frame frame)
Returns the current instance of guest language representation of the root node (e.g.
|
Object |
getScope(Object node,
Frame frame,
boolean nodeEnter)
Get an object representing a local scope containing variables visible at the node location.
|
static NodeLibrary |
getUncached()
Returns the uncached automatically dispatched version of the node library.
|
static NodeLibrary |
getUncached(Object node)
Returns the uncached manually dispatched version of the node library.
|
Object |
getView(Object node,
Frame frame,
Object value)
Wraps the value to filter or add scoping specific information for values associated with the
current language and location in the code.
|
boolean |
hasReceiverMember(Object node,
Frame frame)
Returns
true , if there is a named receiver object, else false . |
boolean |
hasRootInstance(Object node,
Frame frame)
Returns
true , if a current instance of the guest language representation of the
root node (e.g. |
boolean |
hasScope(Object node,
Frame frame)
Returns
true , if the node is in a scope containing local variables, else
false . |
accept, adoptChildren, atomic, atomic, copy, deepCopy, getChildren, getCost, getDebugProperties, getDescription, getEncapsulatingSourceSection, getLock, getParent, getRootNode, getSourceSection, insert, insert, isAdoptable, isSafelyReplaceableBy, notifyInserted, onReplace, replace, replace, reportPolymorphicSpecialize, toString
public boolean hasScope(Object node, Frame frame)
true
, if the node is in a scope containing local variables, else
false
.
This method must not cause any observable side-effects. If this method is implemented then
also NodeLibrary.getScope(Object, Frame, boolean)
must be implemented.
node
- a Node, never null
frame
- a Frame
, can be null
in case of lexical access.NodeLibrary.getScope(Object, Frame, boolean)
public Object getScope(Object node, Frame frame, boolean nodeEnter) throws UnsupportedMessageException
true
to InteropLibrary.isScope(Object)
.
The scope object exposes all locally visible variables as flattened
members
, including all parent scopes (for example
block, closure, lexical or dynamic scopes). Local scopes are associated with a Frame
.
See InteropLibrary.isScope(Object)
for details.
This method must not cause any observable side-effects. If this method is implemented then
also NodeLibrary.hasScope(Object, Frame)
must be implemented.
A returned scope is only valid while the regular guest language execution on this thread is suspended. If the guest execution is continued e.g. if a new instrumentation event occurs, the scope is invalid and should be discarded.
node
- a Node, never null
frame
- a Frame
, can be null
in case of lexical access.nodeEnter
- when true
, the location that determines scope variables is at
the enter to the node execution, else false
. Use true
when called e.g. by instruments from
ExecutionEventNode.onEnter(VirtualFrame)
and false
when called e.g. from
ExecutionEventNode.onReturnValue(VirtualFrame, Object)
.
This argument helps to determine visible variables in case that some variables are
added during the node execution.InteropLibrary.isScope(Object)
being true.UnsupportedMessageException
- if and only if NodeLibrary.hasScope(Object, Frame)
returns
false
for the same node and frame.public boolean hasReceiverMember(Object node, Frame frame)
true
, if there is a named receiver object, else false
.
This method must not cause any observable side-effects. If this method is implemented then
also NodeLibrary.getReceiverMember(Object, Frame)
must be implemented.
node
- a Node, never null
frame
- a Frame
, can be null
in case of lexical access.NodeLibrary.getReceiverMember(Object, Frame)
public Object getReceiverMember(Object node, Frame frame) throws UnsupportedMessageException
InteropLibrary.isString(Object)
. Examples for receiver
names are this
in Java or self in Ruby or Python. The value of the
receiver object can be retrieved from the scope
by
converting the member to a string using InteropLibrary.isString(Object)
. The return
value of this method is an Object intentionally to allow the member to have additional
interop traits.
This method must not cause any observable side-effects. If this method is implemented then
also NodeLibrary.hasReceiverMember(Object, Frame)
must be implemented.
node
- a Node, never null
frame
- a Frame
, can be null
in case of lexical access.interop string object
.UnsupportedMessageException
- if and only if NodeLibrary.hasReceiverMember(Object, Frame)
returns false
for the same node and frame.NodeLibrary.hasReceiverMember(Object, Frame)
,
NodeLibrary.getScope(Object, Frame, boolean)
public boolean hasRootInstance(Object node, Frame frame)
true
, if a current instance of the guest language representation of the
root node (e.g. the enclosing guest language function) is available, else false
.
Guest languages will likely require a context lookup to resolve the root instance object.
This method must not cause any observable side-effects. If this method is implemented then
also NodeLibrary.getRootInstance(Object, Frame)
must be implemented.
node
- a Node, never null
frame
- a Frame
, can be null
in case of lexical access, in which
case the instance would likely not be available.NodeLibrary.getRootInstance(Object, Frame)
public Object getRootInstance(Object node, Frame frame) throws UnsupportedMessageException
This method must not cause any observable side-effects. If this method is implemented then
also NodeLibrary.hasRootInstance(Object, Frame)
must be implemented.
node
- a Node, never null
frame
- a Frame
, can be null
in case of lexical access, in which
case the instance would likely not be available.interop
and
executable
value.UnsupportedMessageException
- if and only if NodeLibrary.hasRootInstance(Object, Frame)
returns false
for the same node and frame.NodeLibrary.hasRootInstance(Object, Frame)
public Object getView(Object node, Frame frame, Object value)
This method is only invoked with values that are associated with the current
language
. For values without language the
language view
is requested first
before the scoped view is requested. If this method needs an implementation then
TruffleLanguage.getLanguageView(Object, Object)
should be implemented as well.
Scoped views may be implemented in a very similar way to
language views
. Please refer to the
examples from this method.
node
- the current source location. Guaranteed to be a node from a RootNode
associated with this language. Never null
.frame
- the current active frame. Guaranteed to be a frame from a RootNode
associated with this language. Never null
.value
- the value to provide scope information for. Never null
. Always
associated with this language.TruffleLanguage.getLanguageView(Object, Object)
public static LibraryFactory<NodeLibrary> getFactory()
ResolvedLibrary.resolve(NodeLibrary.class)
.LibraryFactory.resolve(Class)
public static NodeLibrary getUncached()
NodeLibrary.getFactory().getUncached()
.LibraryFactory.getUncached()
public static NodeLibrary getUncached(Object node)
NodeLibrary.getFactory().getUncached(v)
.LibraryFactory.getUncached(Object)