The XSPEC Parser

Basics

The parser routines provide a general, easy interface between a program and the user, particularly for command-driven or other highly interactive programs. The basic cycle begins with the user inputing a line (optionally after some prompt) on the terminal. This line then can be analyzed by the program as a string of arguments. The program then can try to interpret each argument as a number or as a character string. Character strings can be checked if they are one of an allowed list of options. The actual details of how a line is interpreted depend on the particular program and how it uses the various parser facilities. An example of an input line might be:

Foo , 4.7 "Some information" - ! A comment

which is divided into three arguments: `Foo', `4.7' (which can be interpreted as a number), and ``Some information."

When parsing an input line, there are several special characters:

blank	( )	(an horizontal tab is also a blank)
comma	(,)
special delim.	($\mid$)	(the vertical bar)
comment char.	(!)
begin quote	(")	(Note, the begin and end quote are the
end quote	(")	same character by default, the ")

There are special characters whose interpretation depends on their position in the line:

"infinite skip"		/
continuation		-
end of file		/*

Delimiting arguments

When parsing a line for an argument, initial and trailing blanks are ignored. In addition, an argument field is delimited by a comma, or some of the special characters (particularly the comment, end of input, special delimiter characters). If an argument has no non-blank characters before a delimiter is reached, the argument is said to be an empty, null, or skipped argument. Conventionally, an empty argument is to be treated as indicating some default value. For example:

foo	! is a line consisting of a single argument `foo'.
foo bar
foo,bar
foo bar
foo, bar
foo , bar	! are all lines with two arguments `foo' followed
foo|bar	! by `bar'.
foo	! have two initial empty arguments followed by
foo	! `foo'.
bar,,foo	! has `bar', an empty argument and `foo'.

Comments

When looking for arguments, the comment character is treated logically as the end of the line. Thus, any following characters are ignored (and can be used as a comment). Thus, the line

foo ! bar	! has a single argument `foo' followed by a comment.
	! Comment strings cannot be read by the program.
,	!a comment ! has two empty arguments before the comment.

Quotes

If a user wishes to input an argument that contains a blank, comma, comment character, special delimiter, etc., then the argument should begin with the begin quote (") character, and have an end quote (") character at the end. Reaching the end of the input line is equivalent to having the end quote character. If you want to have the string include the end quote character, then you should double the character (similar to the way that FORTRAN handles character strings with embedded single quotes). By default, the begin quote and end quote characters are the same (the ASCII double-quote: " ). For example:

"This argument contains blanks"
"This argument ends with a single """," followed by a 2nd argument"
"The initial "" allow the words following the ! to be read"
" A final "" is optional for the last argument

  
The infinite skip character: /

The function of some characters depends on their location in the input line. For example, if the infinite skip character (/) is the last non-blank character on the line, or the last before the comment character, it is treated as a character delimiter, similar to a comma. In addition, it is equivalent to an infinite series of skipped or empty arguments existing before the end-of-line condition is raised. This treatment is mostly for compatibility with the standard FORTRAN List Directed I/O standards where a slash (/) indicates that all remaining arguments of a read are to retain their current values. If the character is placed anywhere else in the line, it is just an ordinary character and will be treated as part of an argument. Examples of lines that use the infinite skip character:

Foo, bar, bletch	/
Foo bar bletch,/
Foo bar bletch/	! a comment after the infinite skip char

all have three non-empty arguments, followed by infinite skips. In the following cases the slash is NOT treated as an infinite skip character:

file/device	! This is a single argument `file/device'
foo/,	! This is a single argument `foo/'
"foo/"	! As is this.

   
The continuation character: -

If the continuation character (-) is the last non-blank character on a line, or the last before the comment character, then the next line of input will be treated as logically concatenated to the current line. For terminal input, the user will receive a prompt ``->" indicating that the line is treated as a continuation. Note that the continuation character is NOT a delimiter, and thus must be separated from any earlier argument by a blank or some other delimiter. Examples:

These two lines -
are really one line !with 7 arguments
This line is not concatenated- !the 5th argument is "concatenated-"
with the next.
Even if you concatenate -!you are allowed to have comments
on each input line ! this was equivalent to an 8 argument line.

Because of the way continuations are processed, the user may not see the prompt until the program processes the last argument on the line. Thus, the type-ahead for the continuation may be `invisible'.

   
The terminator: /*

When a user inputs a line, the first few characters are checked for the EOF string, /*, which denotes the end of a read.

For example:

/*  ! This is a generated EOF
 /* ! This is a single argument input string "/*".

Matching keyword arguments

A common type of argument that a program might expect would be a character string that is matched against a list of possible keywords, such as a list of commands to tell the program what to do next. In general, case is not significant for such matches, (i.e., `KEYWORD' would match `keyword'). Also, partial matches are usually allowed, (i.e., `key' is a partial match to `keyword'. If the list of allowed matches includes two such partial matches, then usually the first in order is taken. For example if the match-list is (`keyword',`keyhole',...) then `key' matches `keyword'. Of course, any exact match takes precedence, in (`keyword',...,`key') then `key' matches `key'.

The particular program in use may modify any of these conditions individually. Case may be made significant, partial matches may be disallowed, or, if allowed, then only unique partial matches (so that `keyh' would be necessary for a legal argument matched against the list (`keyhole',`keyword',...) ).

Some programs will use a special-choice subroutine, which will prompt a user to input a single argument that will be compared with a list of choices. An example of such an interface might be as follows:

Please choose a keyword: (default)

where the string in parentheses is returned as the default if the user just returns an empty line. If the user returns a ?, then a list of all the legal options will be displayed. An EOF should be handled by the program as an exceptional reply (e.g., to revert to a previous stage of the program).

An even more special case is when the user is prompted to provide an answer to a question:

 
Do you know how to respond to this? (y)

In these cases, the possible answers are `yes' and `no'. Again, the default value is in the parentheses.