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.
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.
The formatter is manually invoked by pressing Ctrl+Shift+F, by selecting "Format" in the Source menu, or by right-clicking in the editor and selecting "Format" from the 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 "Correct Indentation" in the Source menu or the editor's contextual menu. No other formatting options are applied in this case.
The editor can format code automatically as you press the Enter key, depending on the value of the "Coding style mode" preference.
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:
After the Enter key is pressed, a new line is opened and indented to the same amount as the line above:
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.
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).
We select those lines that require reformatting in the next figure. In this case all of the task body is 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.
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.
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:
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:
When this preference is set to 3, this gives:
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:
If this preference were to be set to 1, the formatting would be as follows:
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:
If this preference is set to Non_Rm_Style, this code would be indented as:
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.
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.
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.
The checkbox preference "Use tabulations" specifies whether the editor should use tab characters when indenting. Space characters are used unless this preference is enabled.
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:
After formatting, the colons would be aligned as follows:
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:
After formatting, the colons would be aligned as follows:
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:
With this preference enabled, this code would be indented as:
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:
With this preference enabled, it will be indented as follows:
The checkbox preference "Indent comments" specifies whether to indent lines containing only comments and blanks, or to keep the indentation of these lines unchanged.
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:
With this preference enabled (and with the "Indent comment" preference enabled), formatting the code would result in the following:
