Code Formatter

The IntelliJ Platform includes a powerful framework for implementing custom language formatters. In this framework, the plugin specifies the constraints on the whitespaces between different syntax elements. The formatting engine, provided by the IDE, calculates the smallest number of whitespace modifications that need to be performed on the file to make it match the constraints.

The process of formatting a file or a file fragment consists of the following main steps:

• The formatting model builder (FormattingModelBuilder), implemented by the plugin, provides a formatting model (FormattingModel) for the document to be formatted.

• The formatting model is requested to build the structure of the file as applies to formatting, as a tree of blocks (Block) with an associated indent, wrap, alignment, and spacing settings.

• The formatting engine calculates the sequence of whitespace characters (spaces, tabs, and/or line breaks) that needs to be placed at every block boundary, based on the plugin's formatting model.

• The formatting model is requested to insert the calculated whitespace characters at necessary positions in the file.

The structure of blocks is usually built so that it mirrors the PSI structure of the file – for example, in Java code, the top-level formatting block covers the entire file. Its children cover individual classes in the file, blocks on the next level cover methods inside classes, etc. The formatter modifies only the characters between blocks, and the tree of blocks must be built so that the bottom-level blocks cover all non-whitespace characters in the file. Otherwise, the formatter may delete the characters between blocks.

To better understand how to build the block structure, use PsiViewer and inspect formatting blocks built for an existing language. To invoke PsiViewer with the possibility of inspecting Block Structure, use Tools | View PSI Structure... or Tools | View PSI Structure of Current File...:

To change the default "block name" taken from class name, return custom Block.getDebugName().

If the formatting operation does not affect the entire file (for example, if the formatter is called to format the pasted block of text), a complete tree of blocks is not built. Rather, only blocks for the text range covered by the formatting operation and their parents are built.

For every block, the plugin specifies the following properties:

• The spacing (Spacing) specifies what spaces or line breaks are inserted between the specified children of the block. The spacing object specifies the minimum and maximum number of spaces that must be placed between the specified child blocks, the minimum number of line breaks to put there, and whether the existing line breaks and blank lines should be preserved. The formatting model can also specify that the formatter may not modify the spacing between the specified blocks.

• The indent (Indent) specifies how the block is indented relative to its parent block. There are different modes of indenting defined by factory methods in the Indent class. The most commonly used are:

  • the none indent (which means the child block is not indented)

  • the regular indent (the child block is indented by the number of spaces specified in the Tabs and Indents | Indent code style setting)

  • the continuation indent (based on Tabs and Indents | Continuation indent code style setting)

  If the formatting model does not specify an indent, the "continuation without first" mode is used. This default means that the first block in a sequence of blocks with that type is not indented, and the following blocks are indented with a continuation indent.

• The wrap (Wrap) specifies whether the content of the block is wrapped to the next line. Wrapping is performed by inserting a line break before the block content. The plugin can specify that a particular block is never wrapped, always wrapped, or wrapped only if it exceeds the right margin.

• The alignment (Alignment) specifies which blocks should be aligned with each other. If two blocks with the alignment property set to the same object instance are placed in different lines, and if the second block is the first non-whitespace block in its line, the formatter inserts whitespaces before the second block, so that it starts from the same column as the first one.

For each of these properties, several particular use settings exist, described in the Javadoc comments for the respective classes. See also SpacingBuilder, which aids in building rule-based configuration.

An important special case in using the formatter is the smart indent performed when the user presses the Enter key in a source code file. To determine the indent for the new line, the formatter engine calls the method getChildAttributes() on either the block immediately before the caret or the parent of that block, depending on the return value of the isIncomplete() method for the block before the caret. If the block before the cursor is incomplete (contains elements that the user will probably type but has not yet typed, like a closing parenthesis of the parameter list or the trailing semicolon of a statement), getChildAttributes() is called on the block before the caret; otherwise, it's called on the parent block.

Code formatting can be suppressed per region via special comments.

Example: Custom Language Support Tutorial: Formatter