Writing and using INCLAN macros

A powerful feature of INCLAN is the ability to create new commands from existing ones by combining them in macros. A macro is created by saving a sequence of commands into a file with the extension “.cya”. It can be invoked in the same way as existing commands simply by typing its name.

Suppose that we want to build a macro to perform a protein structure calculation, given the sequence of the protein and a file with upper distance bounds. The macro shall be called “calculate” (i.e. it is stored as a file called “calculate.cya”) and have two parameters, the file name of the input and output files and the number of structures to calculate. A first implementation is:

cyanalib               # read standard residue library file
read seq $p1.seq       # read protein sequence file
read upl $p1.upl       # read upper distance limit file
calc_all $p2           # calculate a group of conformers
overview $p1.ovw       # produce an overview table of the calculation
write pdb $p1.pdb all  # save all resulting structures in a PDB file

$p1 and $p2 represent the values of the two command line parameters. To calculate 10 conformers of a protein whose sequence is given in the file “demo.seq” and the upper distance bounds are stored in the file “demo.upl”, the “calculate.cya” macro is called as follows (“cyana>” is the prompt of the program CYANA):

cyana> calculate demo 10

A second implementation of the “calculate.cya” macro uses the INCLAN command syntax to declare an interface with names and, possibly, default values of the command line parameters:

## calculate - calculate a group of structures
## Usage: calculate file=<file> [structures=<n>]

syntax file=* structures=@i=10

cyanalib
read seq $file.seq
read upl $file.upl 
calc_all $structures
overview $file.ovw
write pdb $file.pdb all

Now, the two parameters are available inside the macro as variables with the names file and structures, respectively. The asterisk “*” in the syntax command indicates that the value of the file parameter can be any character string, whereas the type specification @i restricts the parameter structures to have only integer values. The parameter structures has a default value of 10. There is no default value for the parameter file, i.e. this parameter must be specified by the user. All of the following calls of the calculate command are equivalent:

calculate demo 10                  # unnamed positional parameters
calculate demo                     # use default value for parameter structures
calculate file=demo structures=10  # use named parameters
calculate structures=10 file=demo  # named parameters can be used in any order
calculate demo stru=10             # parameter names can be abbreviated

The following calls of the calculate command are errors that will be detected by INCLAN:

cyana> calculate                   # missing mandatory parameter
*** ERROR: Missing parameter "file".
cyana> calculate demo 10 50        # too many parameters
*** ERROR: Illegal parameter "50".
calculate 10 demo                  # wrong data type for an integer parameter 
*** ERROR: Illegal value "demo" for parameter "structures".
calculate id=demo structures=10    # wrong parameter name
*** ERROR: Unknown parameter name "id".

Lines at the beginning of a macro file that start with “##” are special comment lines that will be displayed by the on-line help system:

cyana> help calculate
    calculate - calculate a group of structures
    Usage: calculate file=<file> [structures=<n>]

In this way it is possible to include on-line documentation directly into a macro file.