Package com.oracle.truffle.api

Annotation Interface Option

@Retention(CLASS) @Target(FIELD) public @interface Option
Describes the attributes of an option whose value is in a static field annotated by this annotation. If used in a class then a package-protected class following the name pattern $classNameOptionDescriptors is generated. The generated class implements OptionDescriptors and contains all options specified by the declaring class.

If the Option annotation is used in a subclass of TruffleLanguage or TruffleInstrument then the option descriptor prefix is automatically inherited from the language id or the instrument id. If the class is not a language or an instrument then the Option.Group annotation can be used on the class to specify a option group name prefix.

The option descriptor name is generated from the group name and the option name separated by '.'. If the option name is an empty String then the trailing '.' will be removed from the descriptor name such that it exactly matches the group name. If, for example, the option group is 'js' and the option name is inherited from the field name 'ECMACompatibility' then the full descriptor name is 'js.ECMACompatibility'.

Example usage: 

@TruffleLanguage.Registration(id = "mylang", name = "My Language",
                              version = "1.0")
abstract static class MyLanguage extends TruffleLanguage<Context> {

    // the descriptor name for MyOption1 is 'mylang.MyOption1'
    @Option(help = "Help Text.", category = OptionCategory.USER,
            stability = OptionStability.STABLE)
    static final OptionKey<String> MyOption1 = new OptionKey<>("");

    // the descriptor name for SecondOption is 'mylang.secondOption'
    @Option(help = "Help Text.", name = "secondOption",
            category = OptionCategory.EXPERT,
            stability = OptionStability.EXPERIMENTAL)
    static final OptionKey<Boolean> SecondOption = new OptionKey<>(false);

    @Override
    protected Context createContext(TruffleLanguage.Env env) {
        if (env.getOptions().get(SecondOption)) {
            // options are available via environment
        }
        return null;
    }

    @Override
    protected OptionDescriptors getOptionDescriptors() {
        // this class is generated by the annotation processor
        return new MyLanguageOptionDescriptors();
    }
}
.
Since:
0.27
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Option.Group
    Must be applied on classes containing option fields to specify a name prefix if the prefix cannot be inferred by language or instrument.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    OptionCategory
    category
    Specifies the category of the option.
    String
    help
    Returns a help message for the option.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    deprecated
    Returns true if this option is deprecated.
    String
    deprecationMessage
    Returns the deprecation reason and the recommended fix.
    String
    name
    Returns a custom name for the option.
    SandboxPolicy
    sandbox
    Specifies the most strict sandbox policy in which the option can be used.
    OptionStability
    stability
    Defines the stability of this option.
    String
    usageSyntax
    Describes in short the syntax of accepted values for this option.

  • Element Details

    • name

      String name
      Returns a custom name for the option. If not specified then the name of the annotated field is used.

      The option descriptor name is generated from the group name and the option name separated by '.'. If the option name is an empty String then the trailing '.' will be removed from the descriptor name such that it exactly matches the group name. If, for example, the option group is 'js' and the option name is inherited from the field name 'ECMACompatibility' then the full descriptor name is 'js.ECMACompatibility'.

      Since:
      0.27
      Default:
      ""

    • help

      String help
      Returns a help message for the option. New lines can be embedded in the message with "%n". The generated an option descriptor returns this value as result of OptionDescriptor.getHelp(). Recommendation:
      • Include the default value for the option and the end of the text, e.g. "Enable or disable the option (default: true)."
      Since:
      0.27

    • deprecated

      boolean deprecated
      Returns true if this option is deprecated. The generated option descriptor returns this value as result of OptionDescriptor.isDeprecated().
      Since:
      0.27
      Default:
      false

    • deprecationMessage

      String deprecationMessage
      Returns the deprecation reason and the recommended fix. The generated option descriptor returns this value as result of OptionDescriptor.getDeprecationMessage().
      Since:
      20.1.0
      Default:
      ""

    • category

      OptionCategory category
      Specifies the category of the option. The generated option descriptor returns this value as result of OptionDescriptor.getCategory().
      Since:
      0.27

    • stability

      OptionStability stability
      Defines the stability of this option. The default value is OptionStability.EXPERIMENTAL.
      Since:
      19.0
      Default:
      EXPERIMENTAL

    • usageSyntax

      String usageSyntax
      Describes in short the syntax of accepted values for this option. This value is used when generating help messages to better explain how to use the option. Combine with the help message to illustrate to users how to correctly use the option. For example: 
       @Option(name = "Enabled", help = "Enable/Disable the option.", usageSyntax = "true|false")
      Recommendations:
      • if the option accepts a discrete number of values (e.g. boolean, enum) list the values separated by a '|' character. The default value for enums should be placed as the first in the list. e.g. "true|false", "none|red|green|blue|white"
      • if the options accepts a value representing a well-known concept or a number representing particular units, place that concept/unit between < and > e.g. "<ms>", "<path>", "<country>", "<>"
      • if the options accepts a range of numbers use the range syntax: [a,b] for inclusive range from a to b, (a, b) for exclusive range from a to b, [a, b) for range from a to b including a and (a, b] for range from a to b including b. If the range is infinite use inf and -inf. For example: "[0, 100]", "(0.0, 1.0)", "[0, inf).
      • if the options accepts a comma-separated list, use two comma-separated values and a .... Apply these same recommendations to individual values, e.g. "<targetName>,<targetName>,...".
      • if the options accepts a custom format, describe the format in a generic manner e.g. ip address - "*.*.*.*", CSV Person - "<firstName>,<lastName>,<age>".
      Since:
      22.1
      Default:
      ""

    • sandbox

      SandboxPolicy sandbox
      Specifies the most strict sandbox policy in which the option can be used. The option can be used for an engine/context with the specified sandbox policy or a weaker one. For example, if an option specifies ISOLATED policy, it can be used for an engine/context configured with sandbox policy TRUSTED, CONSTRAINED or ISOLATED. But it cannot be used for an engine/context configured with the UNTRUSTED sandbox policy.
      Since:
      23.0
      See Also:
      Default:
      TRUSTED