From 1646b09f3b917a135a15084ccd1a8ce41ddf3d38 Mon Sep 17 00:00:00 2001 From: Bob Duff Date: Thu, 11 Jan 2018 08:52:20 +0000 Subject: [PATCH] [Ada] Update gnatpp documentation after engine change 2018-01-11 Bob Duff 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 --- gcc/ada/ChangeLog | 6 + gcc/ada/doc/gnat_ugn/about_this_guide.rst | 2 +- .../doc/gnat_ugn/gnat_utility_programs.rst | 688 +++++++++++------- 3 files changed, 447 insertions(+), 249 deletions(-) diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 9915a7a2c20..4a92bf96d03 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,9 @@ +2018-01-11 Bob Duff + + * 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 * sem_res.adb (Uses_SS): A controlled type requires the secondary stack diff --git a/gcc/ada/doc/gnat_ugn/about_this_guide.rst b/gcc/ada/doc/gnat_ugn/about_this_guide.rst index 241e99891cc..e3037210ac8 100644 --- a/gcc/ada/doc/gnat_ugn/about_this_guide.rst +++ b/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` diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst index 95a35f3e03c..74dbe4ea836 100644 --- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst +++ b/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 -- 2.30.2