GCC v8.2
[gcc.git] / gcc / ada / krunch.ads
1 ------------------------------------------------------------------------------
2 --                                                                          --
3 --                         GNAT COMPILER COMPONENTS                         --
4 --                                                                          --
5 --                               K R U N C H                                --
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.                                     --
17 --                                                                          --
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
19 -- additional permissions described in the GCC Runtime Library Exception,   --
20 -- version 3.1, as published by the Free Software Foundation.               --
21 --                                                                          --
22 -- You should have received a copy of the GNU General Public License and    --
23 -- a copy of the GCC Runtime Library Exception along with this program;     --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
25 -- <http://www.gnu.org/licenses/>.                                          --
26 --                                                                          --
27 -- GNAT was originally developed  by the GNAT team at  New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
29 --                                                                          --
30 ------------------------------------------------------------------------------
31
32 --  This procedure implements file name crunching
33
34 --    First, the name is divided into segments separated by minus signs and
35 --    underscores, then all minus signs and underscores are eliminated. If
36 --    this leaves the name short enough, we are done.
37
38 --    If not, then the longest segment is located (left-most if there are
39 --    two of equal length), and shortened by dropping its last character.
40 --    This is repeated until the name is short enough.
41
42 --    As an example, consider the krunch of our-strings-wide_fixed.adb
43 --    to fit the name into 8 characters as required by DOS:
44
45 --      our-strings-wide_fixed      22
46 --      our strings wide fixed      19
47 --      our string  wide fixed      18
48 --      our strin   wide fixed      17
49 --      our stri    wide fixed      16
50 --      our stri    wide fixe       15
51 --      our str     wide fixe       14
52 --      our str     wid  fixe       13
53 --      our str     wid  fix        12
54 --      ou  str     wid  fix        11
55 --      ou  st      wid  fix        10
56 --      ou  st      wi   fix         9
57 --      ou  st      wi   fi          8
58
59 --      Final file name: OUSTWIFX.ADB
60
61 --    A special rule applies for children of System, Ada, Gnat, and Interfaces.
62 --    In these cases, the following special prefix replacements occur:
63
64 --       ada-        replaced by  a-
65 --       gnat-       replaced by  g-
66 --       interfaces- replaced by  i-
67 --       system-     replaced by  s-
68
69 --    The rest of the name is krunched in the usual manner described above.
70 --    In addition, these names, as well as the names of the renamed packages
71 --    from the obsolescent features annex, are always krunched to 8 characters
72 --    regardless of the setting of Maxlen.
73
74 --    As an example of this special rule, consider ada-strings-wide_fixed.adb
75 --    which gets krunched as follows:
76
77 --      ada-strings-wide_fixed      22
78 --      a-  strings wide fixed      18
79 --      a-  string  wide fixed      17
80 --      a-  strin   wide fixed      16
81 --      a-  stri    wide fixed      15
82 --      a-  stri    wide fixe       14
83 --      a-  str     wide fixe       13
84 --      a-  str     wid  fixe       12
85 --      a-  str     wid  fix        11
86 --      a-  st      wid  fix        10
87 --      a-  st      wi   fix         9
88 --      a-  st      wi   fi          8
89
90 --      Final file name: A-STWIFX.ADB
91
92 --  Since children of units named A, G, I or S might conflict with the names
93 --  of predefined units, the naming rule in that case is that the first hyphen
94 --  is replaced by a tilde sign.
95
96 --  Note: as described below, this special treatment of predefined library
97 --  unit file names can be inhibited by setting the No_Predef flag.
98
99 --  Of course there is no guarantee that this algorithm results in uniquely
100 --  crunched names (nor, obviously, is there any algorithm which would do so)
101 --  In fact we run into such a case in the standard library routines with
102 --  children of Wide_Text_IO, so a special rule is applied to deal with this
103 --  clash, namely the prefix ada-wide_text_io- is replaced by a-wt- and then
104 --  the normal crunching rules are applied, so that for example, the unit:
105
106 --    Ada.Wide_Text_IO.Float_IO
107
108 --  has the file name
109
110 --    a-wtflio
111
112 --  More problems arise with Wide_Wide, so we replace this sequence by
113 --  a z (which is not used much) and also (as in the Wide_Text_IO case),
114 --  we replace the prefix ada.wide_wide_text_io- by a-zt- and then
115 --  the normal crunching rules are applied.
116
117 --  These are the only irregularity required (so far) to keep the file names
118 --  unique in the standard predefined libraries.
119
120 procedure Krunch
121   (Buffer        : in out String;
122    Len           : in out Natural;
123    Maxlen        : Natural;
124    No_Predef     : Boolean);
125 pragma Elaborate_Body (Krunch);
126 --  The full file name is stored in Buffer (1 .. Len) on entry. The file
127 --  name is crunched in place and on return Len is updated, so that the
128 --  resulting krunched name is in Buffer (1 .. Len) where Len <= Maxlen.
129 --  Note that Len may be less than or equal to Maxlen on entry, in which
130 --  case it may be possible that Krunch does not modify Buffer. The fourth
131 --  parameter, No_Predef, is a switch which, if set to True, disables the
132 --  normal special treatment of predefined library unit file names.
133 --
134 --  Note: the string Buffer must have a lower bound of 1, and may not
135 --  contain any blanks (in particular, it must not have leading blanks).