Special comments in the Jedi Code Formatter

The code formatter now recognizes certain comments to disable and enable formatting options around blocks of code.

Since the earliest versions, the comments {(*} and {*)} could be used to disable and reenable formatting respectively, in order to exclude a block of code from formatting.

From version 0.52, a more extensive syntax has been implemented to allow for fine-grained control over which formatting options are temporarily disabled. The original special comments {(*} and {*)} are retained as synonymns for //jcf:format=off and //jcf:format=on respectively.

For instance, in the following line of code, the formatter will not alter the spacing

//jcf:space=off a := a + 1 ; //jcf:space=on

As you can see, the new syntax has the form of a comment like //jcf:flag=state, where state is one of on or off, and the flags are listed below.

Flags

Flag	Description
`all`	all=on is used to reverse the effects of all `off` comments, as described below. `all=off` is not valid
`format`	All formatting
`space`	All processes that insert or remove spaces
`addspace`	All processes that insert spaces
`removespace`	All processes that remove spaces
`return`	All processes that insert or remove returns
`addreturn`	All processes that insert returns
`removereturn`	All processes that remove returns
`add`	All processes that insert spaces or returns
`remove`	All processes that remove spaces or returns
`align`	All processes that align statements - i.e. alignment of variables, constants, types and assignment statements
`aligndef`	Alignment of variables, constants and types
`alignfn`	Alignment of variables and assignments
`alignvars`	Alignment of variables
`alignconst`	Alignment of constants
`aligntypedef`	Alignment of types
`alignassign`	Alignment of assignment
`indent`	Correct block indent of statements and declarations
`caps`	Capitalisation of reserved words or user-specified words
`capsreservedwords`	Capitalisation of reserved words
`capsspecificwords`	Capitalisation of user-specified words
`linebreaking`	Breaking of long lines
`blockstyle`	Line-breaking in blocks of statements
`warnings`	Warnings generated by the code fornatter
`findreplace`	Find and replace
`findreplaceuses`	Maniupulation of the uses clause

The following rules apply:

Turning a flag on will not enable it if it is not disabled in the configuration - the flags are to 'block out' a section of code where a format option is not wanted. The on state is there only to end a previous off state.
All processes turned off buy a flag comment remain turned off until the corresponding flag comment that turns it back on is reached, or the end of the file is reached, or the flag comment //jcf:all=on is reached.
The flag comment //jcf:all=on will reenable all processes that have been turned off by comments, ie it returns formatting to the options specified in the configuration.
Flag comments only affect the file in which they occur, from the position in which the occur onwards.
The effects of some of the flags overlap - this is done to allow degrees of granularity e.g. turn off all alignment, or just alignment of variable declarations for a block of code.
In these special comments, character case and some spaces are ignored.
A comment that starts with //jcf: but cannot be recognised as one of the options given will cause a warning in the log but will have no effect of the file's format.

For exampes see the test case unit TestExclusionFlags.pas, for implmentation see the unit FormatFlags.pas

Index