@item -X@var{name}=@var{value}
@cindex @option{-X} @command{gnatelim}
Indicates that external variable @var{name} in the argument project
-has the @var{value} value. Has no effect if no project is specified as
+has the value @var{value}. Has no effect if no project is specified as
tool argument.
@item ^-files^/FILES^=@var{filename}
To invoke the old formatting algorithms, use the @option{--pp-old} switch.
Support for @option{--pp-old} will be removed in some future version.
-To produce a reformatted file, @command{gnatpp} generates and uses the ASIS
-tree for the input source and thus requires the input to be syntactically and
-semantically legal.
-If this condition is not met, @command{gnatpp} will terminate with an
-error message; no output file will be generated.
+To produce a reformatted file, @command{gnatpp} invokes the Ada
+compiler and generates and uses the ASIS tree for the input source;
+thus the input must be legal Ada code.
@command{gnatpp} cannot process sources that contain
preprocessing directives.
-If the compilation unit
-contained in the input source depends semantically upon units located
-outside the current directory, you have to provide the source search path
-when invoking @command{gnatpp}, if these units are contained in files with
-names that do not follow the GNAT file naming rules, you have to provide
-the configuration file describing the corresponding naming scheme;
-see the description of the @command{gnatpp}
-switches below. Another possibility is to use a project file and to
-call @command{gnatpp} through the @command{gnat} driver
-(see @ref{The GNAT Driver and Project Files}).
+If the compilation unit contained in the input source depends
+semantically upon units located outside the current directory, you
+have to provide the source search path when invoking
+@command{gnatpp}. If these units are contained in files with names
+that do not follow the GNAT file naming rules, you have to provide a
+configuration file describing the corresponding naming scheme; see the
+description of the @command{gnatpp} switches below. Another
+possibility is to use a project file and to call @command{gnatpp}
+through the @command{gnat} driver (see @ref{The GNAT Driver and
+Project Files}).
The @command{gnatpp} command has the form
@item
@var{filename} is the name (including the extension) of the source file to
-reformat; ``wildcards'' or several file names on the same gnatpp command are
-allowed. The file name may contain path information; it does not have to
+reformat; wildcards or several file names on the same gnatpp command are
+allowed. The file name may contain path information; it does not have to
follow the GNAT file naming rules
@item
@samp{@var{gcc_switches}} is a list of switches for
@command{gcc}. They will be passed on to all compiler invocations made by
-@command{gnatelim} to generate the ASIS trees. Here you can provide
+@command{gnatpp} to generate the ASIS trees. Here you can provide
@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
-use the @option{-gnatec} switch to set the configuration file,
-use the @option{-gnat05} switch if sources should be compiled in
-Ada 2005 mode etc.
+use the @option{-gnatec} switch to set the configuration file, etc.
@end itemize
@node Switches for gnatpp
each must be specified in full, with both the name and the value.
Abbreviated forms (the name appearing once, followed by each value) are
not permitted.
-For example, to set
-the alignment of the assignment delimiter both in declarations and in
-assignment statements, you must write @option{-A2A3}
-(or @option{-A2 -A3}), but not @option{-A23}.
@end ifclear
@ifset vms
case, or mixed case), and thus exactly one such option can be in effect for
an invocation of @command{gnatpp}.
If more than one is supplied, the last one is used.
-However, some qualifiers have options that are mutually compatible,
-and then you may then supply several such options when invoking
-@command{gnatpp}.
@end ifset
-In most cases, it is obvious whether or not the
-^values for a switch with a given name^options for a given qualifier^
-are compatible with each other.
-When the semantics might not be evident, the summaries below explicitly
-indicate the effect.
-
@menu
* Alignment Control::
* Casing Control::
-* Construct Layout Control::
* General Text Layout Control::
* Other Formatting Options::
* Setting the Source Search Path::
@noindent
Programs can be easier to read if certain constructs are vertically aligned.
-By default all alignments are set ON.
-Through the @option{^-A0^/ALIGN=OFF^} switch you may reset the default to
-OFF, and then use one or more of the other
-^@option{-A@var{n}} switches^@option{/ALIGN} options^
-to activate alignment for specific constructs.
+By default alignment of the following constructs is set ON:
+@code{:} in declarations, @code{:=} in initializations in declarations
+@code{:=} in assignment statements, @code{=>} in associations, and
+@code{at} keywords in the component clauses in record
+representation clauses.
@table @option
@cindex @option{^-A@var{n}^/ALIGN^} (@command{gnatpp})
-@ifset vms
-@item /ALIGN=ON
-Set all alignments to ON
-@end ifset
-
@item ^-A0^/ALIGN=OFF^
-Set all alignments to OFF
-
-@item ^-A1^/ALIGN=COLONS^
-Align @code{:} in declarations
-
-@item ^-A2^/ALIGN=DECLARATIONS^
-Align @code{:=} in initializations in declarations
+Set alignment to OFF
-@item ^-A3^/ALIGN=STATEMENTS^
-Align @code{:=} in assignment statements
-
-@item ^-A4^/ALIGN=ARROWS^
-Align @code{=>} in associations
-
-@item ^-A5^/ALIGN=COMPONENT_CLAUSES^
-Align @code{at} keywords in the component clauses in record
-representation clauses
+@item ^-A1^/ALIGN=ON^
+Set alignment to ON
@end table
-@noindent
-The @option{^-A^/ALIGN^} switches are mutually compatible; any combination
-is allowed.
-
@node Casing Control
@subsection Casing Control
@cindex Casing control in @command{gnatpp}
via a set of dictionary files.
Three types of casing are supported: lower case, upper case, and mixed case.
-Lower and upper case are self-explanatory (but since some letters in
-Latin1 and other GNAT-supported character sets
-exist only in lower-case form, an upper case conversion will have no
-effect on them.)
``Mixed case'' means that the first letter, and also each letter immediately
following an underscore, are converted to their uppercase forms;
all the other letters are converted to their lowercase forms.
@option{^-D@var{file}^/DICTIONARY=@var{file}^} switches are mutually
compatible.
-@node Construct Layout Control
-@subsection Construct Layout Control
-@cindex Layout control in @command{gnatpp}
-
@noindent
This group of @command{gnatpp} switches controls the layout of comments and
complex syntactic constructs. See @ref{Formatting Comments} for details
@table @option
@cindex @option{^-c@var{n}^/COMMENTS_LAYOUT^} (@command{gnatpp})
@item ^-c0^/COMMENTS_LAYOUT=UNTOUCHED^
-All the comments remain unchanged
+All comments remain unchanged.
@item ^-c1^/COMMENTS_LAYOUT=DEFAULT^
-GNAT-style comment line indentation (this is the default).
-
-@item ^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^
-Reference-manual comment line indentation.
+GNAT-style comment line indentation.
+This is the default.
@item ^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^
-GNAT-style comment beginning
+GNAT-style comment beginning.
@item ^-c4^/COMMENTS_LAYOUT=REFORMAT^
-Reformat comment blocks
+Fill comment blocks.
@item ^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^
-Keep unchanged special form comments
+Keep unchanged special form comments.
+This is the default.
@item --comments-only
@cindex @option{--comments-only} @command{gnatpp}
Format just the comments.
-@cindex @option{^-l@var{n}^/CONSTRUCT_LAYOUT^} (@command{gnatpp})
-@item ^-l1^/CONSTRUCT_LAYOUT=GNAT^
-GNAT-style layout (this is the default)
-
-@item ^-l2^/CONSTRUCT_LAYOUT=COMPACT^
-Compact layout
-
-@item ^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^
-Uncompact layout
-
-@cindex @option{^-N^/NOTABS^} (@command{gnatpp})
-@item ^-N^/NOTABS^
-All the VT characters are removed from the comment text. All the HT characters
-are expanded with the sequences of space characters to get to the next tab
-stops.
-
@cindex @option{^--no-separate-is^/NO_SEPARATE_IS^} (@command{gnatpp})
@item ^--no-separate-is^/NO_SEPARATE_IS^
Do not place the keyword @code{is} on a separate line in a subprogram body in
case if the spec occupies more than one line.
-@cindex @option{^--separate-label^/SEPARATE_LABEL^} (@command{gnatpp})
-@item ^--separate-label^/SEPARATE_LABEL^
-Place statement label(s) on a separate line, with the following statement
-on the next line.
-
@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
Place the keyword @code{loop} in FOR and WHILE loop statements and the
@item ^--use-on-new-line^/USE_ON_NEW_LINE^
Start each USE clause in a context clause from a separate line.
-@cindex @option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^} (@command{gnatpp})
-@item ^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^
-Use a separate line for a loop or block statement name, but do not use an extra
-indentation level for the statement itself.
-
@cindex @option{^--insert-blank-lines^/INSERT_BLANK_LINES^} (@command{gnatpp})
@item ^--insert-blank-lines^/INSERT_BLANK_LINES^
Insert blank lines where appropriate (between bodies and other large
@ifclear vms
@noindent
-The @option{-c1} and @option{-c2} switches are incompatible.
-The @option{-c3} and @option{-c4} switches are compatible with each other and
-also with @option{-c1} and @option{-c2}. The @option{-c0} switch disables all
-the other comment formatting switches.
-
-The @option{-l1}, @option{-l2}, and @option{-l3} switches are incompatible.
+The @option{-c} switches are compatible with one another, except that
+the @option{-c0} switch disables all other comment formatting
+switches.
@end ifclear
@ifset vms
@noindent
-For the @option{/COMMENTS_LAYOUT} qualifier:
-@itemize @bullet
-@item
-The @option{DEFAULT} and @option{STANDARD_INDENT} options are incompatible.
-@item
-The @option{GNAT_BEGINNING} and @option{REFORMAT} options are compatible with
-each other and also with @option{DEFAULT} and @option{STANDARD_INDENT}.
-@end itemize
-
-@noindent
-The @option{GNAT}, @option{COMPACT}, and @option{UNCOMPACT} options for the
-@option{/CONSTRUCT_LAYOUT} qualifier are incompatible.
+For the @option{/COMMENTS_LAYOUT} qualifier,
+The @option{GNAT_BEGINNING}, @option{REFORMAT}, and @option{DEFAULT}
+options are compatible with one another.
@end ifset
@node General Text Layout Control
@subsection Other Formatting Options
@noindent
-These switches control the inclusion of missing end/exit labels, and
-the indentation level in @b{case} statements, etc.
+These switches control other formatting not listed above.
@table @option
@item --decimal-grouping=@var{n}
example, with @code{--based-grouping=4}, @code{16#0001FFFE#} will be
changed to @code{16#0001_FFFE#}.
-@item ^-e^/NO_MISSED_LABELS^
-@cindex @option{^-e^/NO_MISSED_LABELS^} (@command{gnatpp})
-Do not insert missing end/exit labels. An end label is the name of
-a construct that may optionally be repeated at the end of the
-construct's declaration;
-e.g., the names of packages, subprograms, and tasks.
-An exit label is the name of a loop that may appear as target
-of an exit statement within the loop.
-By default, @command{gnatpp} inserts these end/exit labels when
-they are absent from the original source. This option suppresses such
-insertion, so that the formatted source reflects the original.
+@item ^--RM-style-spacing^/RM_STYLE_SPACING^
+@cindex @option{^--RM-style-spacing^/RM_STYLE_SPACING^} (@command{gnatpp})
+Do not insert an extra blank before various occurrences of
+`(' and `:'. This also turns off alignment.
@item ^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^
@cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp})
Insert a Form Feed character after a pragma Page.
-@item ^-T@var{nnn}^/MAX_INDENT=@var{nnn}^
-@cindex @option{^-T^/MAX_INDENT^} (@command{gnatpp})
-Do not use an additional indentation level for @b{case} alternatives
-and variants if there are @var{nnn} or more (the default
-value is 10).
-If @var{nnn} is 0, an additional indentation level is
-used for @b{case} alternatives and variants regardless of their number.
-
@item ^--call_threshold=@var{nnn}^/MAX_ACT=@var{nnn}^
@cindex @option{^--call_threshold^/MAX_ACT^} (@command{gnatpp})
If the number of parameter associations is greater than @var{nnn} and if at
least one association uses named notation, start each association from
a new line. If @var{nnn} is 0, no check for the number of associations
-is made, this is the default.
+is made; this is the default.
@item ^--par_threshold=@var{nnn}^/MAX_PAR=@var{nnn}^
@cindex @option{^--par_threshold^/MAX_PAR^} (@command{gnatpp})
@noindent
To define the search path for the input source file, @command{gnatpp}
-uses the same switches as the GNAT compiler, with the same effects.
+uses the same switches as the GNAT compiler, with the same effects:
@table @option
@item ^-I^/SEARCH=^@var{dir}
@cindex @option{^-I^/SEARCH^} (@command{gnatpp})
-The same as the corresponding gcc switch
@item ^-I-^/NOCURRENT_DIRECTORY^
@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatpp})
-The same as the corresponding gcc switch
@item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE^=@var{path}
@cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@command{gnatpp})
-The same as the corresponding gcc switch
@item ^--RTS^/RUNTIME_SYSTEM^=@var{path}
@cindex @option{^--RTS^/RUNTIME_SYSTEM^} (@command{gnatpp})
-The same as the corresponding gcc switch
@end table
@subsection Output File Control
@noindent
-By default the output is sent to the file whose name is obtained by appending
-the ^@file{.pp}^@file{$PP}^ suffix to the name of the input file
-(if the file with this name already exists, it is unconditionally overwritten).
+By default the output is sent to a file whose name is obtained by appending
+the ^@file{.pp}^@file{$PP}^ suffix to the name of the input file.
+If the file with this name already exists, it is overwritten.
Thus if the input file is @file{^my_ada_proc.adb^MY_ADA_PROC.ADB^} then
@command{gnatpp} will produce @file{^my_ada_proc.adb.pp^MY_ADA_PROC.ADB$PP^}
as output file.
@item ^--eol=@var{xxx}^/END_OF_LINE=@var{xxx}^
@cindex @option{^--eol^/END_OF_LINE^} (@code{gnatpp})
-Specifies the format of the reformatted output file. The @var{xxx}
-^string specified with the switch^option^ may be either
+Specifies the line-ending style of the reformatted output file. The @var{xxx}
+^string specified with the switch^option^ may be:
@itemize @bullet
@item ``@option{^dos^DOS^}'' MS DOS style, lines end with CR LF characters
@item ``@option{^crlf^CRLF^}''
-the same as @option{^crlf^CRLF^}
+the same as @option{^dos^DOS^}
@item ``@option{^unix^UNIX^}'' UNIX style, lines end with LF character
@item ``@option{^lf^LF^}''
the same as @option{^unix^UNIX^}
@item ^-W^/RESULT_ENCODING=^@var{e}
@cindex @option{^-W^/RESULT_ENCODING=^} (@command{gnatpp})
-Specify the wide character encoding method used to write the code in the
-result file
+Specify the wide character encoding method for the input and output files.
@var{e} is one of the following:
@itemize @bullet
@end table
@noindent
-Options @option{^-pipe^/STANDARD_OUTPUT^},
-@option{^-o^/OUTPUT^} and
+Options @option{^-o^/OUTPUT^} and
@option{^-of^/FORCED_OUTPUT^} are allowed only if the call to gnatpp
contains only one file to reformat.
Option
@table @option
@item --version
@cindex @option{--version} @command{gnatpp}
-Display Copyright and version, then exit disregarding all other options.
+Display copyright and version, then exit disregarding all other options.
@item --help
@cindex @option{--help} @command{gnatpp}
@cindex @option{-P} @command{gnatpp}
Indicates the name of the project file that describes the set of sources
to be processed. The exact set of argument sources depends on other options
-specified, see below.
+specified; see below.
@item -U
@cindex @option{-U} @command{gnatpp}
@item -X@var{name}=@var{value}
@cindex @option{-X} @command{gnatpp}
Indicates that external variable @var{name} in the argument project
-has the @var{value} value. Has no effect if no project is specified as
+has the value @var{value}. Has no effect if no project is specified as
tool argument.
@item --pp-off=@var{xxx}
Print out execution time.
@item ^-v^/VERBOSE^
-@cindex @option{^-v^/VERBOSE^} (@code{gnatpp})
-Verbose mode;
-@command{gnatpp} generates version information and then
-a trace of the actions it takes to produce or obtain the ASIS tree.
-
-@item ^-w^/WARNINGS^
-@cindex @option{^-w^/WARNINGS^} (@code{gnatpp})
-Warning mode;
-@command{gnatpp} generates a warning whenever it cannot provide
-a required layout in the result source.
+@cindex @option{^-v^/VERBOSE^} (@command{gnatpp})
+Verbose mode
+
+@item ^-q^/QUIET^
+@cindex @option{^-q^/QUIET^} (@command{gnatpp})
+Quiet mode
@end table
@noindent
@section Formatting Rules
@noindent
-The following subsections show how @command{gnatpp} treats ``white space'',
+The following subsections show how @command{gnatpp} treats white space,
comments, program layout, and name casing.
-They provide the detailed descriptions of the switches shown above.
+They provide detailed descriptions of the switches shown above.
@menu
* Disabling Pretty Printing::
* White Space and Empty Lines::
* Formatting Comments::
-* Construct Layout::
* Name Casing::
@end menu
@cartouche
package Interrupts is
--!pp off -- turn off pretty printing so "Interrupt_Kind" lines up
- type Interrupt_Kind is
+ type Interrupt_Kind is
(Asynchronous_Interrupt_Kind,
Synchronous_Interrupt_Kind,
Green_Interrupt_Kind);
@end cartouche
@end smallexample
-You can specify different comment strings using the gnatpp
-@code{--pp-off} and @code{--pp-on} switches. For example, if you say
-@code{gnatpp --pp-off=' pp-' *.ad?} then gnatpp will recognize
-comments of the form @code{-- pp-} instead of @code{--!pp off} for
-disabling pretty printing. Note that the leading @code{--} of the
-comment is not included in the argument to these switches.
+You can specify different comment strings using the @code{--pp-off}
+and @code{--pp-on} switches. For example, if you say @code{gnatpp
+--pp-off=' pp-' *.ad?} then gnatpp will recognize comments of the form
+@code{-- pp-} instead of @code{--!pp off} for disabling pretty
+printing. Note that the leading @code{--} of the comment is not
+included in the argument to these switches.
@node White Space and Empty Lines
@subsection White Space and Empty Lines
@command{gnatpp} does not have an option to control space characters.
It will add or remove spaces according to the style illustrated by the
examples in the @cite{Ada Reference Manual}.
-
-The only format effectors
-(see @cite{Ada Reference Manual}, paragraph 2.1(13))
-that will appear in the output file are platform-specific line breaks,
-and also format effectors within (but not at the end of) comments.
-In particular, each horizontal tab character that is not inside
-a comment will be treated as a space and thus will appear in the
-output file as zero or more spaces depending on
-the reformatting of the line in which it appears.
-The only exception is a Form Feed character, which is inserted after a
-pragma @code{Page} when @option{-ff} is set.
-
-The output file will contain no lines with trailing ``white space'' (spaces,
-format effectors).
-
-Empty lines in the original source are preserved
-only if they separate declarations or statements.
-In such contexts, a
-sequence of two or more empty lines is replaced by exactly one empty line.
-Note that a blank line will be removed if it separates two ``comment blocks''
-(a comment block is a sequence of whole-line comments).
-In order to preserve a visual separation between comment blocks, use an
-``empty comment'' (a line comprising only hyphens) rather than an empty line.
-Likewise, if for some reason you wish to have a sequence of empty lines,
-use a sequence of empty comments instead.
+The output file will contain no lines with trailing white space.
+
+By default, a sequence of one or more blank lines in the input is
+converted to a single blank line in the output; multiple blank lines
+are squeezed down to one.
+The @option{^--preserve-blank-lines^/PRESERVE_BLANK_LINES^} option
+turns off the squeezing; each blank line in the input is copied
+to the output.
+The @option{^--insert-blank-lines^/INSERT_BLANK_LINES^} option
+causes additional blank lines to be inserted if not already
+present in the input (e.g. between bodies).
@node Formatting Comments
@subsection Formatting Comments
@itemize @bullet
@item
a @emph{whole-line comment}, which appears by itself (possibly preceded by
-``white space'') on a line
+white space) on a line
@item
-an @emph{end-of-line comment}, which follows some other Ada lexical element
-on the same line.
+an @emph{end-of-line comment}, which follows some other Ada code on
+the same line.
@end itemize
@noindent
-The indentation of a whole-line comment is that of either
-the preceding or following line in
-the formatted source, depending on switch settings as will be described below.
-
-For an end-of-line comment, @command{gnatpp} leaves the same number of spaces
-between the end of the preceding Ada lexical element and the beginning
-of the comment as appear in the original source,
-unless either the comment has to be split to
-satisfy the line length limitation, or else the next line contains a
-whole line comment that is considered a continuation of this end-of-line
-comment (because it starts at the same position).
-In the latter two
-cases, the start of the end-of-line comment is moved right to the nearest
-multiple of the indentation level.
-This may result in a ``line overflow'' (the right-shifted comment extending
-beyond the maximum line length), in which case the comment is split as
-described below.
-
-There is a difference between @option{^-c1^/COMMENTS_LAYOUT=DEFAULT^}
-(GNAT-style comment line indentation)
-and @option{^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^}
-(reference-manual comment line indentation).
-With reference-manual style, a whole-line comment is indented as if it
-were a declaration or statement at the same place
-(i.e., according to the indentation of the preceding line(s)).
-With GNAT style, a whole-line comment that is immediately followed by an
-@b{if} or @b{case} statement alternative, a record variant, or the reserved
-word @b{begin}, is indented based on the construct that follows it.
-
-For example:
-@smallexample @c ada
-@cartouche
-if A then
- null;
- -- some comment
-else
- null;
-end if;
-@end cartouche
-@end smallexample
-
-@noindent
-Reference-manual indentation produces:
-
-@smallexample @c ada
-@cartouche
-if A then
- null;
- -- some comment
-else
- null;
-end if;
-@end cartouche
-@end smallexample
-
-@noindent
-while GNAT-style indentation produces:
+A whole-line comment is indented according to the surrounding code,
+with some exceptions.
+Comments that start in column 1 are kept there.
+If possible, comments are not moved so far to the right that the maximum
+line length is exceeded.
+The @option{^-c0^/COMMENTS_LAYOUT=UNTOUCHED^} option
+turns off comment formatting.
+Special-form comments such as SPARK-style @code{--#...} are left alone.
-@smallexample @c ada
-@cartouche
-if A then
- null;
--- some comment
-else
- null;
-end if;
-@end cartouche
-@end smallexample
+For an end-of-line comment, @command{gnatpp} tries to leave the same
+number of spaces between the end of the preceding Ada code and the
+beginning of the comment as appear in the original source.
@noindent
The @option{^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^} switch
@end itemize
@noindent
-For an end-of-line comment, if in the original source the next line is a
-whole-line comment that starts at the same position
-as the end-of-line comment,
-then the whole-line comment (and all whole-line comments
-that follow it and that start at the same position)
-will start at this position in the output file.
-
-@noindent
-That is, if in the original source we have:
-
-@smallexample @c ada
-@cartouche
-begin
-A := B + C; -- B must be in the range Low1..High1
- -- C must be in the range Low2..High2
- --B+C will be in the range Low1+Low2..High1+High2
-X := X + 1;
-@end cartouche
-@end smallexample
-
-@noindent
-Then in the formatted source we get
-
-@smallexample @c ada
-@cartouche
-begin
- A := B + C; -- B must be in the range Low1..High1
- -- C must be in the range Low2..High2
- -- B+C will be in the range Low1+Low2..High1+High2
- X := X + 1;
-@end cartouche
-@end smallexample
-
-@noindent
-A comment that exceeds the line length limit will be split.
-Unless switch
-@option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} (reformat comment blocks) is set and
-the line belongs to a reformattable block, splitting the line generates a
-@command{gnatpp} warning.
-The @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} switch specifies that whole-line
-comments may be reformatted in typical
-word processor style (that is, moving words between lines and putting as
-many words in a line as possible).
-
-@noindent
-The @option{^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^} switch specifies, that comments
-that has a special format (that is, a character that is neither a letter nor digit
-not white space nor line break immediately following the leading @code{--} of
-the comment) should be without any change moved from the argument source
-into reformatted source. This switch allows to preserve comments that are used
-as a special marks in the code (e.g.@: SPARK annotation).
+The @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} switch specifies that
+whole-line comments that form a paragraph will be filled in typical
+word processor style (that is, moving words between lines to make the
+lines other than the last similar in length ).
@noindent
The @option{--comments-only} switch specifies that only the comments
both. If @option{--comments-only} is given without @option{-c3} or
@option{-c4}, then gnatpp doesn't format anything.
-@node Construct Layout
-@subsection Construct Layout
-
-@noindent
-In several cases the suggested layout in the Ada Reference Manual includes
-an extra level of indentation that many programmers prefer to avoid. The
-affected cases include:
-
-@itemize @bullet
-
-@item Record type declaration (RM 3.8)
-
-@item Record representation clause (RM 13.5.1)
-
-@item Loop statement in case if a loop has a statement identifier (RM 5.6)
-
-@item Block statement in case if a block has a statement identifier (RM 5.6)
-@end itemize
-
-@noindent
-In compact mode (when GNAT style layout or compact layout is set),
-the pretty printer uses one level of indentation instead
-of two. This is achieved in the record definition and record representation
-clause cases by putting the @code{record} keyword on the same line as the
-start of the declaration or representation clause, and in the block and loop
-case by putting the block or loop header on the same line as the statement
-identifier.
-
-@noindent
-The difference between GNAT style @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^}
-and compact @option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^}
-layout on the one hand, and uncompact layout
-@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} on the other hand,
-can be illustrated by the following examples:
-
-@iftex
-@cartouche
-@multitable @columnfractions .5 .5
-@item @i{GNAT style, compact layout} @tab @i{Uncompact layout}
-
-@item
-@smallexample @c ada
-type q is record
- a : integer;
- b : integer;
-end record;
-@end smallexample
-@tab
-@smallexample @c ada
-type q is
- record
- a : integer;
- b : integer;
- end record;
-@end smallexample
-
-@item
-@smallexample @c ada
-for q use record
- a at 0 range 0 .. 31;
- b at 4 range 0 .. 31;
-end record;
-@end smallexample
-@tab
-@smallexample @c ada
-for q use
- record
- a at 0 range 0 .. 31;
- b at 4 range 0 .. 31;
- end record;
-@end smallexample
-
-@item
-@smallexample @c ada
-Block : declare
- A : Integer := 3;
-begin
- Proc (A, A);
-end Block;
-@end smallexample
-@tab
-@smallexample @c ada
-Block :
- declare
- A : Integer := 3;
- begin
- Proc (A, A);
- end Block;
-@end smallexample
-
-@item
-@smallexample @c ada
-Clear : for J in 1 .. 10 loop
- A (J) := 0;
-end loop Clear;
-@end smallexample
-@tab
-@smallexample @c ada
-Clear :
- for J in 1 .. 10 loop
- A (J) := 0;
- end loop Clear;
-@end smallexample
-@end multitable
-@end cartouche
-@end iftex
-
-@ifnottex
-@smallexample
-@cartouche
-GNAT style, compact layout Uncompact layout
-
-type q is record type q is
- a : integer; record
- b : integer; a : integer;
-end record; b : integer;
- end record;
-
-for q use record for q use
- a at 0 range 0 .. 31; record
- b at 4 range 0 .. 31; a at 0 range 0 .. 31;
-end record; b at 4 range 0 .. 31;
- end record;
-
-Block : declare Block :
- A : Integer := 3; declare
-begin A : Integer := 3;
- Proc (A, A); begin
-end Block; Proc (A, A);
- end Block;
-
-Clear : for J in 1 .. 10 loop Clear :
- A (J) := 0; for J in 1 .. 10 loop
-end loop Clear; A (J) := 0;
- end loop Clear;
-@end cartouche
-@end smallexample
-@end ifnottex
-
-@noindent
-A further difference between GNAT style layout and compact layout is that
-GNAT style layout inserts empty lines as separation for
-compound statements, return statements and bodies.
-
-Note that the layout specified by
-@option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^}
-for named block and loop statements overrides the layout defined by these
-constructs by @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^},
-@option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^} or
-@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} option.
-
@node Name Casing
@subsection Name Casing
had affected the
casing for the defining occurrence of the name.
+The options
+@option{^-a@var{x}^/ATTRIBUTE^},
+@option{^-k@var{x}^/KEYWORD_CASING^},
+@option{^-ne@var{x}^/ENUM_CASING^},
+@option{^-nt@var{x}^/TYPE_CASING^},
+@option{^-nn@var{x}^/NUMBER_CASING^}, and
+@option{^-p@var{x}^/PRAGMA_CASING^}
+allow finer-grained control over casing for
+attributes, keywords, enumeration literals,
+types, named numbers and pragmas, respectively.
+@option{^-nt@var{x}^/TYPE_CASING^} covers subtypes and
+task and protected bodies as well.
+
Some names may need to be spelled with casing conventions that are not
covered by the upper-, lower-, and mixed-case transformations.
You can arrange correct casing by placing such names in a
To handle the casing of Ada predefined names and the names from GNAT libraries,
@command{gnatpp} assumes a default dictionary file.
The name of each predefined entity is spelled with the same casing as is used
-for the entity in the @cite{Ada Reference Manual}.
+for the entity in the @cite{Ada Reference Manual} (usually mixed case).
The name of each entity in the GNAT libraries is spelled with the same casing
as is used in the declaration of that entity.
-The @w{@option{^-D-^/SPECIFIC_CASING^}} switch suppresses the use of the
-default dictionary file.
-Instead, the casing for predefined and GNAT-defined names will be established
-by the @option{^-n^/NAME_CASING^} switch or explicit dictionary files.
-For example, by default the names @code{Ada.Text_IO} and @code{GNAT.OS_Lib}
-will appear as just shown,
-even in the presence of a @option{^-nU^/NAME_CASING=UPPER_CASE^} switch.
-To ensure that even such names are rendered in uppercase,
-additionally supply the @w{@option{^-D-^/SPECIFIC_CASING^}} switch
-(or else, less conveniently, place these names in upper case in a dictionary
-file).
-
-A dictionary file is
-a plain text file; each line in this file can be either a blank line
-(containing only space characters and ASCII.HT characters), an Ada comment
+The @w{@option{^-D-^/SPECIFIC_CASING^}} switch suppresses the use of
+the default dictionary file. Instead, the casing for predefined and
+GNAT-defined names will be established by the
+@option{^-n^/NAME_CASING^} switch or explicit dictionary files. For
+example, by default the names @code{Ada.Text_IO} and
+@code{GNAT.OS_Lib} will appear as just shown, even in the presence of
+a @option{^-nU^/NAME_CASING=UPPER_CASE^} switch. To ensure that even
+such names are rendered in uppercase, additionally supply the
+@w{@option{^-D-^/SPECIFIC_CASING^}} switch (or else place these names
+in upper case in a dictionary file).
+
+A dictionary file is a plain text file; each line in this file can be
+either a blank line (containing only space characters), an Ada comment
line, or the specification of exactly one @emph{casing schema}.
A casing schema is a string that has the following syntax:
Otherwise this option has no effect.
-X@var{name}=@var{value} -- indicates that external variable @var{name} in
- the argument project has the @var{value} value. Has no effect if no
+ the argument project has the value @var{value}. Has no effect if no
project is specified as tool argument.
-mdir -- generate one .xml file for each Ada source file, in directory
@item -X@var{name}=@var{value}
@cindex @option{-X} @command{gnatmetric}
Indicates that external variable @var{name} in the argument project
-has the @var{value} value. Has no effect if no project is specified as
+has the value @var{value}. Has no effect if no project is specified as
tool argument.
@item --subdirs=@var{dir}
@item -X@var{name}=@var{value}
@cindex @option{-X} @command{gnatstub}
Indicates that external variable @var{name} in the argument project
-has the @var{value} value. Has no effect if no project is specified as
+has the value @var{value}. Has no effect if no project is specified as
tool argument.
@item ^-f^/FULL^
projects / gcc.git / commitdiff