@Retention(value=CLASS) @Target(value=FIELD) public @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 extendsTruffleLanguage
<Context
> { // the descriptor name for MyOption1 is 'mylang.MyOption1' @Option
(help = "Help Text.", category =OptionCategory
.USER, stability =OptionStability
.STABLE) static finalOptionKey
<String
> MyOption1 = newOptionKey
<>(""); // the descriptor name for SecondOption is 'mylang.secondOption' @Option
(help = "Help Text.", name = "secondOption", category =OptionCategory
.EXPERT, stability =OptionStability
.EXPERIMENTAL) static finalOptionKey
<Boolean
> SecondOption = newOptionKey
<>(false); @Override
protectedContext
createContext(TruffleLanguage
.Env env) { if (env.getOptions().get(SecondOption)) { // options are available via environment } return null; } @Override
protectedOptionDescriptors
getOptionDescriptors() { // this class is generated by the annotation processor return new MyLanguageOptionDescriptors(); } }
OptionDescriptor
,
Option.Group
Modifier and Type | Required Element and Description |
---|---|
OptionCategory |
category
Specifies the category of the option.
|
String |
help
Returns a help message for the option.
|
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.
|
public abstract String help
"%n"
. The generated an option descriptor returns this value as result of
OptionDescriptor.getHelp()
.
Recommendation:
"Enable or disable the option (default: true)."
public abstract OptionCategory category
OptionDescriptor.getCategory()
.public abstract String name
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'
.
public abstract boolean deprecated
true
if this option is deprecated. The generated option descriptor
returns this value as result of OptionDescriptor.isDeprecated()
.public abstract String deprecationMessage
OptionDescriptor.getDeprecationMessage()
.public abstract OptionStability stability
OptionStability.EXPERIMENTAL
.public abstract String usageSyntax
@Option(name = "Enabled", help = "Enable/Disable the option.", usageSyntax = "true|false")Recommendations:
"true|false"
, "none|red|green|blue|white"
"<ms>"
, "<path>"
, "<country>"
,
"<>"
"[0, 100]"
, "(0.0, 1.0)"
, "[0, inf)
.
...
. Apply these same recommendations to individual values, e.g.
"<targetName>,<targetName>,..."
.
"*.*.*.*"
, CSV Person -
"<firstName>,<lastName>,<age>"
.
public abstract SandboxPolicy sandbox
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.SandboxPolicy