Language Syntax

Delimiters
As mentioned above, TSL is line oriented. Keywords and parameter values are separated by white space (i.e., one or more blanks or tabs) and newline characters. Blank lines are ignored by the parser as are internal comments. Internal comments begin with the '#' character and continue to the end of the line unless the '#' character appears within a quoted string.

Minimum Requirement
A submission file must define at least one track. Each track must define at least one action. An action can be specified explicitly with an ACTION or ACTION_LIST block or it can be defined implicitly with a TRACK or TRACK_LIST block that is not directly followed by an ACTION or ACTION_LIST block.

Block Keywords
Block keywords must be specified one per line and define the beginning of a logical block which continues until another block keyword or end-of-file is encountered. They have no associated value fields.

After each block keyword there MUST be at least one parameter keyword/value pair before another block keyword is encountered.

The legitimate sequences for blocks are defined as follows, where blocks in brackets are optional (the indentions below are for display purposes only and are not required by or have any meaning in the language):

[ COMMON ]
    [ GROUP ]
        TRACK or TRACK_LIST
            [ACTION or ACTION_LIST]

Any number of variants of the sequences above may be concatenated to form a legitimate submission file.

Parameter Keywords
For the standard blocks -- COMMON, GROUP, TRACK and ACTION -- parameter keyword/value pairs must appear on a single line with the keyword appearing first (after optional white space) followed by white space then the parameter value. Note that whitespace is NOT allowed in any parameter value unless it is a double quoted string. For example:

EXP	1200
DEC	+12:05:36.7
NOTES	"This argument contains white space and must be enclosed in double quotes."

For the list blocks, TRACK_LIST and ACTION_LIST, parameter keywords are placed on a single line where keywords are separated by white space. Values for the list block parameters are then placed on subsequent lines separated by white space. Here are two examples from different submission files:

TRACK_LIST
	OBJECT	RA	DEC	MAG	PRI	EXP	VISITS
	mytarget	12:12:12.12	+13:12:12.1	12	1	1200	2
	mystandard	12:12:12.12	+13:12:12.1	13	2	1300	3

ACTION_LIST
	GASCELL	TYPE	EXP	COMMENT
	0	Sci	1200	"This is the gas cell out exposure"
	1	Sci	1200	"This is the gas cell in exposure"
	1	hrsff	5	"This is my flat with the gas cell in "

Parameter Scope
Recall that the block types are hierarchical. A parameter defined in a given block retains its value within the scope of the block unless locally overridden within a sub-block. For example, if the gascell parameter, GASCELL, were set to 1 in a TRACK block, then all actions within that block would use a GASCELL value of 1 unless a value for GASCELL 4 was explicitly defined within one of the ACTION blocks. So in the following example the first and third actions inherit a GASCELL value of 1 from the preceding TRACK block while the second action overrides that value by setting GASCELL to 0.

TRACK
	OBJECT	NI_748
	RA	12.12.12.12
	DEC	+13:12:12.1
	GASCELL	1
ACTION
	EXP	400
	CRSPLIT	2
ACTION
	EXP	500
	CRSPLIT	2
	GASCELL	0
ACTION
	EXP	600
	CRSPLIT	1

In any given submission file, parameter values for a given block persist until one of two conditions exists: 1) they are overridden with a subsequent declaration inside the same sub-block, or 2) another block of the same or higher position in the hierarchy is encountered.

Default and Required Values for Parameters
The majority of parameters have predefined default values. The default values for these parameters were guided by an analysis of one year's worth of HET plan.db entries.

Of course many of the parameters, which have no default value, are required for all target submissions, such as program name, RA and DEC. Others are instrument dependent, such as FILTER, which is has default values for HRS and MRS but not for all LRS grisms.

The PI does not have to specify any parameter in a submission file that is not required or if it has a default value. This allows for very simple submission files. For example, the following target submission file defines a single track with three actions: