gcc/ada/gnatprep.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                             G N A T P R E P                              --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2018, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT; see file COPYING3.  If not, go to --
  19 -- http://www.gnu.org/licenses for a complete copy of the license.          --
  20 --                                                                          --
  21 -- GNAT was originally developed  by the GNAT team at  New York University. --
  22 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  23 --                                                                          --
  24 ------------------------------------------------------------------------------
  25
  26 --  This program provides a simple preprocessing capability for Ada programs.
  27 --  It is designed for use with GNAT, but is not dependent on any special
  28 --  features of GNAT.
  29
  30 --    To call gnatprep use
  31
  32 --      gnatprep infile outfile [deffile] [-v] [-c] [-b] [-r] [-s] [-u]
  33 --            [-Dsymbol=value]
  34
  35 --    where
  36
  37 --      infile is the full name of the input file, which is an Ada source
  38 --      file containing preprocessor directives.
  39
  40 --      outfile is the full name of the output file, which is an Ada source
  41 --      in standard Ada form. When used with GNAT, this file name will
  42 --      normally have an ads or adb suffix.
  43
  44 --      deffile is the full name of a text file containing definitions of
  45 --      symbols to be referenced by the preprocessor. This argument is
  46 --      optional.
  47
  48 --      The -c switch, causes both preprocessor lines and the lines deleted
  49 --      by preprocessing to be retained in the output source as comments marked
  50 --      with the special string "--! ". This option will result in line numbers
  51 --      being preserved in the output file.
  52
  53 --      The -b switch causes both preprocessor lines and the lines deleted by
  54 --      preprocessing to be replaced by blank lines in the output source file,
  55 --      thus preserving line numbers in the output file.
  56
  57 --      The -r switch causes a Source_Reference pragma to be generated that
  58 --      references the original input file, so that error messages will use
  59 --      the file name of this original file.
  60
  61 --      The -u switch causes gnatprep to treat any undefined symbol that it
  62 --      encounters as having the value False. Otherwise an undefined symbol
  63 --      is a fatal error.
  64
  65 --      The -s switch causes a sorted list of symbol names and values to be
  66 --      listed on the standard output file.
  67
  68 --      The -v switch causes a Copyright notice to be displayed, and
  69 --      lines containing errors in the input file or the definition file
  70 --      to be displayed before the errors.
  71
  72 --      The -D switch causes symbol 'symbol' to be associated with 'value'.
  73 --      This symbols can then be referenced by the preprocessor. Several
  74 --      -D switches may be specified.
  75
  76 --      Note: if neither -b nor -c is present, then preprocessor lines and
  77 --      deleted lines are completely removed from the output, unless -r is
  78 --      specified, in which case -b is assumed.
  79
  80 --   The definitions file contains lines of the form
  81
  82 --      symbol := value
  83
  84 --   where symbol is an identifier, following normal Ada (case-insensitive)
  85 --   rules for its syntax, and value is one of the following:
  86
  87 --      Empty, corresponding to a null substitution
  88
  89 --      A string literal using normal Ada syntax
  90
  91 --      Any sequence of characters from the set
  92 --        (letters, digits, period, underline)
  93
  94 --   Comment lines may also appear in the definitions file, starting with
  95 --   the usual --, and comments may be added to the definitions lines.
  96
  97 --   The input text may contain preprocessor conditional inclusion lines,
  98 --   and also general symbol substitution sequences.
  99
 100 --   The preprocessor conditional inclusion commands have the form
 101
 102 --      #if <expression> [then]
 103 --         lines
 104 --      #elsif <expression> [then]
 105 --         lines
 106 --      #elsif <expression> [then]
 107 --         lines
 108 --      ...
 109 --      #else
 110 --         lines
 111 --      #end if;
 112 --
 113 --     Where expression is defined by the following grammar :
 114 --        expression ::=  <symbol>
 115 --        expression ::=  <symbol> = "<value>"
 116 --        expression ::=  <symbol> = <symbol>
 117 --        expression ::=  <symbol> 'Defined
 118 --        expression ::=  not <expression>
 119 --        expression ::=  <expression> and <expression>
 120 --        expression ::=  <expression> or <expression>
 121 --        expression ::=  <expression> and then <expression>
 122 --        expression ::=  <expression> or else <expression>
 123 --        expression ::=  ( <expression> )
 124
 125 --        "or" and "and" may not be used in the same expression without
 126 --        using parentheses.
 127
 128 --     For these Boolean tests, the symbol must have either the value True or
 129 --     False. If the value is True, then the corresponding lines are included,
 130 --     and if the value is False, they are excluded. It is an error to
 131 --     reference a symbol not defined in the symbol definitions file, or
 132 --     to reference a symbol that has a value other than True or False.
 133
 134 --     The use of the not operator inverts the sense of this logical test, so
 135 --     that the lines are included only if the symbol is not defined.
 136
 137 --     The THEN keyword is optional as shown
 138
 139 --     Spaces or tabs may appear between the # and the keyword. The keywords
 140 --     and the symbols are case insensitive as in normal Ada code. Comments
 141 --     may be used on a preprocessor line, but other than that, no other
 142 --     tokens may appear on a preprocessor line.
 143
 144 --     Any number of #elsif clauses can be present, including none at all
 145
 146 --     The #else is optional, as in Ada
 147
 148 --     The # marking the start of a preprocessor line must be the first
 149 --     non-blank character on the line, i.e. it must be preceded only by
 150 --     spaces or horizontal tabs.
 151
 152 --   Symbol substitution is obtained by using the sequence
 153
 154 --     $symbol
 155
 156 --   anywhere within a source line, except in a comment. The identifier
 157 --   following the $ must match one of the symbols defined in the symbol
 158 --   definition file, and the result is to substitute the value of the
 159 --   symbol in place of $symbol in the output file.
 160
 161 procedure GNATprep;