GNAT GPL User's Guide: Renaming Files with gnatchop

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 8. Renaming Files with `gnatchop`

This chapter discusses how to handle files with multiple units by using the `gnatchop` utility. This utility is also useful in renaming files to meet the standard GNAT default file naming conventions.

> 8.1 Handling Files with Multiple Units |  |
> 8.2 Operating gnatchop in Compilation Mode |  |
> 8.3 Command Line for `gnatchop` |  |
> 8.4 Switches for `gnatchop` |  |
> 8.5 Examples of `gnatchop` Usage |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 8.1 Handling Files with Multiple Units

The basic compilation model of GNAT requires that a file submitted to the compiler have only one unit and there be a strict correspondence between the file name and the unit name.

The `gnatchop` utility allows both of these rules to be relaxed, allowing GNAT to process files which contain multiple compilation units and files with arbitrary file names. `gnatchop` reads the specified file and generates one or more output files, containing one unit per file. The unit and the file name correspond, as required by GNAT.

If you want to permanently restructure a set of "foreign" files so that they match the GNAT rules, and do the remaining development using the GNAT structure, you can simply use `gnatchop` once, generate the new set of files and work with them from that point on.

Alternatively, if you want to keep your files in the "foreign" format, perhaps to maintain compatibility with some other Ada compilation system, you can set up a procedure where you use `gnatchop` each time you compile, regarding the source files that it writes as temporary files that you throw away.

Note that if your file containing multiple units starts with a byte order mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop will each start with a copy of this BOM, meaning that they can be compiled automatically in UTF-8 mode without needing to specify an explicit encoding.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 8.2 Operating gnatchop in Compilation Mode

The basic function of `gnatchop` is to take a file with multiple units and split it into separate files. The boundary between files is reasonably clear, except for the issue of comments and pragmas. In default mode, the rule is that any pragmas between units belong to the previous unit, except that configuration pragmas always belong to the following unit. Any comments belong to the following unit. These rules almost always result in the right choice of the split point without needing to mark it explicitly and most users will find this default to be what they want. In this default mode it is incorrect to submit a file containing only configuration pragmas, or one that ends in configuration pragmas, to `gnatchop`.

However, using a special option to activate "compilation mode", `gnatchop` can perform another function, which is to provide exactly the semantics required by the RM for handling of configuration pragmas in a compilation. In the absence of configuration pragmas (at the main file level), this option has no effect, but it causes such configuration pragmas to be handled in a quite different manner.

First, in compilation mode, if `gnatchop` is given a file that consists of only configuration pragmas, then this file is appended to the ``gnat.adc'` file in the current directory. This behavior provides the required behavior described in the RM for the actions to be taken on submitting such a file to the compiler, namely that these pragmas should apply to all subsequent compilations in the same compilation environment. Using GNAT, the current directory, possibly containing a ``gnat.adc'` file is the representation of a compilation environment. For more information on the ``gnat.adc'` file, see 9.1 Handling of Configuration Pragmas.

Second, in compilation mode, if `gnatchop` is given a file that starts with configuration pragmas, and contains one or more units, then these configuration pragmas are prepended to each of the chopped files. This behavior provides the required behavior described in the RM for the actions to be taken on compiling such a file, namely that the pragmas apply to all units in the compilation, but not to subsequently compiled units.

Finally, if configuration pragmas appear between units, they are appended to the previous unit. This results in the previous unit being illegal, since the compiler does not accept configuration pragmas that follow a unit. This provides the required RM behavior that forbids configuration pragmas other than those preceding the first compilation unit of a compilation.

For most purposes, `gnatchop` will be used in default mode. The compilation mode described above is used only if you need exactly accurate behavior with respect to compilations, and you have files that contain multiple units and configuration pragmas. In this circumstance the use of `gnatchop` with the compilation mode switch provides the required behavior, and is for example the mode in which GNAT processes the ACVC tests.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 8.3 Command Line for `gnatchop`

The `gnatchop` command has the form:

    $ gnatchop switches file name [file name ...]
          [directory]

The only required argument is the file name of the file to be chopped. There are no restrictions on the form of this file name. The file itself contains one or more Ada units, in normal GNAT format, concatenated together. As shown, more than one file may be presented to be chopped.

When run in default mode, `gnatchop` generates one output file in the current directory for each unit in each of the files.

directory, if specified, gives the name of the directory to which the output files will be written. If it is not specified, all files are written to the current directory.

For example, given a file called ``hellofiles'` containing

    procedure hello;

    with Text_IO; use Text_IO;
    procedure hello is
    begin
       Put_Line ("Hello");
    end hello;

