Detailed Template Line Format

Each line of the template generally translates into one FITS keyword record. In addition, there are several template directives, each preceded by a backslash character, which are used to indicate the start and end of HDU definitions. Also, any template line that begins with the pound '#' character is ignored by the template parser and may be use to insert comments into the template file itself.

The format of each template line follows very closely the format of the FITS keyword record:

            KEYWORD = KEYVALUE / COMMENT

All the fields are optional, and only one field of each type per record is allowed. The fields must appear in order. The result of parsing is one (or possibly more, in the case of a long keyvalue field) 80 character FITS header record(s). For the purpose of parsing, space and TAB characters (blanks) are equivalent and treated as separators.

The start of each record field is order dependent but position independent, except if the first 8 characters of a record are blanks then the entire line is treated as a FITS comment keyword (with a blank keyword name) and copied verbatim into the FITS header. Thus lines can be indented, but indentation is limited to a maximum of 7 spaces.

The KEYWORD field is limited to 8 characters in length and only the letters A-Z, digits 0-9, and the hyphen and underscore character may be used, without any embedded spaces. Lowercase letters in the template keyword name are converted to uppercase. The only exception to this is when auto-indexing is used (see below).

The KEYWORD and KEYVALUE may optionally be separated by the "=" character with optional spaces allowed on either side of the "=".

KEYVALUE fields are parsed for data type using standard FITS rules. Allowed data types are:

  - logical         : T or F character
  - integer         : -12345
  - real            : -1.234E+68
  - complex integer : (integer,integer)
  - complex real    : (real,real)
  - string          : any other format

The value may be forced to be interpreted as a character string by enclosing it in single quotes. An undefined (null) value is specified if the template record only contains blanks following the "=" or between the "=" and the "/" comment field delimiter.

Keyword values longer than 68 characters (for string data type) are permitted using the cfitsio long string convention. They can either be specified as a single "long" line, or by using multiple lines where the continuing lines contain the 'CONTINUE' keyword. Example:

  LONGKEY = 'This is a long string value that is contin&'
  CONTINUE  'ued over 2 records' / comment field here

The format of template lines with CONTINUE keyword is very strict: 3 spaces must follow CONTINUE and the rest of the line is copied verbatim to the FITS file.

Note: contrary to the FITS standard, the template cannot have any blanks between real and imaginary parts of a complex number (complex integer and complex real data types).

The start of a COMMENT field must be preceeded by "/", which is used to separate it from the keyword value field. Exceptions are if the KEYWORD field contains COMMENT, HISTORY, CONTINUE, or if the first 8 chars of the record are blanks.