11.3 Template Parser Directives

In addition to the template lines which define individual keywords, the template parser recognizes 3 special directives which are each preceded by the backslash character: \include, \group, and \end.

The 'include' directive must be followed by a filename. It forces the parser to temporarily stop reading the current template file and begin reading the include file. Once the parser reaches the end of the include file it continues parsing the current template file. Include files can be nested, and HDU definitions can span multiple template files.

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. Each 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.