the command

    $ gnatchop hellofiles

generates two files in the current directory, one called ``hello.ads'` containing the single line that is the procedure spec, and the other called ``hello.adb'` containing the remaining text. The original file is not affected. The generated files can be compiled in the normal manner.

When gnatchop is invoked on a file that is empty or that contains only empty lines and/or comments, gnatchop will not fail, but will not produce any new sources.

For example, given a file called ``toto.txt'` containing

    --  Just a comment

the command

    $ gnatchop toto.txt

will not produce any new file and will result in the following warnings:

    toto.txt:1:01: warning: empty file, contains no compilation units
    no compilation units found
    no source files written

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 8.4 Switches for `gnatchop`

`gnatchop` recognizes the following switches:

``--version'`
  Display Copyright and version, then exit disregarding all other options.

``--help'`
  If ``--version'` was not used, display usage, then exit disregarding all other options.

``-c'`
  Causes `gnatchop` to operate in compilation mode, in which configuration pragmas are handled according to strict RM rules. See previous section for a full description of this mode.

``-gnatxxx'`
  This passes the given ``-gnatxxx'` switch to `gnat` which is used to parse the given file. Not all xxx options make sense, but for example, the use of ``-gnati2'` allows `gnatchop` to process a source file that uses Latin-2 coding for identifiers.

``-h'`
  Causes `gnatchop` to generate a brief help summary to the standard output file showing usage information.

``-kmm'`
  Limit generated file names to the specified number `mm` of characters. This is useful if the resulting set of files is required to be interoperable with systems which limit the length of file names. No space is allowed between the ``-k'` and the numeric value. The numeric value may be omitted in which case a default of ``-k8'`, suitable for use with DOS-like file systems, is used. If no ``-k'` switch is present then there is no limit on the length of file names.

``-p'`
  Causes the file modification time stamp of the input file to be preserved and used for the time stamp of the output file(s). This may be useful for preserving coherency of time stamps in an environment where `gnatchop` is used as part of a standard build process.

``-q'`
  Causes output of informational messages indicating the set of generated files to be suppressed. Warnings and error messages are unaffected.

``-r'`
  Generate `Source_Reference` pragmas. Use this switch if the output files are regarded as temporary and development is to be done in terms of the original unchopped file. This switch causes `Source_Reference` pragmas to be inserted into each of the generated files to refers back to the original file name and line number. The result is that all error messages refer back to the original unchopped file. In addition, the debugging information placed into the object file (when the ``-g'` switch of `gcc` or `gnatmake` is specified) also refers back to this original file so that tools like profilers and debuggers will give information in terms of the original unchopped file.

  If the original file to be chopped itself contains a `Source_Reference` pragma referencing a third file, then gnatchop respects this pragma, and the generated `Source_Reference` pragmas in the chopped file refer to the original file, with appropriate line numbers. This is particularly useful when `gnatchop` is used in conjunction with `gnatprep` to compile files that contain preprocessing statements and multiple units.

``-v'`
  Causes `gnatchop` to operate in verbose mode. The version number and copyright notice are output, as well as exact copies of the gnat1 commands spawned to obtain the chop control information.

``-w'`
  Overwrite existing file names. Normally `gnatchop` regards it as a fatal error if there is already a file with the same name as a file it would otherwise output, in other words if the files to be chopped contain duplicated units. This switch bypasses this check, and causes all but the last instance of such duplicated units to be skipped.

``--GCC=xxxx'`
  Specify the path of the GNAT parser to be used. When this switch is used, no attempt is made to add the prefix to the GNAT parser executable.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 8.5 Examples of `gnatchop` Usage

`gnatchop -w hello_s.ada prerelease/files`

  Chops the source file ``hello_s.ada'`. The output files will be placed in the directory ``prerelease/files'`, overwriting any files with matching names in that directory (no files in the current directory are modified).

`gnatchop archive`
  Chops the source file ``archive'` into the current directory. One useful application of `gnatchop` is in sending sets of sources around, for example in email messages. The required sources are simply concatenated (for example, using a Unix `cat` command), and then `gnatchop` is used at the other end to reconstitute the original file names.

`gnatchop file1 file2 file3 direc`
  Chops all units in files ``file1'`, ``file2'`, ``file3'`, placing the resulting files in the directory ``direc'`. Note that if any units occur more than once anywhere within this set of files, an error message is generated, and no files are written. To override this check, use the ``-w'` switch, in which case the last occurrence in the last file will be the one that is output, and earlier duplicate occurrences for a given unit will be skipped.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html