Formal Template Syntax

    TEMPLATE = BLOCK [ BLOCK ... ]

       BLOCK = { HDU | GROUP }

       GROUP = \GROUP [ BLOCK ... ] \END

         HDU = XTENSION [ LINE ... ] { XTENSION | \GROUP | \END | EOF }

        LINE = [ KEYWORD [ = ] ] [ VALUE ] [ / COMMENT ]

    X ...     - X can be present 1 or more times
    { X | Y } - X or Y
    [ X ]     - X is optional

At the topmost level, the template defines 1 or more template blocks. Blocks can be either HDU (Header Data Unit) or a GROUP. For each block the parser creates 1 (or more for GROUPs) FITS file HDUs.

The start of an HDU definition is denoted with a template line containing either of the following keywords:

'SIMPLE' : begins a Primary array (PHDU) definition. One per template is allowed and only as a first keyword in the template file. If not present then an empty PHDU is created (of size 2880 bytes) and the first HDU defined in template files is saved as a 2nd HDU (first after dummy one).

'XTENSION' : begins any xtension HDU definition.

The end of an HDU definition is given by the next occurance of an 'XTENSION' keyword, a group or end directive, or the end of the template file.

The start of a GROUP definition is denoted with the group directive, and the end of a GROUP definition is denoted with the end directive. GROUP contains 0 or more member blocks (HDUs or GROUPs). Member blocks of type GROUP can contain their own member blocks. The GROUP definition itself occupies one FITS file HDU of special type (GROUP HDU), so if a template specifies 1 group with 1 member HDU like:

\group
grpdescr = 'demo'
xtension bintable
# this bintable has 0 cols, 0 rows
\end

then the parser creates a FITS file with 3 HDUs :

1) dummy PHDU
2) GROUP HDU (has 1 member, which is bintable in HDU number 3)
3) bintable (member of GROUP in HDU number 2)

Technically speaking, the GROUP HDU is a BINTABLE with 6 columns. Applications can define additional columns in a GROUP HDU using TFORMn and TTYPEn (where n is 7, 8, ....) keywords or their auto-indexing equivalents.

For a more complicated example of a template file using the group directives, look at the sample.tpl file that is included in the CFITSIO distribution.