Section 5.3.2.1.2. Options to vcif

A number of options may be supplied as command-line arguments to modify the output from vcif.

A more complete account is given of each error on its first occurrence when the program is invoked with the `-v' option. The output listing explains in more detail what the breach of syntax is and sometimes suggests how misunderstandings of the file structure result in such breaches (Fig. 5.3.2.2).

Figure 5.3.2.2 | top | pdf | Verbose error listing from vcif when run with the `-v' option on the example of Fig. 5.3.2.1.

Each error message is prefaced by the word `ERROR' (or occasionally another phrase such as `WARNING' or `STAR ERROR'). Three chevrons preface a printout of the beginning of the troublesome line. Then an expanded description of the error is given, prefaced by three asterisks, on the first occurrence of each distinct error. In this mode, only the first 20 errors are listed (the assumption is that this mode is best suited to novices, who should identify and correct each error in turn and would not want to be swamped by large numbers of error messages arising from a single error). More errors may be reported by using the `-e' command-line option.

The quiet option (vcif -q) outputs no error messages but instead returns to the calling environment an integer giving the total number of errors found. This option allows scripts or external programs to use vcif as a silent test of whether a file has any syntax errors. A related option, vcif -b, counts errors and returns the result as an integer to the calling environment, as in the previous case; but additionally outputs a list of all the data-block codes in the file. While adding nothing to the syntax-checking function of the program, this provides a useful small utility for simply listing data-block names.

Although intended for use with the restricted STAR File syntax permitted for CIF (Chapter 2.2 , vcif may also be used with the `-s' option to check the syntax of CIF dictionary files, which may include save frames. The program does not, however, handle nested loop structures.

The program will flag as an error any line of greater than 80 characters length (the original limit in the CIF version 1.0 specification; see Chapter 2.2 , but this behaviour may be overridden with the `-l' option. If used, only lines longer than the specified number of characters will be reported and the reports of such lines will be prefaced with the word `WARNING'. Likewise, the `-w' option may be used to override the CIF version 1.0 restriction of data names and data-block codes to 32 characters.

Other options allow the program to write extensive debugging information to a user-specified file, indicating its internal state upon processing each token of input, and to list either a brief summary of how it may be used or its current version number.