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.