com.oracle.truffle.api.vm

Class PolyglotEngine.Value

java.lang.Object

com.oracle.truffle.api.vm.PolyglotEngine.Value

Enclosing class:

PolyglotEngine

public abstract class PolyglotEngine.Value
extends Object

A future value wrapper. A user level wrapper around values returned by evaluation of various PolyglotEngine functions like PolyglotEngine.findGlobalSymbol(String) and PolyglotEngine.eval(Source) or a value returned by a subsequent execution. In case the PolyglotEngine has been initialized for asynchronous execution, the PolyglotEngine.Value represents a future - i.e., it is returned immediately, leaving the execution running on behind.

Since:

0.9

Method Summary

Modifier and Type	Method and Description
<T> T	as(Class<T> representation) Creates Java-typed foreign access to the object wrapped by this Value, a kind of cross-language "cast".
PolyglotEngine.Value	execute(Object... args) Executes this value, depending on its content.
Object	get() Returns the object represented by this value, possibly null.
PolyglotEngine.Value	getMetaObject() Get a meta-object of this value, if any.
SourceSection	getSourceLocation() Get a source location where this value is declared, if any.

Methods inherited from class java.lang.Object

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

Method Detail

get

public Object get()

Returns the object represented by this value, possibly null. The raw object can either be a wrapped primitive type (e.g. Number, String, Character, Boolean) or a TruffleObject representing more complex object created by a language.

Returns:

the object, possibly null

Throws:

Exception - in case it is not possible to obtain the value of the object

Since:

0.9

as

public <T> T as(Class<T> representation)

Creates Java-typed foreign access to the object wrapped by this Value, a kind of cross-language "cast". Results depend on the requested type:

• For primitive types such as Number, the value is simply cast and returned.
• A String is produced by the language that returned the value.
• A FunctionalInterface instance is returned if the value can be executed.
• Aggregate types such as List and Map are supported, including when used in combination with nested generics.

This method is useful for Java applications that interoperate with guest language code. The general strategy is to evaluate guest language code that produces the desired language element and then use this method to create a Java object of the appropriate type for Java access to the result. The tutorial "Embedding Truffle Languages in Java" contains examples.

Type Parameters:

T - the type of the requested view

Parameters:

representation - an interface describing the requested access (must be an interface)

Returns:

instance of the view wrapping the object of this value

Throws:

Exception - in case it is not possible to obtain the value of the object

ClassCastException - if the value cannot be converted to desired view

Since:

0.9

execute

public PolyglotEngine.Value execute(Object... args)

Executes this value, depending on its content.

• If the value represents a function, makes a foreign function call using appropriate Java arguments.
• If the value represents a field, then sets the field to the value of the first argument, if provided, and returns the (possibly new) value of the field.

This method is useful for Java applications that interoperate with guest language code. The general strategy is to evaluate guest language code that produces the desired language element. If that element is a guest language function, this method allows direct execution without giving the function a Java type. The tutorial "Embedding Truffle Languages in Java" contains examples.

Parameters:

args - arguments to pass when executing the value

Returns:

result of the execution wrapped in a non-null PolyglotEngine.Value

Throws:

Exception - signals problem during execution

Since:

0.9

getMetaObject

public PolyglotEngine.Value getMetaObject()

Get a meta-object of this value, if any. The meta-object represents a description of the value, reveals it's kind and it's features.

Returns:

a value representing the meta-object, or null

Since:

0.24

getSourceLocation

public SourceSection getSourceLocation()

Get a source location where this value is declared, if any.

Returns:

a source location of the object, or null

Since:

0.24