Annotation Interface Option
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
Modifier and TypeClassDescriptionstatic @interface
Must be applied on classes containingoption
fields to specify a name prefix if the prefix cannot be inferred by language or instrument. -
Required Element Summary
Modifier and TypeRequired ElementDescriptionSpecifies the category of the option.Returns a help message for the option. -
Optional Element Summary
Modifier and TypeOptional ElementDescriptionboolean
Returnstrue
if this option is deprecated.Returns the deprecation reason and the recommended fix.Returns a custom name for the option.Specifies the most strict sandbox policy in which the option can be used.Defines the stability of this option.Describes in short the syntax of accepted values for this option.
-
Element Details
-
name
String nameReturns 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 thegroup name
and theoption name
separated by'.'
. If the option name is an emptyString
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 helpReturns 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 ofOptionDescriptor.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
- Include the default value for the option and the end of the text, e.g.
-
deprecated
boolean deprecatedReturnstrue
if this option is deprecated. The generated option descriptor returns this value as result ofOptionDescriptor.isDeprecated()
.- Since:
- 0.27
- Default:
false
-
deprecationMessage
String deprecationMessageReturns the deprecation reason and the recommended fix. The generated option descriptor returns this value as result ofOptionDescriptor.getDeprecationMessage()
.- Since:
- 20.1.0
- Default:
""
-
category
OptionCategory categorySpecifies the category of the option. The generated option descriptor returns this value as result ofOptionDescriptor.getCategory()
.- Since:
- 0.27
-
stability
OptionStability stabilityDefines the stability of this option. The default value isOptionStability.EXPERIMENTAL
.- Since:
- 19.0
- Default:
EXPERIMENTAL
-
usageSyntax
String usageSyntaxDescribes 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:
""
- 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.
-
sandbox
SandboxPolicy sandboxSpecifies 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 specifiesISOLATED
policy, it can be used for an engine/context configured with sandbox policyTRUSTED
,CONSTRAINED
orISOLATED
. But it cannot be used for an engine/context configured with theUNTRUSTED
sandbox policy.- Since:
- 23.0
- See Also:
- Default:
TRUSTED
-