* :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`
.. 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
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:
* ``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:
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
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
.. 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.
:switch:`--use-on-new-line`
Start each USE clause in a context clause from a separate line.
+
.. index:: --insert-blank-lines (gnatpp)
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:
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
'(' 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.
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:
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.
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:
: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.
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)
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.
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.
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:
``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.
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
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'
::
- $ 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:
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
projects / gcc.git / commitdiff