6.1.3. Formatting Source Code

The GNATbench Ada language-sensitive editor provides a large number of built-in formatting controls that can be applied manually or automatically. These formatting controls are described in this chapter.

Note that you can format an entire file using the external pretty printer tool. See Pretty Printer for details.

Specific aspects of formatting are controlled by the Coding Style preference page.

Each of these formatting controls is applied when the formatting command is invoked, but in general they can be individually configured to have no effect if that is the desired behavior.

6.1.3.1. Manual Invocation

The formatter is manually invoked by pressing Ctrl+Shift+F, or by selecting “Format” under the Ada menubar entry and the editor’s Ada contextual menu. This command corrects applies the formatting options, including indentation.

Individual lines can also be formatted: if no selection is active when the command is invoked, only the current line is formatted.

In addition, indentation can be manually corrected by pressing Ctrl+I, or by selecting “Indent” under the Ada menubar entry and the editor’s Ada contextual menu. No other formatting options are applied in this case.

6.1.3.2. Automatic Invocation

The editor can format code automatically as you press the Enter key, depending on the value of the “Coding style mode” preference on the “Coding Style” preference page.

Selecting the mode “None” means no formatting will be applied; the cursor will simply go column 1 of the new line.

The “Simple” mode means that the indentation from the previous line will be used for the next line; the beginning of the new line will be indented to the same amount as the line containing the cursor when the Enter key was pressed. No other formatting is applied.

For example, in the following figure the mode is “Simple” and the Enter key is about to be pressed:

simple mode example before enter

After the Enter key is pressed, a new line is opened and indented to the same amount as the line above:

simple mode example after enter

In the “Extended” mode, the line is automatically formatted. The formatter indents the new line as you would indent it yourself, based on the context. For example, if you start a new sequence of statements with the reserved word “begin” and press the Enter key, the new line after the “begin” will be indented to the next level. All other formatting options are also applied.

See Smart Enter Key for an example.

6.1.3.3. Formatting Selected Lines

When a number of lines of source are selected, the selected code will be formatted based on an analysis of the selection as well as the surrounding code. In particular, the selection will be indented relative to that of the surrounding code.

In this initial figure, the lines for the task body are incorrectly indented (in an admittedly unlikely extreme).

reformatting initial state

We select those lines that require reformatting in the next figure. In this case all of the task body is selected:

reformatting selected

The following figure shows the result after formatting. The selection itself is now properly indented but, in addition, its indentation is consistent with the surrounding code.

reformatted final state

6.1.3.4. Indenting Continuation Lines

The numeric preference value “Continuation lines” specifies the amount to indent when the Enter key is pressed before the end of a line, thereby continuing that line on a new line below. This new line is indented by the value of the preference. In the following example, the Enter key was pressed on line 10, just before the semicolon of the assignment operation. All text to the right of the cursor was then moved down to a new line, now line 11, with the indentation preference value applied.

indenting continuation lines

6.1.3.5. Indenting Declaration Lines

The numeric preference value “Declaration lines” specifies the amount to indent multiple-line declarations. For example, using a value of 3, the following figure illustrates how three variables declared with one declaration would be indented:

indenting declaration lines

6.1.3.6. Indenting Conditional Continuation Lines

The numeric preference value “Conditional continuation lines” specifies the amount to indent multiple-line conditional expressions within parentheses.

For example, when this preference is set to 1, continuation lines are indented based on the previous parenthesis plus one space:

conditional continuation line 1 space

When this preference is set to 3, this gives:

conditional continuation line 3 spaces

6.1.3.7. Indenting Record Definitions

The numeric preference value “Record indentation” specifies the amount to indent record definitions when the reserved word “record” appears on its own line.

For example, when this preference is set to 3, the following sample will be indented as shown:

record type def indented 3 spaces

If this preference were to be set to 1, the formatting would be as follows:

record type def indented 1 spaces

6.1.3.8. Indenting Case Statement Alternatives

The radio button preference “Case indentation” specifies whether GNATbench should indent case statement alternatives with an extra level, as is done in the Ada Reference Manual, e.g:

