Option (GraalVM Truffle Java API Reference)

@Retention(value=CLASS)
 @Target(value=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:: OptionDescriptor, Option.Group

Required Element Summary

Required Elements
Modifier and Type Required Element and Description

OptionCategory category
Specifies the category of the option.

String help
Returns a help message for the option.

Required Elements
Modifier and Type	Required Element and 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 and 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 Detail
  - help
```
public abstract 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
- - category
```
public abstract OptionCategory category
```
    Specifies the category of the option. The generated option descriptor returns this value as result of OptionDescriptor.getCategory().
    
    Since:
    
    0.27
- - name
```
public abstract 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:
    
    ""
- - deprecated
```
public abstract 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
```
public abstract 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:
    
    ""
- - stability
```
public abstract OptionStability stability
```
    Defines the stability of this option. The default value is OptionStability.EXPERIMENTAL.
    
    Since:
    
    19.0
    
    Default:
    
    EXPERIMENTAL
- - usageSyntax
```
public abstract 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
```
public abstract 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:
    
    SandboxPolicy
    
    Default:
    
    TRUSTED

Annotation Type Option

Required Element Summary

Optional Element Summary

Element Detail

help

category

name

deprecated

deprecationMessage

stability

usageSyntax

sandbox