10.3.1 File Format in the Mappings File

The mappings file consists of a series of separate tables. Each table begins with its name. Names always have an alphabetic character in the first column. The table name is followed by a required blank line, and then by the entries in the table. Entries consist of zero or more indented lines. Each entry line consists of two columns separated by one or more spaces or tabs. Any spaces within an entry must be quoted using the $ character. A blank line must appear after each mapping table name and between each mapping table; no blank lines can appear between entries in a single table. Comments are introduced by an exclamation mark (!) in the first column.

The resulting format looks like:

TABLE1_NAME

   pattern1-1    template1-1
   pattern1-2    template1-2
   pattern1-3    template1-3
      .              .
      .              .
      .              .
   pattern1-n    template1-n

TABLE2_NAME

   pattern2-1    template2-1
   pattern2-2    template2-2
   pattern2-3    template2-3
       .            .
       .            .
       .            .
   pattern2-n    template2-n
          .
          .
          .


TABLE3_NAME

           .
          .
          .

         

An application using the mapping table TABLE2_NAME would map the string pattern2-2 into whatever is specified by template2-2. Each pattern or template can contain up to 256 and 1024 characters respectively. The maximum size of a line in the mapping file is 4096 characters. There is no limit to the number of entries that can appear in a mapping (although excessive numbers of entries may consume huge amounts of CPU and can consume excessive amounts of memory). Long lines (over 252 characters) may be continued by ending them with a backslash (\). The white space between the two columns and before the first column may not be omitted.

Duplicate mapping table names are not allowed in the mappings file.

10.3.1.1 Including Other Files in the Mappings File

Other files may be included in the mappings file. This is done with a line of the form:

<file-spec
            

This effectively substitutes the contents of the file file-spec into the mappings file at the point where the include appears. The file specification should specify a full file path (directory, and so forth). All files included in this fashion must be world readable. Comments are also allowed in such included mappings file. Includes can be nested up to three levels deep. Include files are loaded at the same time the mappings file is loaded—they are not loaded on demand, so there is no performance or memory savings involved in using include files.