GNAT GPL User's Guide: File Name Krunching with gnatkr

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

# 17. File Name Krunching with `gnatkr`

This chapter discusses the method used by the compiler to shorten the default file names chosen for Ada units so that they do not exceed the maximum length permitted. It also describes the `gnatkr` utility that can be used to determine the result of applying this shortening.

> 17.1 About `gnatkr` |  |
> 17.2 Using `gnatkr` |  |
> 17.3 Krunching Method |  |
> 17.4 Examples of `gnatkr` Usage |  |

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

## 17.1 About `gnatkr`

The default file naming rule in GNAT is that the file name must be derived from the unit name. The exact default rule is as follows:

- Take the unit name and replace all dots by hyphens.
- If such a replacement occurs in the second character position of a name, and the first character is ``a'`, ``g'`, ``s'`, or ``i'`, then replace the dot by the character ``~'` (tilde) instead of a minus.

The reason for this exception is to avoid clashes with the standard names for children of System, Ada, Interfaces, and GNAT, which use the prefixes ``s-'`, ``a-'`, ``i-'`, and ``g-'`, respectively.

The ``-gnatknn'` switch of the compiler activates a "krunching" circuit that limits file names to nn characters (where nn is a decimal integer). For example, using OpenVMS, where the maximum file name length is 39, the value of nn is usually set to 39, but if you want to generate a set of files that would be usable if ported to a system with some different maximum file length, then a different value can be specified. The default value of 39 for OpenVMS need not be specified.

The `gnatkr` utility can be used to determine the krunched name for a given file, when krunched to a specified maximum length.

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

## 17.2 Using `gnatkr`

The `gnatkr` command has the form

    $ gnatkr name [length]

name is the uncrunched file name, derived from the name of the unit in the standard manner described in the previous section (i.e., in particular all dots are replaced by hyphens). The file name may or may not have an extension (defined as a suffix of the form period followed by arbitrary characters other than period). If an extension is present then it will be preserved in the output. For example, when krunching ``hellofile.ads'` to eight characters, the result will be hellofil.ads.

Note: for compatibility with previous versions of `gnatkr` dots may appear in the name instead of hyphens, but the last dot will always be taken as the start of an extension. So if `gnatkr` is given an argument such as ``Hello.World.adb'` it will be treated exactly as if the first period had been a hyphen, and for example krunching to eight characters gives the result ``hellworl.adb'`.

Note that the result is always all lower case (except on OpenVMS where it is all upper case). Characters of the other case are folded as required.

length represents the length of the krunched name. The default when no argument is given is 8 characters. A length of zero stands for unlimited, in other words do not chop except for system files where the implied crunching length is always eight characters.

The output is the krunched name. The output has an extension only if the original argument was a file name with an extension.

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

## 17.3 Krunching Method

The initial file name is determined by the name of the unit that the file contains. The name is formed by taking the full expanded name of the unit and replacing the separating dots with hyphens and using lowercase for all letters, except that a hyphen in the second character position is replaced by a tilde if the first character is ``a'`, ``i'`, ``g'`, or ``s'`. The extension is `.ads` for a spec and `.adb` for a body. Krunching does not affect the extension, but the file name is shortened to the specified length by following these rules:

- The name is divided into segments separated by hyphens, tildes or underscores and all hyphens, tildes, and underscores are eliminated. If this leaves the name short enough, we are done.

- If the name is too long, the longest segment is located (left-most if there are two of equal length), and shortened by dropping its last character. This is repeated until the name is short enough.

  As an example, consider the krunching of
  ``our-strings-wide_fixed.adb'` to fit the name into 8 characters as required by some operating systems.

      our-strings-wide_fixed 22
      our strings wide fixed 19
      our string  wide fixed 18
      our strin   wide fixed 17
      our stri    wide fixed 16
      our stri    wide fixe  15
      our str     wide fixe  14
      our str     wid  fixe  13
      our str     wid  fix   12
      ou  str     wid  fix   11
      ou  st      wid  fix   10
      ou  st      wi   fix   9
      ou  st      wi   fi    8
      Final file name: oustwifi.adb

- The file names for all predefined units are always krunched to eight characters. The krunching of these predefined units uses the following special prefix replacements:

  ``ada-'`
    replaced by ``a-'`

  ``gnat-'`
    replaced by ``g-'`

  ``interfaces-'`
    replaced by ``i-'`

  ``system-'`
    replaced by ``s-'`

  These system files have a hyphen in the second character position. That is why normal user files replace such a character with a tilde, to avoid confusion with system file names.

  As an example of this special rule, consider
  ``ada-strings-wide_fixed.adb'`, which gets krunched as follows:

      ada-strings-wide_fixed 22
      a-  strings wide fixed 18
      a-  string  wide fixed 17
      a-  strin   wide fixed 16
      a-  stri    wide fixed 15
      a-  stri    wide fixe  14
      a-  str     wide fixe  13
      a-  str     wid  fixe  12
      a-  str     wid  fix   11
      a-  st      wid  fix   10
      a-  st      wi   fix   9
      a-  st      wi   fi    8
      Final file name: a-stwifi.adb

Of course no file shortening algorithm can guarantee uniqueness over all possible unit names, and if file name krunching is used then it is your responsibility to ensure that no name clashes occur. The utility program `gnatkr` is supplied for conveniently determining the krunched name of a file.

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

## 17.4 Examples of `gnatkr` Usage

    $ gnatkr very_long_unit_name.ads      --> velounna.ads
    $ gnatkr grandparent-parent-child.ads --> grparchi.ads
    $ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads
    $ gnatkr grandparent-parent-child     --> grparchi
    $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
    $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads

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

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