The Format DSL is intended to be used when creating a format configuration. It is basically a frontend to Xtext’s declarative formatter framework.
For a general introduction on Xtext formatting, see the Xtext manual section on formatting.
Declaring a formatting configuration
The language specific formatting is declared using the Format DSL. The format configuration source file is transformed into Java classes by the appropriate generator.
The generated artefacts are
AbstractMyDslFormatter. The former is only
generated once, i.e. never overwritten, and the latter is always regenerated.
MyDslFormatter one can declare parts of the format configuration which cannot be expressed
in Format DSL (using instructions provided by Xtext formatting framework).
When generated for the first time,
MyDslFormatter may be incorrect. Watch out for missing implementations for abstract methods.
The declared formatting configuration is applied between semantic tokens, i.e. a formatter inserts/removes/modifies white space between tokens. The Format DSL runtime extends the limited locator vocabulary of Xtext and and has an improved method to combine multiple locators for a grammar element. The Format DSL runtime component
DdkFormattingConfigBasedStreamcombines locators by category, so a
no_spacelocator will not affect a
DDK / Variable space locators
Xtext offers only one space locator - space. It takes a fixed string as an argument, which is added to a grammar element. More elaborate formatting, such as padding a grammar element to a minimum length is not possible.
In DDK additional locators, such as
With the Xtext formatter space locators always take precedence over linewrap locators, which makes it very difficult to define line wrapping for optional elements.
Consider the Xtext rule Block:
"begin" (ID)+ "end". We want to declare formatting such that there is a linewrap before end and two spaces after each
FormattingConfigBasedStreamthere is no way to cause end to be on a new line.