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> 2018-01-11 Hristian Kirtchev <kirtchev@adacore.com>
* sem_res.adb (Uses_SS): A controlled type requires the secondary stack * 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. ...@@ -146,7 +146,7 @@ the new document structure.
- :ref:`The_Ada-to-XML_Converter_gnat2xml` - :ref:`The_Ada-to-XML_Converter_gnat2xml`
- :ref:`The_Coding_Standard_Verifier_gnatcheck` - :ref:`The_Coding_Standard_Verifier_gnatcheck`
- :ref:`The_GNAT_Metrics_Tool_gnatmetric` - :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_Body_Stub_Generator_gnatstub`
- :ref:`The_Unit_Test_Generator_gnattest` - :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: ...@@ -19,7 +19,7 @@ This chapter describes a number of utility programs:
* :ref:`The_Ada-to-XML_Converter_gnat2xml` * :ref:`The_Ada-to-XML_Converter_gnat2xml`
* :ref:`The_Coding_Standard_Verifier_gnatcheck` * :ref:`The_Coding_Standard_Verifier_gnatcheck`
* :ref:`The_GNAT_Metrics_Tool_gnatmetric` * :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_Body_Stub_Generator_gnatstub`
* :ref:`The_Unit_Test_Generator_gnattest` * :ref:`The_Unit_Test_Generator_gnattest`
* :ref:`The_Backtrace_Symbolizer_gnatsymbolize` * :ref:`The_Backtrace_Symbolizer_gnatsymbolize`
...@@ -2798,42 +2798,36 @@ Alternatively, you may run the script using the following command line: ...@@ -2798,42 +2798,36 @@ Alternatively, you may run the script using the following command line:
.. only:: PRO or GPL .. 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:: ! gnatpp
.. index:: Pretty-Printer .. index:: pretty printer
The ``gnatpp`` tool is an ASIS-based utility This documentation is for the new libadalang-based version
for source reformatting / pretty-printing. of ``gnatpp``, which replaces the ASIS-based version.
It takes an Ada source file as input and generates a reformatted
version as output. The ``gnatpp`` tool is a utility for source reformatting / pretty
You can specify various style directives via switches; e.g., printing. It takes an Ada source file as input and generates a
identifier case conventions, rules of indentation, and comment layout. 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 ``gnatpp`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches). The project file package that can specify the project-related switches). The project file package that can specify
``gnatpp`` switches is named ``Pretty_Printer``. ``gnatpp`` switches is named ``Pretty_Printer``.
To produce a reformatted file, ``gnatpp`` invokes the Ada ``gnatpp`` cannot process sources that contain preprocessing
compiler and generates and uses the ASIS tree for the input source; directives.
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.
The ``gnatpp`` command has the form The ``gnatpp`` command has the form
:: ::
$ gnatpp [ switches ] filename [ -cargs gcc_switches ] $ gnatpp [ switches ] filename
where where
...@@ -2841,16 +2835,10 @@ Alternatively, you may run the script using the following command line: ...@@ -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 the formatting rules, the source search path, and the destination for the
output source file output source file
* ``filename`` is the name (including the extension) of the source file to * ``filename`` is the name of the source file to reformat; wildcards
reformat; wildcards or several file names on the same gnatpp command are or several file names on the same gnatpp command are allowed. The
allowed. The file name may contain path information; it does not have to file name may contain path information; it does not have to follow
follow the GNAT file naming rules 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.
.. _Switches_for_gnatpp: .. _Switches_for_gnatpp:
...@@ -2892,15 +2880,15 @@ Alternatively, you may run the script using the following command line: ...@@ -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. * ``at`` keywords in the component clauses in record representation clauses.
.. index:: -A0 (gnatpp) .. index:: --no-alignment (gnatpp)
.. index:: -A1 (gnatpp) .. index:: --alignment (gnatpp)
:switch:`-A0` :switch:`--no-alignment`
Set alignment to OFF Set alignment to OFF
:switch:`-A1` :switch:`--alignment`
Set alignment to ON Set alignment to ON
.. _Casing_Control: .. _Casing_Control:
...@@ -2922,144 +2910,158 @@ Alternatively, you may run the script using the following command line: ...@@ -2922,144 +2910,158 @@ Alternatively, you may run the script using the following command line:
following an underscore, are converted to their uppercase forms; following an underscore, are converted to their uppercase forms;
all the other letters are converted to their lowercase 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` :switch:`--name-case-as-declared`
Attribute designators are lower case Name casing for defining occurrences are as they appear in the source file
(this is the default)
:switch:`-aU`
Attribute designators are upper case
:switch:`-aM` .. index:: --name-upper-case (gnatpp)
Attribute designators are mixed case (this is the default)
.. index:: -k (gnatpp) :switch:`--name-upper-case`
Names are in upper case
.. index:: --name-lower-case (gnatpp)
:switch:`-kL` :switch:`--name-lower-case`
Keywords (technically, these are known in Ada as *reserved words*) are Names are in lower case
lower case (this is the default)
.. index:: --name-mixed-case (gnatpp)
:switch:`-kU` :switch:`--name-mixed-case`
Keywords are upper 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` .. index:: --attribute-upper-case (gnatpp)
Name casing for defining occurrences are as they appear in the source file
(this is the default)
:switch:`--attribute-upper-case`
Attribute designators are upper case
:switch:`-nU` .. index:: --attribute-mixed-case (gnatpp)
Names are in upper case
:switch:`--attribute-mixed-case`
Attribute designators are mixed case (this is the default)
:switch:`-nL` .. index:: --keyword-lower-case (gnatpp)
Names are in lower case
:switch:`--keyword-lower-case`
Keywords (technically, these are known in Ada as *reserved words*) are
lower case (this is the default)
:switch:`-nM` .. index:: --keyword-upper-case (gnatpp)
Names are in mixed case
.. 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 Enumeration literal casing for defining occurrences are as they appear in the
source file. Overrides -n casing setting. 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 Enumeration literals are in upper case. Overrides -n casing
setting. setting.
.. index:: --enum-lower-case (gnatpp)
:switch:`-neL` :switch:`--enum-lower-case`
Enumeration literals are in lower case. Overrides -n casing Enumeration literals are in lower case. Overrides -n casing
setting. setting.
.. index:: --enum-mixed-case (gnatpp)
:switch:`-neM` :switch:`--enum-mixed-case`
Enumeration literals are in mixed case. Overrides -n casing Enumeration literals are in mixed case. Overrides -n casing
setting. 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 Names introduced by type and subtype declarations are always
cased as they appear in the declaration in the source file. cased as they appear in the declaration in the source file.
Overrides -n casing setting. 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 Names introduced by type and subtype declarations are always in
upper case. Overrides -n casing setting. 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 Names introduced by type and subtype declarations are always in
lower case. Overrides -n casing setting. 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 Names introduced by type and subtype declarations are always in
mixed case. Overrides -n casing setting. 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 Names introduced by number declarations are always in
upper case. Overrides -n casing setting. 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 Names introduced by number declarations are always in
lower case. Overrides -n casing setting. 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 Names introduced by number declarations are always in
mixed case. Overrides -n casing setting. 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 Pragma names are lower case
.. index:: --pragma-upper-case (gnatpp)
:switch:`-pU` :switch:`--pragma-upper-case`
Pragma names are 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) 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 Use ``file`` as a *dictionary file* that defines
the casing for a set of specified names, the casing for a set of specified names,
thereby overriding the effect on these names by thereby overriding the effect on these names by
any explicit or implicit any explicit or implicit
-n switch. -n switch.
To supply more than one dictionary file, To supply more than one dictionary file,
use several ``-D`` switches. use several ``--dictionary`` switches.
``gnatpp`` implicitly uses a *default dictionary file* ``gnatpp`` implicitly uses a *default dictionary file*
to define the casing for the Ada predefined names and to define the casing for the Ada predefined names and
the names declared in the GNAT libraries. the names declared in the GNAT libraries.
.. index:: -D- (gnatpp) .. index:: --dictionary=- (gnatpp)
:switch:`-D-` :switch:`--dictionary=-`
Do not use the default dictionary file; Do not use the default dictionary file;
instead, use the casing instead, use the casing
defined by a ``-n`` switch and any explicit defined by a ``-n`` switch and any explicit
...@@ -3068,8 +3070,8 @@ Alternatively, you may run the script using the following command line: ...@@ -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 The structure of a dictionary file, and details on the conventions
used in the default dictionary file, are defined in :ref:`Name_Casing`. used in the default dictionary file, are defined in :ref:`Name_Casing`.
The :switch:`-D-` and The :switch:`--dictionary=-` and
:switch:`-D{file}` switches are mutually :switch:`--dictionary={file}` switches are mutually
compatible. compatible.
This group of ``gnatpp`` switches controls the layout of comments and 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: ...@@ -3080,24 +3082,24 @@ Alternatively, you may run the script using the following command line:
.. index:: -c (gnatpp) .. index:: -c (gnatpp)
:switch:`-c0` :switch:`--comments-unchanged`
All comments remain unchanged. All comments remain unchanged.
:switch:`-c1` :switch:`--comments-gnat-indentation`
GNAT-style comment line indentation. GNAT-style comment line indentation.
This is the default. This is the default.
:switch:`-c3` :switch:`--comments-gnat-beginning`
GNAT-style comment beginning. GNAT-style comment beginning.
:switch:`-c4` :switch:`--comments-fill`
Fill comment blocks. Fill comment blocks.
:switch:`-c5` :switch:`--comments-special`
Keep unchanged special form comments. Keep unchanged special form comments.
This is the default. This is the default.
...@@ -3142,6 +3144,7 @@ Alternatively, you may run the script using the following command line: ...@@ -3142,6 +3144,7 @@ Alternatively, you may run the script using the following command line:
:switch:`--use-on-new-line` :switch:`--use-on-new-line`
Start each USE clause in a context clause from a separate line. Start each USE clause in a context clause from a separate line.
.. index:: --insert-blank-lines (gnatpp) .. index:: --insert-blank-lines (gnatpp)
...@@ -3156,10 +3159,14 @@ Alternatively, you may run the script using the following command line: ...@@ -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 Preserve blank lines in the input. By default, gnatpp will squeeze
multiple blank lines down to one. multiple blank lines down to one.
.. index:: --preserve-line-breaks (gnatpp)
The ``-c`` switches are compatible with one another, except that :switch:`--preserve-line-breaks`
the ``-c0`` switch disables all other comment formatting Preserve line breaks in the input, to the extent possible.
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: .. _General_Text_Layout_Control:
...@@ -3169,21 +3176,21 @@ Alternatively, you may run the script using the following command line: ...@@ -3169,21 +3176,21 @@ Alternatively, you may run the script using the following command line:
These switches allow control over line length and indentation. 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 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 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 Indentation level for continuation lines (relative to the line being
continued), ``nnn`` from 1...9. continued), ``nnn`` from 1...9.
The default The default
...@@ -3232,9 +3239,9 @@ Alternatively, you may run the script using the following command line: ...@@ -3232,9 +3239,9 @@ Alternatively, you may run the script using the following command line:
'(' and ':'. This also turns off alignment. '(' 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. Insert a Form Feed character after a pragma Page.
...@@ -3255,6 +3262,32 @@ Alternatively, you may run the script using the following command line: ...@@ -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 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. 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: .. _Setting_the_Source_Search_Path:
...@@ -3283,48 +3316,52 @@ Alternatively, you may run the script using the following command line: ...@@ -3283,48 +3316,52 @@ Alternatively, you may run the script using the following command line:
Output File Control Output File Control
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
By default the output is sent to a file whose name is obtained by appending By default the output overwrites the input file.
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.
The output may be redirected by the following switches: 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) .. index:: --output-dir (gnatpp)
:switch:`--output-dir={dir}` :switch:`--output-dir={dir}`
Generate output file in directory :file:`dir` with the same name as the input Generate output file in directory :file:`dir` with the same name as
file. If :file:`dir` is the same as the directory containing the input file, the input file. If :file:`dir` is the same as the directory
the input file is not processed; use ``-rnb`` containing the input file, the input file is not processed; use
if you want to update the input file in place. ``--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`` 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``. Write the output into ``output_file``.
If ``output_file`` already exists, ``gnatpp`` terminates without If ``output_file`` already exists, ``gnatpp`` terminates without
reading or processing the input file. 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 Write the output into ``output_file``, overwriting the existing file
(if one is present). (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 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 original input source into the file whose name is obtained by appending the
:file:`.npp` suffix to the name of the input file. :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: ...@@ -3332,54 +3369,39 @@ Alternatively, you may run the script using the following command line:
reading or processing the input file. reading or processing the input file.
.. index:: -rf (gnatpp) .. index:: --replace-force-backup (gnatpp)
:switch:`-rf` :switch:`--replace-force-backup`
Like ``-r`` except that if the file with the specified name Like ``--replace-backup`` except that if the file with the specified name
already exists, it is overwritten. 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}` :switch:`--end-of-line={xxx}`
Specifies the line-ending style of the reformatted output file. The ``xxx`` Specifies the line-ending style of the reformatted output file. The
string specified with the switch may be: ``xxx`` string specified with the switch may be:
* *dos* - MS DOS style, lines end with CR LF characters* * *dos* - MS DOS style, lines end with CR LF characters*
* *crlf* - the same as *dos* * *crlf* - the same as *dos*
* *unix* - UNIX style, lines end with LF character* * *unix* - UNIX style, lines end with LF character*
* *lf* - the same as *unix* * *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 :switch:`--wide-character-encoding={e}`
Specify the wide character encoding method for the input and output
* *e* - EUC encoding files. ``e`` is one of the following:
* *8* - UTF-8 encoding * *8* - UTF-8 encoding
* *b* - Brackets encoding (default value) * *b* - Brackets encoding (default value)
Options ``-o`` and ``-of`` are allowed only if the call to gnatpp Options ``--output-file`` and ``--output-force`` are allowed only if
contains only one file to reformat. the call to gnatpp contains only one file to reformat.
Option ``--eol`` and ``-W`` cannot be used together Option ``--end-of-line`` and ``--wide-character-encoding`` cannot be used together
with the ``-pipe`` option. with the ``--pipe`` option.
.. _Other_gnatpp_Switches: .. _Other_gnatpp_Switches:
...@@ -3414,14 +3436,14 @@ Alternatively, you may run the script using the following command line: ...@@ -3414,14 +3436,14 @@ Alternatively, you may run the script using the following command line:
:switch:`-U` :switch:`-U`
If a project file is specified and no argument source is explicitly 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 all the units of the closure of the argument project. Otherwise this option
has no effect. has no effect.
:switch:`-U {main_unit}` :switch:`-U {main_unit}`
If a project file is specified and no argument source is explicitly 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 the closure of units rooted at ``main_unit``. Otherwise this option
has no effect. has no effect.
...@@ -3450,6 +3472,8 @@ Alternatively, you may run the script using the following command line: ...@@ -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 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 in this mode, and the gnat driver (as in *gnat pretty*) is not
supported. supported.
(Note: this switch is not yet supported in the libadalang-based
version of gnatpp.)
.. index:: --pp-off (gnatpp) .. index:: --pp-off (gnatpp)
...@@ -3466,9 +3490,9 @@ Alternatively, you may run the script using the following command line: ...@@ -3466,9 +3490,9 @@ Alternatively, you may run the script using the following command line:
of the default ``--!pp on``. 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``. Take as arguments the files listed in text file ``file``.
Text file ``file`` may contain empty lines that are ignored. Text file ``file`` may contain empty lines that are ignored.
Each nonempty line should contain the name of an existing file. 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: ...@@ -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 Do not process the sources listed in a specified file. This option cannot
be used in incremental mode. be used in incremental mode.
.. index:: -j (gnatpp) .. index:: --jobs (gnatpp)
:switch:`-j{n}` :switch:`--jobs={n}`
Without ``--incremental``, use *n* processes to carry out the With ``--incremental``, use *n* ``gnatpp`` processes to perform
tree creations (internal representations of the argument sources). On pretty printing in parallel. If *n* is 0, then the maximum number
a multiprocessor machine this speeds up processing of big sets of processes is the number of core processors on the platform.
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.
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.
:switch:`--verbose`
.. index:: -v (gnatpp)
:switch:`-v`
Verbose mode Verbose mode
.. index:: -q (gnatpp) .. index:: --quiet (gnatpp)
:switch:`-q` :switch:`--quiet`
Quiet mode Quiet mode
If a project file is specified and no argument source is explicitly 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 ``-U`` is specified, then the set of processed sources is
all the immediate units of the argument project. all the immediate units of the argument project.
...@@ -3612,42 +3619,40 @@ Alternatively, you may run the script using the following command line: ...@@ -3612,42 +3619,40 @@ Alternatively, you may run the script using the following command line:
the same line. the same line.
A whole-line comment is indented according to the surrounding code, A whole-line comment is indented according to the surrounding code,
with some exceptions. with some exceptions. Comments that start in column 1 are kept
Comments that start in column 1 are kept there. there. If possible, comments are not moved so far to the right that
If possible, comments are not moved so far to the right that the maximum the maximum line length is exceeded. The ``--comments-unchanged``
line length is exceeded. option turns off comment formatting. Special-form comments such as
The ``-c0`` option SPARK-style ``--#...`` are left alone.
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 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 number of spaces between the end of the preceding Ada code and the
beginning of the comment as appear in the original source. beginning of the comment as appear in the original source.
The ``-c3`` switch The ``--comments-gnat-beginning`` switch (GNAT style comment
(GNAT style comment beginning) has the following beginning) has the following effect:
effect:
* For each whole-line comment that does not end with two hyphens, * For each whole-line comment that does not end with two hyphens,
``gnatpp`` inserts spaces if necessary after the starting two hyphens ``gnatpp`` inserts spaces if necessary after the starting two
to ensure that there are at least two spaces between these hyphens and the hyphens to ensure that there are at least two spaces between
first non-blank character of the comment. these hyphens and the first non-blank character of the comment.
The ``-c4`` switch specifies that The ``--comments-fill`` switch specifies that whole-line comments
whole-line comments that form a paragraph will be filled in typical that form a paragraph will be filled in typical word processor style
word processor style (that is, moving words between lines to make the (that is, moving words between lines to make the lines other than the
lines other than the last similar in length ). last similar in length ).
The ``--comments-only`` switch specifies that only the comments The ``--comments-only`` switch specifies that only the comments are
are formatted; the rest of the program text is left alone. The formatted; the rest of the program text is left alone. The comments
comments are formatted according to the -c3 and -c4 switches; other are formatted according to the ``--comments-gnat-beginning`` and
formatting switches are ignored. For example, ``--comments-fill`` switches; other formatting switches are ignored. For
``--comments-only -c4`` means to fill comment paragraphs, and do nothing else. example, ``--comments-only --comments-fill`` means to fill comment
Likewise, paragraphs, and do nothing else. Likewise, ``--comments-only
``--comments-only -c3`` ensures comments start with at least two --comments-gnat-beginning`` ensures comments start with at least two
spaces after ``--``, and ``--comments-only -c3 -c4`` does spaces after ``--``, and ``--comments-only --comments-gnat-beginning
both. If ``--comments-only`` is given without ``-c3`` or --comments-fill`` does both. If ``--comments-only`` is given without
``-c4``, then gnatpp doesn't format anything. ``--comments-gnat-beginning`` or ``--comments-fill``, then gnatpp
doesn't format anything.
.. _Name_Casing: .. _Name_Casing:
...@@ -3658,49 +3663,42 @@ Alternatively, you may run the script using the following command line: ...@@ -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 ``gnatpp`` always converts the usage occurrence of a (simple) name to
the same casing as the corresponding defining identifier. the same casing as the corresponding defining identifier.
You control the casing for defining occurrences via the You control the casing for defining occurrences via the ``--name...``
``-n`` switch. switches. With ``--name-case-as-declared``, which is the default,
With ``-nD`` ('as declared', which is the default), defining occurrences appear exactly as in the source file where they
defining occurrences appear exactly as in the source file are declared. The other values for this switch --
where they are declared. ``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case``
The other values for this switch -- -- result in upper, lower, or mixed case, respectively. If
``-nU``, ``gnatpp`` changes the casing of a defining occurrence, it
``-nL``, analogously changes the casing of all the usage occurrences of this
``-nM`` -- name.
result in
upper, lower, or mixed case, respectively. If the defining occurrence of a name is not in the source compilation
If ``gnatpp`` changes the casing of a defining unit currently being processed by ``gnatpp``, the casing of each
occurrence, it analogously changes the casing of all the reference to this name is changed according to the switch (subject to
usage occurrences of this name. the dictionary file mechanism described below). Thus ``gnatpp`` acts
as though the switch had affected the casing for the defining
If the defining occurrence of a name is not in the source compilation unit occurrence of the name.
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.
The options The options
:switch:`-a{x}`, :switch:`--attribute...`,
:switch:`-k{x}`, :switch:`--keyword...`,
:switch:`-ne{x}`, :switch:`--enum...`,
:switch:`-nt{x}`, :switch:`--type...`,
:switch:`-nn{x}`, and :switch:`--number...`, and
:switch:`-p{x}` :switch:`--pragma...`
allow finer-grained control over casing for allow finer-grained control over casing for
attributes, keywords, enumeration literals, attributes, keywords, enumeration literals,
types, named numbers and pragmas, respectively. types, named numbers and pragmas, respectively.
:switch:`-nt{x}` covers subtypes and :switch:`--type...` cover subtypes as well.
task and protected bodies as well.
Some names may need to be spelled with casing conventions that are not Some names may need to be spelled with casing conventions that are not
covered by the upper-, lower-, and mixed-case transformations. covered by the upper-, lower-, and mixed-case transformations.
You can arrange correct casing by placing such names in a You can arrange correct casing by placing such names in a
*dictionary file*, *dictionary file*,
and then supplying a ``-D`` switch. and then supplying a ``--dictionary`` switch.
The casing of names from dictionary files overrides 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, To handle the casing of Ada predefined names and the names from GNAT libraries,
``gnatpp`` assumes a default dictionary file. ``gnatpp`` assumes a default dictionary file.
...@@ -3709,15 +3707,15 @@ Alternatively, you may run the script using the following command line: ...@@ -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 The name of each entity in the GNAT libraries is spelled with the same casing
as is used in the declaration of that entity. 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 the default dictionary file. Instead, the casing for predefined and
GNAT-defined names will be established by the GNAT-defined names will be established by the
``-n`` switch or explicit dictionary files. For ``-n`` switch or explicit dictionary files. For
example, by default the names ``Ada.Text_IO`` and example, by default the names ``Ada.Text_IO`` and
``GNAT.OS_Lib`` will appear as just shown, even in the presence of ``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 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). in upper case in a dictionary file).
A dictionary file is a plain text file; each line in this file can be 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: ...@@ -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. comment; any amount of white space is allowed before the string.
If a dictionary file is passed as 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 then for every
simple name and every identifier, ``gnatpp`` checks if the dictionary 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' 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: ...@@ -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: 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: ...@@ -3812,6 +3810,200 @@ Alternatively, you may run the script using the following command line:
Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1; Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
end Test; 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 .. 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