Skip to content

R
riscv-gcc-1
Commit 1646b09f by Bob Duff Committed by Pierre-Marie de Rodat
Options

[Ada] Update gnatpp documentation after engine change 

2018-01-11  Bob Duff  <duff@adacore.com>

gcc/ada/

	* doc/gnat_ugn/gnat_utility_programs.rst: Rewrite gnatpp documentation
	to match what the Libadalang-based version does.
	* doc/gnat_ugn/about_this_guide.rst: Update reference.

From-SVN: r256500
parent 7460ccc7
Showing with 447 additions and 249 deletions
gcc/ada/ChangeLog
2018-01-11 Bob Duff <duff@adacore.com>
* doc/gnat_ugn/gnat_utility_programs.rst: Rewrite gnatpp documentation
to match what the Libadalang-based version does.
* doc/gnat_ugn/about_this_guide.rst: Update reference.
2018-01-11 Hristian Kirtchev <kirtchev@adacore.com>
* sem_res.adb (Uses_SS): A controlled type requires the secondary stack
......
gcc/ada/doc/gnat_ugn/about_this_guide.rst
......@@ -146,7 +146,7 @@ the new document structure.
- :ref:`The_Ada-to-XML_Converter_gnat2xml`
- :ref:`The_Coding_Standard_Verifier_gnatcheck`
- :ref:`The_GNAT_Metrics_Tool_gnatmetric`
- :ref:`The_GNAT_Pretty-Printer_gnatpp`
- :ref:`The_GNAT_Pretty_Printer_gnatpp`
- :ref:`The_Body_Stub_Generator_gnatstub`
- :ref:`The_Unit_Test_Generator_gnattest`
......
gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
......@@ -19,7 +19,7 @@ This chapter describes a number of utility programs:
* :ref:`The_Ada-to-XML_Converter_gnat2xml`
* :ref:`The_Coding_Standard_Verifier_gnatcheck`
* :ref:`The_GNAT_Metrics_Tool_gnatmetric`
* :ref:`The_GNAT_Pretty-Printer_gnatpp`
* :ref:`The_GNAT_Pretty_Printer_gnatpp`
* :ref:`The_Body_Stub_Generator_gnatstub`
* :ref:`The_Unit_Test_Generator_gnattest`
* :ref:`The_Backtrace_Symbolizer_gnatsymbolize`
......@@ -2798,42 +2798,36 @@ Alternatively, you may run the script using the following command line:
.. only:: PRO or GPL
.. _The_GNAT_Pretty-Printer_gnatpp:
.. _The_GNAT_Pretty_Printer_gnatpp:
The GNAT Pretty-Printer ``gnatpp``
The GNAT Pretty Printer ``gnatpp``
==================================
.. index:: ! gnatpp
.. index:: Pretty-Printer
.. index:: pretty printer
The ``gnatpp`` tool is an ASIS-based utility
for source reformatting / pretty-printing.
It takes an Ada source file as input and generates a reformatted
version as output.
You can specify various style directives via switches; e.g.,
identifier case conventions, rules of indentation, and comment layout.
This documentation is for the new libadalang-based version
of ``gnatpp``, which replaces the ASIS-based version.
The ``gnatpp`` tool is a utility for source reformatting / pretty
printing. It takes an Ada source file as input and generates a
reformatted version as output. You can specify various style
directives via switches; e.g., identifier case conventions, rules of
indentation, and comment layout.
``gnatpp`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches). The project file package that can specify
``gnatpp`` switches is named ``Pretty_Printer``.
To produce a reformatted file, ``gnatpp`` invokes the Ada
compiler and generates and uses the ASIS tree for the input source;
thus the input must be legal Ada code, and the tool should have all the
information needed to compile the input source. To provide this information,
you may specify as a tool parameter the project file the input source belongs to.
Another possibility is to specify the source search
path and needed configuration files in ``-cargs`` section of ``gnatpp``
call, see the description of the ``gnatpp`` switches below.
``gnatpp`` cannot process sources that contain preprocessing directives.
``gnatpp`` cannot process sources that contain preprocessing
directives.
The ``gnatpp`` command has the form
::
$ gnatpp [ switches ] filename [ -cargs gcc_switches ]
$ gnatpp [ switches ] filename
where
......@@ -2841,16 +2835,10 @@ Alternatively, you may run the script using the following command line:
the formatting rules, the source search path, and the destination for the
output source file
* ``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
follow the GNAT file naming rules
* ``gcc_switches`` is a list of switches for
``gcc``. They will be passed on to all compiler invocations made by
``gnatpp`` to generate the ASIS trees. Here you can provide
``-I`` switches to form the source search path,
use the ``-gnatec`` switch to set the configuration file, etc.
* ``filename`` is the name 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 follow
the GNAT file naming rules
.. _Switches_for_gnatpp:
......@@ -2892,15 +2880,15 @@ Alternatively, you may run the script using the following command line:
* ``at`` keywords in the component clauses in record representation clauses.
.. index:: -A0 (gnatpp)
.. index:: -A1 (gnatpp)
.. index:: --no-alignment (gnatpp)
.. index:: --alignment (gnatpp)
:switch:`-A0`
:switch:`--no-alignment`
Set alignment to OFF
:switch:`-A1`
:switch:`--alignment`
Set alignment to ON
.. _Casing_Control:
......@@ -2922,144 +2910,158 @@ Alternatively, you may run the script using the following command line:
following an underscore, are converted to their uppercase forms;
all the other letters are converted to their lowercase forms.
.. index:: -a (gnatpp)
(Note: the casing switches are not yet fully supported in the
libadalang-based version of gnatpp.)
.. index:: --name-case-as-declared (gnatpp)
:switch:`-aL`
Attribute designators are lower case
:switch:`-aU`
Attribute designators are upper case
:switch:`--name-case-as-declared`
Name casing for defining occurrences are as they appear in the source file
(this is the default)
:switch:`-aM`
Attribute designators are mixed case (this is the default)
.. index:: --name-upper-case (gnatpp)
.. index:: -k (gnatpp)
:switch:`--name-upper-case`
Names are in upper case
.. index:: --name-lower-case (gnatpp)
:switch:`-kL`
Keywords (technically, these are known in Ada as *reserved words*) are
lower case (this is the default)
:switch:`--name-lower-case`
Names are in lower case
.. index:: --name-mixed-case (gnatpp)
:switch:`-kU`
Keywords are upper case
:switch:`--name-mixed-case`
Names are in mixed case
.. index:: -n (gnatpp)
.. index:: --attribute-lower-case (gnatpp)
:switch:`--attribute-lower-case`
Attribute designators are lower case
:switch:`-nD`
Name casing for defining occurrences are as they appear in the source file
(this is the default)
.. index:: --attribute-upper-case (gnatpp)
:switch:`--attribute-upper-case`
Attribute designators are upper case
:switch:`-nU`
Names are in upper case
.. index:: --attribute-mixed-case (gnatpp)
:switch:`--attribute-mixed-case`
Attribute designators are mixed case (this is the default)
:switch:`-nL`
Names are in lower case
.. index:: --keyword-lower-case (gnatpp)
:switch:`--keyword-lower-case`
Keywords (technically, these are known in Ada as *reserved words*) are
lower case (this is the default)
:switch:`-nM`
Names are in mixed case
.. index:: --keyword-upper-case (gnatpp)
.. index:: -ne (gnatpp)
:switch:`--keyword-upper-case`
Keywords are upper case
.. index:: --enum-case-as-declared (gnatpp)
:switch:`-neD`
:switch:`--enum-case-as-declared`
Enumeration literal casing for defining occurrences are as they appear in the
source file. Overrides -n casing setting.
.. index:: --enum-upper-case (gnatpp)
:switch:`-neU`
:switch:`--enum-upper-case`
Enumeration literals are in upper case. Overrides -n casing
setting.
.. index:: --enum-lower-case (gnatpp)
:switch:`-neL`
:switch:`--enum-lower-case`
Enumeration literals are in lower case. Overrides -n casing
setting.
.. index:: --enum-mixed-case (gnatpp)
:switch:`-neM`
:switch:`--enum-mixed-case`
Enumeration literals are in mixed case. Overrides -n casing
setting.
.. index:: -nt (gnatpp)
.. index:: --type-case-as-declared (gnatpp)
:switch:`-ntD`
:switch:`--type-case-as-declared`
Names introduced by type and subtype declarations are always
cased as they appear in the declaration in the source file.
Overrides -n casing setting.
.. index:: --type-upper-case (gnatpp)
:switch:`-ntU`
:switch:`--type-upper-case`
Names introduced by type and subtype declarations are always in
upper case. Overrides -n casing setting.
.. index:: --type-lower-case (gnatpp)
:switch:`-ntL`
:switch:`--type-lower-case`
Names introduced by type and subtype declarations are always in
lower case. Overrides -n casing setting.
.. index:: --type-mixed-case (gnatpp)
:switch:`-ntM`
:switch:`--type-mixed-case`
Names introduced by type and subtype declarations are always in
mixed case. Overrides -n casing setting.
.. index:: --number-upper-case (gnatpp)
:switch:`-nnU`
:switch:`--number-upper-case`
Names introduced by number declarations are always in
upper case. Overrides -n casing setting.
.. index:: --number-lower-case (gnatpp)
:switch:`-nnL`
:switch:`--number-lower-case`
Names introduced by number declarations are always in
lower case. Overrides -n casing setting.
.. index:: --number-mixed-case (gnatpp)
:switch:`-nnM`
:switch:`--number-mixed-case`
Names introduced by number declarations are always in
mixed case. Overrides -n casing setting.
.. index:: -p (gnatpp)
.. index:: --pragma-lower-case (gnatpp)
:switch:`-pL`
:switch:`--pragma-lower-case`
Pragma names are lower case
.. index:: --pragma-upper-case (gnatpp)
:switch:`-pU`
:switch:`--pragma-upper-case`
Pragma names are upper case
.. index:: --pragma-mixed-case (gnatpp)
:switch:`-pM`
:switch:`--pragma-mixed-case`
Pragma names are mixed case (this is the default)
.. index:: -D (gnatpp)
.. index:: --dictionary (gnatpp)
:switch:`-D{file}`
:switch:`--dictionary={file}`
Use ``file`` as a *dictionary file* that defines
the casing for a set of specified names,
thereby overriding the effect on these names by
any explicit or implicit
-n switch.
To supply more than one dictionary file,
use several ``-D`` switches.
use several ``--dictionary`` switches.
``gnatpp`` implicitly uses a *default dictionary file*
to define the casing for the Ada predefined names and
the names declared in the GNAT libraries.
.. index:: -D- (gnatpp)
.. index:: --dictionary=- (gnatpp)
:switch:`-D-`
:switch:`--dictionary=-`
Do not use the default dictionary file;
instead, use the casing
defined by a ``-n`` switch and any explicit
......@@ -3068,8 +3070,8 @@ Alternatively, you may run the script using the following command line:
The structure of a dictionary file, and details on the conventions
used in the default dictionary file, are defined in :ref:`Name_Casing`.
The :switch:`-D-` and
:switch:`-D{file}` switches are mutually
The :switch:`--dictionary=-` and
:switch:`--dictionary={file}` switches are mutually
compatible.
This group of ``gnatpp`` switches controls the layout of comments and
......@@ -3080,24 +3082,24 @@ Alternatively, you may run the script using the following command line:
.. index:: -c (gnatpp)
:switch:`-c0`
:switch:`--comments-unchanged`
All comments remain unchanged.
:switch:`-c1`
:switch:`--comments-gnat-indentation`
GNAT-style comment line indentation.
This is the default.
:switch:`-c3`
:switch:`--comments-gnat-beginning`
GNAT-style comment beginning.
:switch:`-c4`
:switch:`--comments-fill`
Fill comment blocks.
:switch:`-c5`
:switch:`--comments-special`
Keep unchanged special form comments.
This is the default.
......@@ -3142,6 +3144,7 @@ Alternatively, you may run the script using the following command line:
:switch:`--use-on-new-line`
Start each USE clause in a context clause from a separate line.
.. index:: --insert-blank-lines (gnatpp)
......@@ -3156,10 +3159,14 @@ Alternatively, you may run the script using the following command line:
Preserve blank lines in the input. By default, gnatpp will squeeze
multiple blank lines down to one.
.. index:: --preserve-line-breaks (gnatpp)
:switch:`--preserve-line-breaks`
Preserve line breaks in the input, to the extent possible.
The ``-c`` switches are compatible with one another, except that
the ``-c0`` switch disables all other comment formatting
switches.
The ``--comments`` switches are compatible with one another, except
that the ``--comments-unchanged`` switch disables all other comment
formatting switches.
.. _General_Text_Layout_Control:
......@@ -3169,21 +3176,21 @@ Alternatively, you may run the script using the following command line:
These switches allow control over line length and indentation.
.. index:: -M (gnatpp)
.. index:: --max-line-length (gnatpp)
:switch:`-M{nnn}`
:switch:`--max-line-length={nnn}`
Maximum line length, ``nnn`` from 32...256, the default value is 79
.. index:: -i (gnatpp)
.. index:: --indentation (gnatpp)
:switch:`-i{nnn}`
:switch:`--indentation={nnn}`
Indentation level, ``nnn`` from 1...9, the default value is 3
.. index:: -cl (gnatpp)
.. index:: --indent-continuation (gnatpp)
:switch:`-cl{nnn}`
:switch:`--indent-continuation={nnn}`
Indentation level for continuation lines (relative to the line being
continued), ``nnn`` from 1...9.
The default
......@@ -3232,9 +3239,9 @@ Alternatively, you may run the script using the following command line:
'(' and ':'. This also turns off alignment.
.. index:: -ff (gnatpp)
.. index:: --ff-after-pragma-page (gnatpp)
:switch:`-ff`
:switch:`--ff-after-pragma-page`
Insert a Form Feed character after a pragma Page.
......@@ -3255,6 +3262,32 @@ Alternatively, you may run the script using the following command line:
a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not specified, then
the ``is`` is placed on a separate line. This feature is disabled by default.
.. index:: --vertical-enum-types (gnatpp)
:switch:`--vertical-enum-types`
Format enumeration type declarations "vertically", e.g. each
enumeration literal goes on a separate line.
.. index:: --vertical-array-types (gnatpp)
:switch:`--vertical-array-types`
Format array type declarations "vertically", e.g. for
multidimensional arrays, each index_subtype_definition or
discrete_subtype_definition goes on a separate line.
.. index:: --vertical-named-aggregates (gnatpp)
:switch:`--vertical-named-aggregates`
Format aggregates "vertically" if named notation is used for all
component_associations, e.g. each component_association
goes on a separate line.
.. index:: --vertical-case-alternatives (gnatpp)
:switch:`--vertical-case-alternatives`
Format case statements, case expressions, and variant parts with
additional line breaks.
.. _Setting_the_Source_Search_Path:
......@@ -3283,48 +3316,52 @@ Alternatively, you may run the script using the following command line:
Output File Control
^^^^^^^^^^^^^^^^^^^
By default the output is sent to a file whose name is obtained by appending
the :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` then
``gnatpp`` will produce :file:`my_ada_proc.adb.pp`
as output file.
By default the output overwrites the input file.
The output may be redirected by the following switches:
.. index:: --replace (gnatpp)
:switch:`--replace`
This is the default.
Replace the input source file with the reformatted output without
creating any backup copy of the input source.
.. index:: --output-dir (gnatpp)
:switch:`--output-dir={dir}`
Generate output file in directory :file:`dir` with the same name as the input
file. If :file:`dir` is the same as the directory containing the input file,
the input file is not processed; use ``-rnb``
if you want to update the input file in place.
Generate output file in directory :file:`dir` with the same name as
the input file. If :file:`dir` is the same as the directory
containing the input file, the input file is not processed; use
``--replace`` if you want to update the input file in
place.
.. index:: -pipe (gnatpp)
.. index:: --pipe (gnatpp)
:switch:`-pipe`
:switch:`--pipe`
Send the output to ``Standard_Output``
.. index:: -o (gnatpp)
.. index:: --output (gnatpp)
:switch:`-o {output_file}`
:switch:`--output={output_file}`
Write the output into ``output_file``.
If ``output_file`` already exists, ``gnatpp`` terminates without
reading or processing the input file.
.. index:: -of (gnatpp)
.. index:: --output-force (gnatpp)
:switch:`-of {output_file}`
:switch:`--output-force={output_file}`
Write the output into ``output_file``, overwriting the existing file
(if one is present).
.. index:: -r (gnatpp)
.. index:: --replace-backup (gnatpp)
:switch:`-r`
:switch:`--replace-backup`
Replace the input source file with the reformatted output, and copy the
original input source into the file whose name is obtained by appending the
:file:`.npp` suffix to the name of the input file.
......@@ -3332,54 +3369,39 @@ Alternatively, you may run the script using the following command line:
reading or processing the input file.
.. index:: -rf (gnatpp)
.. index:: --replace-force-backup (gnatpp)
:switch:`-rf`
Like ``-r`` except that if the file with the specified name
:switch:`--replace-force-backup`
Like ``--replace-backup`` except that if the file with the specified name
already exists, it is overwritten.
.. index:: -rnb (gnatpp)
.. index:: --end-of-line (gnatpp)
:switch:`-rnb`
Replace the input source file with the reformatted output without
creating any backup copy of the input source.
.. index:: --eol (gnatpp)
:switch:`--eol={xxx}`
Specifies the line-ending style of the reformatted output file. The ``xxx``
string specified with the switch may be:
:switch:`--end-of-line={xxx}`
Specifies the line-ending style of the reformatted output file. The
``xxx`` string specified with the switch may be:
* *dos* - MS DOS style, lines end with CR LF characters*
* *crlf* - the same as *dos*
* *unix* - UNIX style, lines end with LF character*
* *lf* - the same as *unix*
.. index:: -W (gnatpp)
.. index:: --wide-character-encoding (gnatpp)
:switch:`-W{e}`
Specify the wide character encoding method for the input and output files.
``e`` is one of the following:
* *h* - Hex encoding
* *u* - Upper half encoding
* *s* - Shift/JIS encoding
* *e* - EUC encoding
:switch:`--wide-character-encoding={e}`
Specify the wide character encoding method for the input and output
files. ``e`` is one of the following:
* *8* - UTF-8 encoding
* *b* - Brackets encoding (default value)
Options ``-o`` and ``-of`` are allowed only if the call to gnatpp
contains only one file to reformat.
Options ``--output-file`` and ``--output-force`` are allowed only if
the call to gnatpp contains only one file to reformat.
Option ``--eol`` and ``-W`` cannot be used together
with the ``-pipe`` option.
Option ``--end-of-line`` and ``--wide-character-encoding`` cannot be used together
with the ``--pipe`` option.
.. _Other_gnatpp_Switches:
......@@ -3414,14 +3436,14 @@ Alternatively, you may run the script using the following command line:
:switch:`-U`
If a project file is specified and no argument source is explicitly
specified (either directly or by means of ``-files`` option), process
specified (either directly or by means of ``--files`` option), process
all the units of the closure of the argument project. Otherwise this option
has no effect.
:switch:`-U {main_unit}`
If a project file is specified and no argument source is explicitly
specified (either directly or by means of ``-files`` option), process
specified (either directly or by means of ``--files`` option), process
the closure of units rooted at ``main_unit``. Otherwise this option
has no effect.
......@@ -3450,6 +3472,8 @@ Alternatively, you may run the script using the following command line:
compiles files that need to be recompiled. A project file is required
in this mode, and the gnat driver (as in *gnat pretty*) is not
supported.
(Note: this switch is not yet supported in the libadalang-based
version of gnatpp.)
.. index:: --pp-off (gnatpp)
......@@ -3466,9 +3490,9 @@ Alternatively, you may run the script using the following command line:
of the default ``--!pp on``.
.. index:: -files (gnatpp)
.. index:: --files (gnatpp)
:switch:`-files {filename}`
:switch:`--files={filename}`
Take as arguments the files listed in text file ``file``.
Text file ``file`` may contain empty lines that are ignored.
Each nonempty line should contain the name of an existing file.
......@@ -3481,44 +3505,27 @@ Alternatively, you may run the script using the following command line:
Do not process the sources listed in a specified file. This option cannot
be used in incremental mode.
.. index:: -j (gnatpp)
.. index:: --jobs (gnatpp)
:switch:`-j{n}`
Without ``--incremental``, use *n* processes to carry out the
tree creations (internal representations of the argument sources). On
a multiprocessor machine this speeds up processing of big sets of
argument sources. If *n* is 0, then the maximum number of parallel
tree creations is the number of core processors on the platform. This
option cannot be used together with the :switch:`-r`,
:switch:`-rf` or
:switch:`-rnb` options.
:switch:`--jobs={n}`
With ``--incremental``, use *n* ``gnatpp`` processes to perform
pretty printing in parallel. If *n* is 0, then the maximum number
processes is the number of core processors on the platform.
With ``--incremental``, use *n* ``gnatpp`` processes to
perform pretty-printing in parallel. *n* = 0 means the same as
above. In this case, the :switch:`-r`,
:switch:`-rf` and
:switch:`-rnb` options are allowed.
.. index:: -t (gnatpp)
.. index:: --verbose (gnatpp)
:switch:`-t`
Print out execution time.
.. index:: -v (gnatpp)
:switch:`-v`
:switch:`--verbose`
Verbose mode
.. index:: -q (gnatpp)
.. index:: --quiet (gnatpp)
:switch:`-q`
:switch:`--quiet`
Quiet mode
If a project file is specified and no argument source is explicitly
specified (either directly or by means of ``-files`` option), and no
specified (either directly or by means of ``--files`` option), and no
``-U`` is specified, then the set of processed sources is
all the immediate units of the argument project.
......@@ -3612,42 +3619,40 @@ Alternatively, you may run the script using the following command line:
the same line.
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 ``-c0`` option
turns off comment formatting.
Special-form comments such as SPARK-style ``--#...`` are left alone.
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 ``--comments-unchanged``
option turns off comment formatting. Special-form comments such as
SPARK-style ``--#...`` are left alone.
For an end-of-line comment, ``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.
The ``-c3`` switch
(GNAT style comment beginning) has the following
effect:
The ``--comments-gnat-beginning`` switch (GNAT style comment
beginning) has the following effect:
* For each whole-line comment that does not end with two hyphens,
``gnatpp`` inserts spaces if necessary after the starting two hyphens
to ensure that there are at least two spaces between these hyphens and the
first non-blank character of the comment.
The ``-c4`` 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 ).
The ``--comments-only`` switch specifies that only the comments
are formatted; the rest of the program text is left alone. The
comments are formatted according to the -c3 and -c4 switches; other
formatting switches are ignored. For example,
``--comments-only -c4`` means to fill comment paragraphs, and do nothing else.
Likewise,
``--comments-only -c3`` ensures comments start with at least two
spaces after ``--``, and ``--comments-only -c3 -c4`` does
both. If ``--comments-only`` is given without ``-c3`` or
``-c4``, then gnatpp doesn't format anything.
``gnatpp`` inserts spaces if necessary after the starting two
hyphens to ensure that there are at least two spaces between
these hyphens and the first non-blank character of the comment.
The ``--comments-fill`` 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 ).
The ``--comments-only`` switch specifies that only the comments are
formatted; the rest of the program text is left alone. The comments
are formatted according to the ``--comments-gnat-beginning`` and
``--comments-fill`` switches; other formatting switches are ignored. For
example, ``--comments-only --comments-fill`` means to fill comment
paragraphs, and do nothing else. Likewise, ``--comments-only
--comments-gnat-beginning`` ensures comments start with at least two
spaces after ``--``, and ``--comments-only --comments-gnat-beginning
--comments-fill`` does both. If ``--comments-only`` is given without
``--comments-gnat-beginning`` or ``--comments-fill``, then gnatpp
doesn't format anything.
.. _Name_Casing:
......@@ -3658,49 +3663,42 @@ Alternatively, you may run the script using the following command line:
``gnatpp`` always converts the usage occurrence of a (simple) name to
the same casing as the corresponding defining identifier.
You control the casing for defining occurrences via the
``-n`` switch.
With ``-nD`` ('as declared', which is the default),
defining occurrences appear exactly as in the source file
where they are declared.
The other values for this switch --
``-nU``,
``-nL``,
``-nM`` --
result in
upper, lower, or mixed case, respectively.
If ``gnatpp`` changes the casing of a defining
occurrence, it analogously changes the casing of all the
usage occurrences of this name.
If the defining occurrence of a name is not in the source compilation unit
currently being processed by ``gnatpp``, the casing of each reference to
this name is changed according to the value of the ``-n``
switch (subject to the dictionary file mechanism described below).
Thus ``gnatpp`` acts as though the ``-n`` switch
had affected the
casing for the defining occurrence of the name.
You control the casing for defining occurrences via the ``--name...``
switches. With ``--name-case-as-declared``, which is the default,
defining occurrences appear exactly as in the source file where they
are declared. The other values for this switch --
``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case``
-- result in upper, lower, or mixed case, respectively. If
``gnatpp`` changes the casing of a defining occurrence, it
analogously changes the casing of all the usage occurrences of this
name.
If the defining occurrence of a name is not in the source compilation
unit currently being processed by ``gnatpp``, the casing of each
reference to this name is changed according to the switch (subject to
the dictionary file mechanism described below). Thus ``gnatpp`` acts
as though the switch had affected the casing for the defining
occurrence of the name.
The options
:switch:`-a{x}`,
:switch:`-k{x}`,
:switch:`-ne{x}`,
:switch:`-nt{x}`,
:switch:`-nn{x}`, and
:switch:`-p{x}`
:switch:`--attribute...`,
:switch:`--keyword...`,
:switch:`--enum...`,
:switch:`--type...`,
:switch:`--number...`, and
:switch:`--pragma...`
allow finer-grained control over casing for
attributes, keywords, enumeration literals,
types, named numbers and pragmas, respectively.
:switch:`-nt{x}` covers subtypes and
task and protected bodies as well.
:switch:`--type...` cover subtypes 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
*dictionary file*,
and then supplying a ``-D`` switch.
and then supplying a ``--dictionary`` switch.
The casing of names from dictionary files overrides
any ``-n`` switch.
any ``--name...`` switch.
To handle the casing of Ada predefined names and the names from GNAT libraries,
``gnatpp`` assumes a default dictionary file.
......@@ -3709,15 +3707,15 @@ Alternatively, you may run the script using the following command line:
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 ``-D-`` switch suppresses the use of
The ``--dictionary=-`` switch suppresses the use of
the default dictionary file. Instead, the casing for predefined and
GNAT-defined names will be established by the
``-n`` switch or explicit dictionary files. For
example, by default the names ``Ada.Text_IO`` and
``GNAT.OS_Lib`` will appear as just shown, even in the presence of
a ``-nU`` switch. To ensure that even
a ``--name-upper-case`` switch. To ensure that even
such names are rendered in uppercase, additionally supply the
-D- switch (or else place these names
--dictionary=- 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
......@@ -3740,7 +3738,7 @@ Alternatively, you may run the script using the following command line:
comment; any amount of white space is allowed before the string.
If a dictionary file is passed as
the value of a :switch:`-D{file}` switch
the value of a :switch:`--dictionary={file}` switch
then for every
simple name and every identifier, ``gnatpp`` checks if the dictionary
defines the casing for the name or for some of its parts (the term 'subword'
......@@ -3796,7 +3794,7 @@ Alternatively, you may run the script using the following command line:
::
$ gnatpp -nM -D dict1 -D dict2 test.adb
$ gnatpp --name-mixed-case --dictionary=dict1 --dictionary=dict2 test.adb
then we will get the following name casing in the ``gnatpp`` output:
......@@ -3812,6 +3810,200 @@ Alternatively, you may run the script using the following command line:
Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
end Test;
Legacy Switches
^^^^^^^^^^^^^^^
Some switches have a short form, mostly for legacy reasons,
as shown below.
.. index:: -n (gnatpp)
:switch:`-nD`
:switch:`--name-case-as-declared`
:switch:`-nU`
:switch:`--name-upper-case`
:switch:`-nL`
:switch:`--name-lower-case`
:switch:`-nM`
:switch:`--name-mixed-case`
.. index:: -a (gnatpp)
:switch:`-aL`
:switch:`--attribute-lower-case`
:switch:`-aU`
:switch:`--attribute-upper-case`
:switch:`-aM`
:switch:`--attribute-mixed-case`
.. index:: -k (gnatpp)
:switch:`-kL`
:switch:`--keyword-lower-case`
:switch:`-kU`
:switch:`--keyword-upper-case`
.. index:: -ne (gnatpp)
:switch:`-neD`
:switch:`--enum-case-as-declared`
:switch:`-neU`
:switch:`--enum-upper-case`
:switch:`-neL`
:switch:`--enum-lower-case`
:switch:`-neM`
:switch:`--enum-mixed-case`
.. index:: -nt (gnatpp)
:switch:`-ntD`
:switch:`--type-case-as-declared`
:switch:`-ntU`
:switch:`--type-upper-case`
:switch:`-ntL`
:switch:`--type-lower-case`
:switch:`-ntM`
:switch:`--type-mixed-case`
:switch:`-nnU`
:switch:`--number-upper-case`
:switch:`-nnL`
:switch:`--number-lower-case`
:switch:`-nnM`
:switch:`--number-mixed-case`
.. index:: -p (gnatpp)
:switch:`-pL`
:switch:`--pragma-lower-case`
:switch:`-pU`
:switch:`--pragma-upper-case`
:switch:`-pM`
:switch:`--pragma-mixed-case`
.. index:: -D (gnatpp)
:switch:`-D{file}`
:switch:`--dictionary={file}`
.. index:: -D- (gnatpp)
:switch:`-D-`
:switch:`--dictionary=-`
.. index:: -c (gnatpp)
:switch:`-c0`
:switch:`--comments-unchanged`
:switch:`-c1`
:switch:`--comments-gnat-indentation`
:switch:`-c3`
:switch:`--comments-gnat-beginning`
:switch:`-c4`
:switch:`--comments-fill`
:switch:`-c5`
:switch:`--comments-special`
.. index:: -M (gnatpp)
:switch:`-M{nnn}`
:switch:`--max-line-length={nnn}`
.. index:: -i (gnatpp)
:switch:`-i{nnn}`
:switch:`--indentation={nnn}`
.. index:: -cl (gnatpp)
:switch:`-cl{nnn}`
:switch:`--indent-continuation={nnn}`
.. index:: -ff (gnatpp)
:switch:`-ff`
:switch:`--ff-after-pragma-page`
.. index:: -pipe (gnatpp)
:switch:`-pipe`
:switch:`--pipe`
.. index:: -o (gnatpp)
:switch:`-o {output-file}`
:switch:`--output={output-file}`
.. index:: -of (gnatpp)
:switch:`-of {output-file}`
:switch:`--output-force={output-file}`
.. index:: -r (gnatpp)
:switch:`-rnb`
:switch:`--replace`
:switch:`-r`
:switch:`--replace-backup`
.. index:: -rf (gnatpp)
:switch:`-rf`
:switch:`--replace-force-backup`
.. index:: -rnb (gnatpp)
.. index:: --eol (gnatpp)
:switch:`--eol={xxx}`
:switch:`--end-of-line={xxx}`
.. index:: -W (gnatpp)
:switch:`-W{e}`
:switch:`--wide-character-encoding={e}`
.. index:: -files (gnatpp)
:switch:`-files {filename}`
:switch:`--files={filename}`
.. index:: -j (gnatpp)
:switch:`-j{n}`
:switch:`--jobs={n}`
.. index:: -v (gnatpp)
:switch:`-v`
:switch:`--verbose`
.. index:: -q (gnatpp)
:switch:`-q`
:switch:`--quiet`
.. only:: PRO or GPL
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment