com.oracle.truffle.api

Annotation Type TruffleLanguage.Registration

@Retention(value=RUNTIME)
 @Target(value=TYPE)
public static @interface TruffleLanguage.Registration

The annotation to use to register your language to the Polyglot API. By annotating your implementation of TruffleLanguage by this annotation the language can be discovered on the class path.

Since:

0.8 or earlier

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String[]	byteMimeTypes List of MIME types supported by this language which sources should be interpreted as byte based sources.
String[]	characterMimeTypes List of MIME types supported by this language which sources should be interpreted as character based sources.
TruffleLanguage.ContextPolicy	contextPolicy Defines the supported policy for reusing languages per context.
String	defaultMimeType Returns the default MIME type of this language.
String[]	dependentLanguages Specifies a list of languages that this language depends on.
Class<? extends TruffleFile.FileTypeDetector>[]	fileTypeDetectors Declarative list of TruffleFile.FileTypeDetector classes provided by this language.
String	id Unique id of your language.
String	implementationName Unique name of your language implementation.
boolean	interactive Specifies if the language is suitable for interactive evaluation of sources.
boolean	internal Returns true if this language is intended for internal use only.
Class<? extends InternalResource>[]	internalResources Declarative list of InternalResource classes that is associated with this language.
String	name Unique name of your language.
boolean	needsAllEncodings Returns true if the language uses TruffleStrings with encodings not present in the following list.
SandboxPolicy	sandbox Specifies the most strict sandbox policy in which the language can be used.
Class<?>[]	services Declarative list of classes this language is known to provide.
String	version Unique string identifying the language version.
String	website A link to a website with more information about the language.

Element Detail

id

public abstract String id

Unique id of your language. This id will be exposed to users via the getter. It is used as group identifier for options of the language.

Returns:

identifier of your language

Since:

0.8 or earlier

Default:

""

name

public abstract String name

Unique name of your language. This name will be exposed to users via the Language.getName() getter.

Returns:

identifier of your language

Since:

0.8 or earlier

Default:

""

implementationName

public abstract String implementationName

Unique name of your language implementation.

Returns:

the implementation name of your language

Since:

0.8 or earlier

Default:

""

version

public abstract String version

Unique string identifying the language version. This name will be exposed to users via the Language.getVersion() getter. It inherits from Engine.getVersion() by default.

Returns:

version of your language

Since:

0.8 or earlier

Default:

"inherit"

defaultMimeType

public abstract String defaultMimeType

Returns the default MIME type of this language. The default MIME type allows embedders and other language or instruments to find out how content is interpreted if no MIME type was specified. The default MIME type must be specified in the list of supported character or byte based MIME types.

The default MIME type is mandatory if more than one supported MIME type was specified. If no default MIME type and no supported MIME types were specified then all sources for this language will be interpreted as character based sources.

Since:

19.0

See Also:

LanguageInfo.getDefaultMimeType(), Language.getDefaultMimeType(), TruffleLanguage.Registration.characterMimeTypes(), TruffleLanguage.Registration.byteMimeTypes()

Default:

""

characterMimeTypes

public abstract String[] characterMimeTypes

List of MIME types supported by this language which sources should be interpreted as character based sources. Languages may use MIME types to differentiate supported source kinds. If a MIME type is declared as supported then the language needs to be able to parse sources of this kind. If only one supported MIME type was specified by a language then it will be used as default MIME type. If no supported character and byte based MIME types are specified then all sources will be interpreted as character based.

Returns:

array of MIME types assigned to your language files

Since:

19.0

See Also:

TruffleLanguage.Registration.defaultMimeType(), TruffleLanguage.Registration.byteMimeTypes()

Default:

{}

byteMimeTypes

public abstract String[] byteMimeTypes

List of MIME types supported by this language which sources should be interpreted as byte based sources. Languages may use MIME types to differentiate supported source kinds. If a MIME type is declared as supported then the language needs to be able to parse sources of this kind. If only one supported MIME type was specified by a language then it will be used as default MIME type. If no supported character and byte based MIME types are specified then all sources will be interpreted as character based.

Returns:

array of MIME types assigned to your language files

Since:

19.0

See Also:

TruffleLanguage.Registration.defaultMimeType(), TruffleLanguage.Registration.characterMimeTypes()

Default:

{}

interactive

public abstract boolean interactive

