Input file: plots

General syntax rules

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:

  1. The header commands
  2. 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: 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

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.


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

     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