Whitespace

Whitespace

Ada-ASSURED automatically formats programs according to its built-in customizable style guide. This chapter provides a summary of the formatting capabilities. Vertical layout is determined by line breaks; horizontal layout is determined by blanks within lines. These are discussed separately below in

Section Vertical Whitespace
Section Horizontal Whitespace

Certain non-blank characters are also semantically irrelevant. For example, underscores in numbers have only aesthetic significance, and are therefore effectively whitespace. These are discussed below in

Section Other Whitespace

Vertical Whitespace

Line breaks are automatically introduced by the formatter according to the syntactic structure of programs. Some line breaks always occur regardless of how much room is left on a line. For example, assignment statements always appear on their own lines:

X := 1; Y := 2; Z := 3;

Other line breaks occur optionally depending on how much room is left on a line. For example, if the definition of an enumeration type fits entirely on one line, it is formatted that way:

type Color is (Red, White, Blue);

but if it does not fit, a line break is inserted after the is keyword:

type Color is (Red, White, Blue, Black);

If editor parameter Word Wrap is on, the width of the window influences where line breaks occur. As a window is resized, the program text is reformatted to fit. For example, a narrower window could lead to:

type Color is (Red, White, Blue, Black);

The format of some constructs can be customized using enforcement parameters. For example, if parameter Columnar Enumeration Literals is on, each literal appears on its own line regardless of window width:

type Color is (Red, White, Blue, Black);

The ``Columnar'' in the parameter name is best thought of as ``Unicolumnar''.

If Word Wrap is off, the formatter is not influenced by the width of a window. In this case, the maximum line length is determined solely by editor parameter Absolute Right Margin. When a window is too narrow to see all of a long line, you must scroll horizontally to see the rest of it.

When a program is saved to an ASCII file, window width is always ignored, i.e., only the parameter Absolute Right Margin controls line length. Although the formatter attempts to prevent any line from being longer than Absolute Right Margin, several circumstances can lead to longer lines. One pathological example is an identifier longer than Absolute Right Margin characters.

If Ada-ASSURED resource warnOnLineOverflow is True, an error message is generated for each line saved that is longer than Absolute Right Margin.

Window width is also ignored when a program is sent to a PostScript printer or when it is saved to a file in PostScript format. If print parameter Absolute Right Margin is on, lines on the page correspond exactly to lines in an ASCII file. If Absolute Right Margin is off, the program is formatted to fit the width of the page. In this case, the text may be more or less dense than the ASCII file representation and lines do not necessarily correspond.

Blank Lines

Extra blank lines can be inserted in reasonable contexts. For example:

A := 0; B := 1; C := 1; D := 2;

Blank lines are entered by typing extra LineFeed or Control+J characters as text is entered. They can also be created before and after the current structural selection using the transforms insert-blank-line and append-blank-line. To delete a blank line, just select it and delete it.

Blank lines are not permitted in arbitrary locations. For example, blank lines are not permitted within an expression and will be deleted.

Blank lines are inserted automatically by the formatter at certain locations. For example, if enforcement parameter Return Whitespace Enforcement is on, return statements are always surrounded with blank lines:

if X = 1 then return; else Y := 1; end if;

Care should be exercised in changing the settings of enforcement parameters that control the automatic generation of blank lines. In particular, when a text file is opened, its blank lines are interpreted according to the settings of the parameters. Turning on the automatic generation of blank lines after a file has been opened may lead to extra blank lines.

Form Feeds

Form-feed (Control+L [aka ASCII NP]) characters are permitted anywhere that user-inserted blank lines are permitted. Form feed characters can be inserted using transforms, or by cut and paste. The keystroke combination Control+L is by default bound to the command redraw-display.

Form feeds cause a new page to be taken when printing.

Horizontal Whitespace

Horizontal whitespace includes blank spaces at the beginning of a line (for indenting), within a line (for tabular displays and other pleasing visual effects), and at the end of a line (which have no visual effect, but may appear in an ASCII file nevertheless).

Indentation