case indent rm style

If this preference is set to Non_Rm_Style, this code would be indented as:

case indent non-rm style

By default (Automatic), GNATbench will choose whether to indent based on the first “case alternative” construct: if the first “when” is indented by an extra level, the whole case statement will be indented following the RM style.

6.1.3.9. Correcting Letter Casing

Reserved words and identifiers can be formatted per the letter casing specified by the user. Reserved words and identifiers are configured individually in the Coding Style preferences via the “Reserved words casing” and “Identifier casing” preferences.

There are five letter casing modes supported. These modes are described in the following paragraphs and are cased in a manner indicating their effect.

With the first mode, “none”, no formatting changes occur.

Using the second mode, “lower_case”, reserved words and/or identifiers are changed to all lower-case.

Using the third mode, “UPPER_CASE”, reserved words and/or identifiers are changed to all upper-case.

Using the fourth mode, “Mixed_Case”, reserved words and/or identifiers are changed such that the first letter of the word and any letter immediately following an underscore are in upper-case, with all other letters in lower-case.

The fifth mode, “Smart_CASE”, is similar to Mixed_Case except that upper-case letters remain in upper-case. For example, “text_IO” becomes “Text_IO” in this mode. The benefit of this mode is that upper-case acronyms in the identifier are retained.

6.1.3.10. Formatting Operators and Delimiters

The checkbox preference “Format operators / delimiters” specifies whether the editor should add extra spaces around operators and delimiters, if needed. If enabled, an extra space will be added when needed in the following cases: before an opening parenthesis; after a closing parenthesis, comma, semicolon; around all Ada operators.

6.1.3.11. Indenting with Tab Characters

The checkbox preference “Use tabulations” specifies whether the editor should use tab characters when indenting. Space characters are used unless this preference is enabled.

6.1.3.12. Aligning Colons in Declarations

The checkbox preference “Align colons in declarations” specifies whether the editor should automatically align colons in declarations and parameter lists.

Consider the following code, in which the colons are not aligned:

unaligned colons in declarations

After formatting, the colons would be aligned as follows:

aligned colons in declarations

Note that the colons in the declarations within the selection were aligned with those of another declaration, that of line 89, even though the other declaration was not in the selection. The other declaration was considered in the same “block” of declarations because there was nothing separating them, such as a blank line. Hence, the general rule is that the colons of declarations in the same block are aligned, even if not in the selection when formatting was applied. The colons of separate declaration blocks are not aligned, even if selected together, unless by coincidence.

In the following example, two separate blocks of declarations are selected:

unaligned colons in two declaration blocks

After formatting, the colons would be aligned as follows:

aligned colons in two declaration blocks

6.1.3.13. Aligning Associations on Arrow Symbols

The checkbox preference “Align associations on arrows” specifies whether the editor should automatically align arrows in associations (e.g., aggregates or function calls).

Consider the following code, in which the arrow symbols are not aligned on lines 10 through 13:

arrow symbol unaligned

With this preference enabled, this code would be indented as:

arrow symbol aligned

6.1.3.14. Aligning Declarations After the Colon

The checkbox preference “Align declarations after colon” specifies whether the editor should align continuation lines in variable declarations based on the colon character.

Consider the following declaration, in which the initial (only) value in the continuation line is in the column before that of the colon:

continuation before colon

With this preference enabled, it will be indented as follows:

continuation after colon

6.1.3.15. Indenting Comments

The checkbox preference “Indent comments” specifies whether to indent lines containing only comments and blanks, or to keep the indentation of these lines unchanged.

6.1.3.16. Aligning Comments on Keywords

The checkbox preference “Align comments on keywords” specifies whether to align comment lines following the reserved words “record” and “is” immediately, with no extra space.

Note that the “Indent comment” preference must be enabled before comments are formatted.

Consider the following source code, in which the comment is indented relative to the line above. This would be the effect of formatting the code with the preference disabled:

comment aligned with keyword

With this preference enabled (and with the “Indent comment” preference enabled), formatting the code would result in the following:

comment indented after keyword