Annotation Interface TruffleLanguage.Registration

Enclosing class:
TruffleLanguage<C>
@Retention(RUNTIME) @Target(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

  • Element Details

    • id

      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

      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

      String implementationName
      Unique name of your language implementation.
      Returns:
      the implementation name of your language
      Since:
      0.8 or earlier
      Default:
      ""

    • version

      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

      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:
      Default:
      ""

    • characterMimeTypes

      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:
      Default:
      {}

    • byteMimeTypes

      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:
      Default:
      {}

    • interactive

      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

      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

      String[] dependentLanguages
      Specifies a list of languages that this language depends on. Languages are referenced using their 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

      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:
      Default:
      EXCLUSIVE

    • services

      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

      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

      @Deprecated(since="24.1") boolean needsAllEncodings
      Deprecated.
      To enable all TruffleString encodings, it is sufficient to add the org.graalvm.shadowed.jcodings module to the language's module-info requires and ensure it is on the module path when languages are loaded. If the module can be found, and at least one languages requires it, all encodings are automatically enabled. When languages are loaded from the class path (i.e. as an unnamed module), having jcodings on the class path is enough to enable it.
      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

      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(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

      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:
      Default:
      TRUSTED

    • internalResources

      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:
      Default:
      {}

    • optionalResources

      String[] optionalResources
      A declarative list of optional InternalResource identifiers associated with this language. It is recommended to register all optional resource identifiers here. Specifying the resource identifier allows the language use the resource even if its implementation was omitted at runtime. To use the resource when its implementation was omitted the polyglot.engine.resourcePath.languageId system property must be specified and point to a path with the resources. This allows to omit the resource implementation class in standalone distributions.
      Since:
      25.0
      See Also:
      Default:
      {}