Input file: plots

General syntax rules
plot... end_plot
title
Input streams
Macros

General syntax rules

The input file is free-format; white-space characters (space, newline and tab) can be used freely. Items such as keywords and explicit values must be separated by at least one white-space character.
Comments begin with an exclamation-mark '!' and continue until the end-of-line. Comments are skipped by MolScript and have no effect.
Input lines can be any length. Single items (keywords, strings) can be at most 2047 characters long. Quoted strings (delimited by the '"' character) must be finished on the same line. A quoted string cannot contain a newline character.
The semi-colon character ';' is used as a command terminator in MolScript. All commands end with this character.
No keywords can be abbreviated, they must be spelled correctly, and must be in the correct character case (i.e. trace is a valid command, while Trace is not).

In the previous versions of MolScript (v1.4 and older) an integer could not be used when a floating-point value was specified, and vice versa. This restriction has been removed.

Note that the keywords encapsulated and raster3d, which in previous versions of MolScript (v1.4 and older) could be used before the first plot, are no longer valid. The choice of output mode now has to be made by supplying the proper command-line option.

A parser generated by the yacc program (Levine et al., 1992) from the molscript.y file is used to process the input file in MolScript.

plot... end_plot

An image is specified by the commands given between the plot and end_plot keywords. See the minimal input file for an example. The only items that may appear outside of these keywords are the title item and the macro definitions.

Conceptually, the commands within the plot... end_plot keywords are grouped into two sections:

The header commands
The general commands

The header commands define some overall characteristics of the image, and can be given only at the top of the plot specification. The general commands include all coordinate handling commands, the graphics commands and the graphics state change commands set, push and pop. The general commands may occur in any order after the header commands.

For the PostScript output mode, more than one plot... end_plot blocks are allowed in one input file, which results in more than one image on the paper. The header command area must be used in this case to specify where on place the images on the paper, or else the last image will simply obliterate the previous ones.

title string

Output a title to the plot. The actual effect depends on the output mode:

PostScript: A title comment is written in the file, which has no effect on the printed image.
VRML 2.0: The title string in the WorldInfo node is set, which may or may not have a visible effect depending on the VRML browser.
OpenGL: The title is used as the name for the display window.
There is no effect at all for the Raster3D or image file modes.

Note that this item must be given before the first plot keyword, and can appear only once in an input file.

Note that there is no semi-colon ';' after this item.

Input streams

MolScript initially reads its input from stdin (standard input) or the file specified by the command-line option -in. There is a mechanism by which the input source can be changed to another file. This file is read until it has been exhausted, at which point the reading of the original input file resumes.

This change of input stream file is accomplished with the item

   @filename

where the character '@' indicates that the rest of the item is a file name.

Note that there is no semi-colon; this input stream item is not part of the ordinary syntax of the MolScript input file. Rather, it is a special item that only affects the source of the input.

This facility makes it possible for a complicated image specification to be split up into several files. For example, if the structure to be plotted must be composed by several read, copy and delete statements, then this can be done in a separate file. This file is then referred to using '@' and the graphics commands given separately afterwards. In this way, several different input files using the same coordinate setup can be made easily, with a guarantee that the coordinate sets are identical in the different images.

The input stream can be changed in a nested fashion, one file referring to another, to any depth.

Macros

A macro is a block of input text that is referenced by a name (or symbol). In MolScript a macro is defined by the keywords macro and end_macro:

     macro macroname
        whatever
     end_macro

The first item after the macro keyword is the macro name (or symbol). Everything else between macro and end_macro is stored as text, without interpretation. The text will be interpreted only when and if the macro is called.

Macro definitions can be placed just before a plot, or as an ordinary command. A macro definition cannot be placed among the header commands. If placed before a plot, then there must be no semi-colon ';' after the keyword end_macro. If placed among the ordinary commands, there must be a semi-colon ';' after the keyword end_macro. The macro definition is kept in memory until the end of execution of the current input file. It cannot be modified once it has been created. Macro definitions cannot be recursive.

A macro is called by giving the macro name preceded by a dollar character '$'. There must be no blank between the dollar character '$' and the macro name. That item will be substituted by the contents of the macro, which will then be interpreted as usual. Similarly as for an input stream file, this item is not part of the ordinary syntax of MolScript. Instead it can be seen as a way to change the input source, basically in the same way as the input stream feature. When the end of the macro has been reached, the input is resumed from after the macro call. Macros may call each other, and may also change input stream files.

As an example, here are two fragments of input files which would produce identical results:

! ----- variant 1, without macro -----

     cpk either require in type ALA and atom CB,
                require in type THR and atom CG2,
                require in type VAL and atom CG*,
                require in type ILE and either atom CD1 or atom CG2,
                require in type LEU and atom CD*
             or require in type MET and atom CE;


! ----- variant 2, with macro -----

     macro methyl-sel
         either require in type ALA and atom CB,
                require in type THR and atom CG2,
                require in type VAL and atom CG*,
                require in type ILE and either atom CD1 or atom CG2,
                require in type LEU and atom CD*
             or require in type MET and atom CE
     end_macro;

     cpk $methyl-sel;

Note that the semi-colon ';' character is left out in the macro. Instead, it is added after the macro call. The reason for this is that the 'methyl-sel' macro can then be used as a part of some other selection expression.

It may be useful to store the definitions of commonly used macros in separate input stream files, which may be read in at the top of MolScript input files which use them. For instance, libraries of reusable macros for commonly used residue or atom selections may be created.

Top page