Subordinate structures are indented automatically. The number of spaces is controlled by editor parameter Indentation. Continuation lines for a given structure that does not fit on a single line are indented an additional amount depending on context.

Interior Spaces

Blank spaces are inserted at various places on a line according to the syntactic structure of the program. For example, blanks are placed around operator symbols:

X := (Y + 1) * (Z + 1);

Blank spaces are also introduced on a line to provide tabular alignment of similar constructs. For example, colons and colon-equals are aligned within a group of similar declarations:

X, Y, Z : Meters := 0; K : Kilograms := 1;

An effort is made to avoid letting ``outliers'' distort tabular formats. For example,

F(Length => 0,
  Mass   => 0,
  An_Outlier_Too_Long_To_Be_Aligned =>
            0);

The enforcement parameters Maximum Column Width and Anomaly Sigmas allow fine control what is considered an outlier.

If the enumeration literals of a type definition must be split across several lines and enforcement parameter Columnar Enumeration Literals is off (no unicolumnar restriction), then the literals will be displayed in several columns. For example,

type Number is (One, Two, Three, Four, Five, Six, Seven, Eight, Nine, Ten);

Note that in this case, vertical and horizontal whitespace are interdependent.

Trailing Blanks

When an ASCII file is opened, all trailing blanks (except for those in comments) are deleted.

The formatter then inserts trailing blanks at certain locations to facilitate mouse and cursor navigation. For example, each statement in a list of statements (except the last) is given an extra trailing blank. Clicking the mouse to the left of this blank sets the structural selection to the statement, but clicking to the right of the blank selects the statement and its successor. When an ASCII file is saved, all trailing blanks (including those in comments) are trimmed if Ada-ASSURED resource trimTrailingBlanks is True.

Tabs

Explicit tabs are not supported. If a file contains tab characters within comments, then these should be converted to spaces in order to preserve the layout. Otherwise the tabs will be treated as single spaces and the original layout may be disturbed.

X The Unix utility expand may be used to do this automatically. The shell script conv, which may be found in the Ada-ASSURED/bin directory, will expand tabs in files given as arguments.

MS No utility is provided.

Other Whitespace

Some non-blank syntactic marks are effectively whitespace because they have no effect on the meaning of the program. Comments, the most notable example, are treated in detail in Chapter Comments. Here, we summarize more minor examples of such whitespace.

Underscores in numbers

If enforcement parameter Number Format Enforcement is on, underscores are automatically inserted within numeric constants. In binary and hexadecimal constants, underscores appear every 4 digits; in octal and decimal constants, they appear every 3 digits.

X1 := 12_345.123_45E+0; X2 := 16#0000_0000_0000#; X3 := 8#000_000_000_000#; X4 := 2#0000_0000_0000#;

When such numbers are edited, the underscores can be safely ignored—they will be readjusted by the formatter automatically.

Redundant parentheses

If enforcement parameter Preserve Parentheses is off, the formatter automatically removes redundant parentheses from expressions. For example, if the following line is typed or read in from an ASCII file

X := ((Y * Z) + W) + (Y * (Z + W));

it is be formatted as

X := Y * Z + W + Y * (Z + W);

If enforcement parameter Preserve Parentheses is on, parentheses are preserved exactly as entered.

Echoed names

Names of procedures, functions, packages, and tasks are echoed after both the begin and the end keywords of the unit. For example,

procedure p is <basic_declarative_item> begin -- p <statement> end p;

Block names are echoed similarly:

Block_123: declare <basic_declarative_item> begin -- Block_123 <statement> end Block_123;

as are loop names:

Loop_345: while B loop <statement> end loop Loop_345;

The defining occurrence of a name determines the name echoed, and if the name is changed by editing, echoed names are automatically made consistent. Although echoed names can be edited (i.e., they are not read-only), they are automatically reset to the defining name upon syntactic analysis.

X	The Unix utility expand may be used to do this automatically. The shell script conv, which may be found in the Ada-ASSURED/bin directory, will expand tabs in files given as arguments.
MS	No utility is provided.