Specifies if the language is suitable for interactive evaluation of sources. Interactive languages should be displayed in interactive environments and presented to the user. The default value of this attribute is true assuming majority of the languages is interactive. Change the value to false to opt-out and turn your language into non-interactive one.

Returns:

true if the language should be presented to end-user in an interactive environment

Since:

0.22

Default:

true

internal

public abstract boolean internal

Returns true if this language is intended for internal use only. Internal languages cannot be used in the host environment directly, they can only be used from other languages or from instruments.

Since:

0.27

Default:

false

dependentLanguages

public abstract String[] dependentLanguages

Specifies a list of languages that this language depends on. Languages are referenced using their TruffleLanguage.Registration.id(). This has the following effects:

• This language always has access to dependent languages if this language is accessible. Languages may not be accessible if language access is restricted.
• This language is finalized before dependent language contexts are finalized.
• This language is disposed before dependent language contexts are disposed.

Non-internal languages implicitly depend on all internal languages. Therefore by default non-internal languages are disposed and finalized before internal languages.

Dependent languages should be parsed with TruffleLanguage.Env.parseInternal(Source, String...) as the embedder might choose to disable access to it for TruffleLanguage.Env.parsePublic(Source, String...).

Dependent languages references are optional. If a dependent language is not installed and the language needs to fail in such a case then the language should fail on context initialization. Cycles in dependencies will cause an IllegalStateException when one of the cyclic languages is initialized.

Since:

0.30

Default:

{}

contextPolicy

public abstract TruffleLanguage.ContextPolicy contextPolicy

Defines the supported policy for reusing languages per context. I.e. the policy specifies the degree of sharing that is allowed between multiple language contexts. The default policy is exclusive. Every language is encouraged to try to support a context policy that is as permissive as possible, where exclusive is the least and shared is the most permissive policy. Parse caching is scoped per language instance, therefore the context policy influences its behavior.

The context policy applies to contexts that were created using the polyglot API as well as for inner contexts. The context policy does not apply to nodes that were created using the Truffle interop protocol. Therefore, interop message nodes always need to be prepared to be used with policy TruffleLanguage.ContextPolicy.SHARED.

Since:

19.0

See Also:

TruffleLanguage.parse(ParsingRequest)

Default:

EXCLUSIVE

services

public abstract Class<?>[] services

Declarative list of classes this language is known to provide. The language is supposed to override its createContext method and instantiate and register all here in defined services.

Languages automatically get created but not yet initialized when their registered service is requested.

Returns:

list of service types that this language can provide

Since:

19.0

Default:

{}

fileTypeDetectors

public abstract Class<? extends TruffleFile.FileTypeDetector>[] fileTypeDetectors

Declarative list of TruffleFile.FileTypeDetector classes provided by this language.

The language has to support all MIME types recognized by the registered file type detectors.

Returns:

list of file type detectors

Since:

19.0

Default:

{}

needsAllEncodings

public abstract boolean needsAllEncodings

Returns true if the language uses TruffleStrings with encodings not present in the following list.

• UTF-8
• UTF-16
• UTF-32
• ISO-8859-1
• US-ASCII
• BYTES

Since:

22.1

Default:

false

website

public abstract String website

A link to a website with more information about the language. Will be shown in the help text of GraalVM launchers.

The link can contain the following substitutions:

${graalvm-version}

the current GraalVM version. Optionally, a format string can be provided for the version using ${graalvm-version:format}. See Version.format(java.lang.String).

${graalvm-website-version}

the current GraalVM version in a format suitable for links to the GraalVM reference manual. The exact format may change without notice.

Returns:

URL for language website.

Since:

22.1.0

Default:

""

sandbox

public abstract SandboxPolicy sandbox

Specifies the most strict sandbox policy in which the language can be used. The language can be used in a context with the specified sandbox policy or a weaker one. For example, if a language specifies ISOLATED policy, it can be used in a context configured with sandbox policy TRUSTED, CONSTRAINED or ISOLATED. But it cannot be used in a context configured with the UNTRUSTED sandbox policy.

Since:

23.0

See Also:

SandboxPolicy

Default:

TRUSTED

internalResources

public abstract Class<? extends InternalResource>[] internalResources

Declarative list of InternalResource classes that is associated with this language. Use the internalResources attribute solely for registering required internal resources. Optional internal resources should provide the associated language identifier using the InternalResource.Id.componentId() method. To unpack all resources of a language embedders may use Engine.copyResources(Path, String...).

Since:

23.1

See Also:

InternalResource, InternalResource.Id

Default:

{}