diff options
Diffstat (limited to 'gcc/ada/gnat_ugn.texi')
| -rw-r--r-- | gcc/ada/gnat_ugn.texi | 633 |
1 files changed, 131 insertions, 502 deletions
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index a57715a8a26..6fc86ab524a 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -11319,7 +11319,7 @@ to be processed. @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} @@ -14076,25 +14076,23 @@ is now available. 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 @@ -14114,18 +14112,16 @@ output source file @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 @@ -14149,10 +14145,6 @@ You may supply several such switches to @command{gnatpp}, but then 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 @@ -14162,21 +14154,11 @@ word may have exactly one option, which specifies either upper case, lower 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:: @@ -14190,44 +14172,22 @@ indicate the effect. @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} @@ -14240,10 +14200,6 @@ general rule for name casing but also override this rule 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. @@ -14369,10 +14325,6 @@ The @option{^-D-^/SPECIFIC_CASING^} and @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 @@ -14381,53 +14333,31 @@ on their effect. @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 @@ -14443,11 +14373,6 @@ incompatible with @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} option. @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 @@ -14462,28 +14387,16 @@ multiple blank lines down to one. @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 @@ -14515,8 +14428,7 @@ line indentation is also 1) @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} @@ -14533,36 +14445,21 @@ Same as @code{--decimal-grouping}, but for based literals. For 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}) @@ -14576,24 +14473,20 @@ a new line. The default for @var{nnn} is 3. @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 @@ -14601,9 +14494,9 @@ The same as the corresponding gcc switch @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. @@ -14645,12 +14538,12 @@ creating any backup copy of the input source. @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^} @@ -14658,8 +14551,7 @@ 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 @@ -14686,8 +14578,7 @@ Brackets encoding (default value) @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 @@ -14706,7 +14597,7 @@ The additional @command{gnatpp} switches are defined in this subsection. @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} @@ -14716,7 +14607,7 @@ Display usage, then exit disregarding all other options. @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} @@ -14734,7 +14625,7 @@ has no effect. @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} @@ -14774,16 +14665,12 @@ This option cannot be used together with @option{^-r^/REPLACE^}, 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 @@ -14797,15 +14684,14 @@ all the immediate units of the argument project. @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 @@ -14832,7 +14718,7 @@ be followed by arbitrary additional text. For example: @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); @@ -14842,12 +14728,12 @@ package Interrupts is @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 @@ -14856,31 +14742,17 @@ comment is not included in the argument to these switches. @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 @@ -14890,82 +14762,26 @@ Comments in Ada code are of two kinds: @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 @@ -14981,57 +14797,10 @@ first non-blank character of the comment. @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 @@ -15044,157 +14813,6 @@ spaces after @code{--}, and @option{--comments-only -c3 -c4} does 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 @@ -15230,6 +14848,19 @@ Thus @command{gnatpp} acts as though the @option{^-n^/NAME_CASING^} switch 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 @@ -15241,25 +14872,23 @@ any @option{^-n^/NAME_CASING^} switch. 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: @@ -15435,7 +15064,7 @@ Options: 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 @@ -16817,7 +16446,7 @@ has no effect. @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} @@ -19712,7 +19341,7 @@ to be processed. @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^ |