A Simple Preferences Specification File
package foo.bar;
page LPG {
fields {
boolean GenerateASTs { defvalue true; }
int MaxErrors { defvalue 100; }
dirlist IncludePath
}
}
A More Interesting Preferences Specification File
package org.eclipse.imp.lpg.preferences;
page LPG {
tabs {
default out { }
configuration in { }
instance in { }
project in { }
}
fields {
boolean GenerateASTs {
defvalue true;
tooltip "If true, automatically generate an AST hierarchy from the grammar";
}
int MaxErrors { defvalue 100; }
boolean UseDefaultExecutable { defvalue true; }
file ExecutableToUse {
tooltip "The full path to the LPG generator executable";
defvalue "${pluginResource:lpg.generator/lpgexe/lpg-${os}_${arch}}";
} unless UseDefaultExecutable
}
}
Preference Value Substitutions
The above example makes use of preference substitutions, which provide a set of variables
that can be interpolated into the values of string-typed preferences. These can be used not
only in hard-wired default values but also in user-supplied values. Substitutions are of one
of two forms: (1) ordinary preference keys, which cause the associated value to be interpreted,
and (2) predefined pseudo-keys, which provide access to various useful values, such as the
location of the workspace, a workspace project, a plugin resource, and the like.
The predefined pseudo-keys fall into two categories: simple and parameterized. Simple
pseudo-keys are accessed using the syntax ${key}. These are the simple pseudo-keys:
| Pseudo-key | Description |
| ${os} | A string indicating the operating system of the host environment |
| ${arch} | A string indicating the processor architecture of the host environment |
| ${workspaceLoc} | A string indicating the fully-qualified filesystem path to the workspace |
| ${nl} | A string indicating the local language of the host environment |
| ${ws} | A string identifying the windowing system of the host environment |
Parameterized pseudo-keys require one or more parameters, and use the syntax ${key:param}.
As of this writing, the only parameterized pseudo-keys take one parameter. They are as follows:
| Pseudo-key | Description |
| ${pluginLoc:pluginID} | A string indicating the fully-qualified filesystem path of the plugin's installation location |
| ${pluginResource:pluginID/resourcePath} | A string indicating the fully-qualified filesystem path of the resource with the given path in the given plugin |
| ${pluginVersion:pluginID} | A string giving the currently enabled version of the plugin with the given ID |
| ${projectLoc:projectName} | A string indicating the fully-qualified filesystem path of the project with the given name |
An Even More Interesting Preferences Specification File
package org.eclipse.imp.lpg.preferences;
choicetype Severity { error, warning, info }
page LPG {
tabs {
default out { }
configuration in { }
instance in { }
project in { }
}
fields {
boolean GenerateASTs {
defvalue true;
tooltip "If true, automatically generate an AST hierarchy from the grammar";
}
int MaxErrors { defvalue 100; }
boolean UseDefaultExecutable { defvalue true; }
file ExecutableToUse {
tooltip "The full path to the LPG generator executable";
defvalue "${pluginResource:lpg.generator/lpgexe/lpg-${os}_${arch}}";
} unless UseDefaultExecutable
radio Verbosity { values { low, high, ridiculous } defvalue low; }
combo NoSuchSymbol { type Severity; defvalue info; }
combo MissingProsthesisDecl { type Severity; defvalue warning; }
}
}
Preferences Specification Grammar
The following describes the syntax and meaning of the prefspecs language syntax, using
EBNF.
| Non-terminal | Description | Rules |
| packageSpec |
packageName is simply a fully-qualified Java package name, which identifies the
package into which the generated classes are to be placed. |
PACKAGE packageName ';' |
| Non-terminal | Description | Rules |
| detailsSpec |
This specification determines whether a "details link" is provided with each preference
field. This link, when clicked, brings up a dialog that displays information such as the
value in effect for that preference at that level, and where that value comes from (the
given level, or some higher level). |
DETAILS (ON | OFF) ';' |
| Non-terminal | Description | Rules |
| topLevelItem |
There are two types of top-level items: specifications of enumerated types that can be
reused across multiple preference fields (e.g. "error/warning/info"), and preference
page specifications. |
typeSpec | pageSpec |
Type Specifications
| Non-terminal | Description | Rules |
| typeSpec |
This declares an enumerated type that can be used in defining both radio- and combo-typed
preferences. |
CHOICETYPE identifier '{' staticOrDynamicValues '}' |
| Non-terminal | Description | Rules |
| staticOrDynamicValues |
There are two ways of defining the values for a CHOICETYPE: dynamic, which uses the
fully-qualified name of a class that computes the legal values, or a static set of string
values. |
DYNAMIC qualifiedClassName | labelledStringValue+',' |
| Non-terminal | Description | Rules |
| labelledStringValue |
This provides a name (a valid Java identifier) that uniquely identifies the value
(which is used by client code to identify this particular value), with an optional
label that is presented in the user interface. If the label is not given explicitly,
one is created from the identifier. |
identifier stringLabel? |
Page Specifications
| Non-terminal | Description | Rules |
| pageSpec |
|
PAGE pageName '{' pageBody '}' |
| Non-terminal | Description | Rules |
| pageName |
This construct specifies the name for the given preference page.
The name may be qualified, in which case this page is nested inside the innermost parent.
For example, the name specifier foo.bar will give this page the name bar
and nest it under the page named foo. |
(identifier '.')* identifier |
| Non-terminal | Description | Rules |
| pageBody |
A pageBody consists mainly of a set of field specifications.
At the moment, it is permissible (but not advisable) for the pageBody to include
one or more tabSpecs. optionalSpecs are used mostly to collect conditional field
specifications in one place (if the user so desires). |
tabsSpec fieldsSpec optionalSpecs |
Field Specifications
| Non-terminal | Description | Rules |
| fieldsSpec |
|
FIELDS '{' fieldSpec+ '}' |
Generic Field Properties
| Non-terminal | Description | Rules |
| generalSpec |
Properties that are valid for fields of any type |
labelSpec | toolTipSpec |
| Non-terminal | Description | Rules |
| labelSpec |
Specifies a non-default label for the preference field in the UI. |
LABEL STRING_LITERAL ';' |
| Non-terminal | Description | Rules |
| toolTipSpec |
Provides help text for the tool-tip for this preference field. |
TOOLTIP STRING_LITERAL ';' |
| Non-terminal | Description | Rules |
| conditionalSpec |
Establishes that this preference field is only enabled for editing if another (boolean)
field currently has the value true. Can be applied to fields of any type. |
(IF | UNLESS) identifier |
Field Types
Scalar-typed Fields
| Non-terminal | Description | Rules |
| booleanDefValueSpec |
|
DEFVALUE (true | false) ';' |
| Non-terminal | Description | Rules |
| intRangeSpec |
low and high are signed integer literals |
RANGE low '..' high ';' |
| Non-terminal | Description | Rules |
| intDefValueSpec |
|
DEFVALUE integer |
| Non-terminal | Description | Rules |
| doubleRangeSpec |
low and high are signed floating-point literals |
RANGE low '..' high ';' |
| Non-terminal | Description | Rules |
| doubleDefValueSpec |
|
DEFVALUE float |
String-typed Fields
| Non-terminal | Description | Rules |
| stringDefValueSpec |
|
DEFVALUE string ';' |
| Non-terminal | Description | Rules |
| stringValidatorSpec |
The fully-qualified name of a class implementing the interface org.eclipse.imp.preferences.fields.StringFieldEditor.Validator |
VALIDATOR qualClassName ';' |
Enumerated Field Types (Combos and Radios)
| Non-terminal | Description | Rules |
| comboFieldSpec |
Specifies a preference whose value can be any one of an enumerated list of string values.
Similar to the radio field type, but uses a combo box field widget. |
COMBO identifier '{' comboFieldPropertySpec* '}' conditionalSpec |
| Non-terminal | Description | Rules |
| radioFieldSpec |
Specifies a preference whose value can be any one of an enumerated list of string values.
Similar to the combo field type, but uses a radio button group. |
RADIO identifier '{' radioFieldPropertySpec* '}' conditionalSpec |
| Non-terminal | Description | Rules |
| columnsSpec |
This specifies the number of columns into which the radio button values should be grouped |
COLUMNS INTEGER ';' |
| Non-terminal | Description | Rules |
| typeOrValuesSpec |
The TYPE variant names a type defined by a CHOICETYPE declaration. |
TYPE identifier ';' | valuesSpec ';' |
| Non-terminal | Description | Rules |
| enumDefValueSpec |
Note that this specifies the identifier of the value, not the label (if one was specified) |
DEFVALUE identifier ';' |
Color Fields
| Non-terminal | Description | Rules |
| colorFieldSpec |
|
COLOR identifier '{' colorFieldPropertySpec* '}' conditionalSpec? |
| Non-terminal | Description | Rules |
| colorFieldPropertySpec |
red, green, and blue are all integer literals between 0 and 255 |
DEFVALUE red ',' green ',' blue ';' | generalSpec |
Font Fields
| Non-terminal | Description | Rules |
| fontDefValueSpec |
height is an integer |
DEFVALUE fontName height (NORMAL | BOLD | ITALIC) ';' |