SPDBV scripting language user guide.
===================================================================
The parser of SPDBV scripting language has been generated with
flex and yacc, whose combination allows to build very advanced
parsers.
The scripting language will be quite familiar for persons
who know C or perl. The scripting language supports
variables, conditionnal branching, loops, arrays and file access.
Subroutines are also supported, but you must be aware that all
variables are global. Despite this limitation, it allows to
make the scripts more compact and readeable, and can also be
used to prepare a kind of "jump table" of your favourite
functions that can be executed simply by clicking on their name
from the SPDBV interface or from added menus.

The scripts can be stopped at specific points to let
users interact with the graphical interface before
resuming operation. This allows among other things to
access commands not directly available from the script,
take parameters from the user input, or execute other
script commands not included in the script by typing
them directly from the "Execute script command" item of
the Edit menu.

Scripts can be either loaded as TEXT file (with the
open TEXT item of the file menu) or with the "Run Script"
item of the file menu.
On unix systems, scripts can be passed as the last
parameter of the command line (after optional PDB files).

The place to post and exchange scripts is on the
spdbv mailing list maintained by Prof. Gale Rhodes at
http://www.usm.maine.edu/~rhodes/SPVTut/text/DiscuSPV.html
===================================================================
As we all like to be polite, scripts must start with please do
and end with thank you.
all instructions are terminated with a semicolon.
all information following a # is ignored untill the end of the line.

===================================================================
Data Types:
===================================================================

In the manual, data types appear between <>.
These means that a value of the mentionned type is expected
(or returned). This value can be obtained from a variable, or
provided directly.

Supported types are:

vector            example: <1.0,1.0,1.0>
float             example: 1.0
int               example: 42
string            example: "Hello World!"

layer             example: "1CRN" (alternately, layers can be
                           referred to by position the first layer 
					  loaded is 0 the second 1, etc.
selection         example: select in <layer> pos <int> to <int>;
file              example:
internal variable example: gCurrentOS

===================================================================
Data Types:
===================================================================

There are two types of variables:
script variables (that can be used to store values in scripts)
and program variables (internal spdbv variables).

assigning a value to a variable is done with 
$varname = value;
data types for variables is attributed implicitely during the
assignment.

$X = 1.0; will assign the value 1.0 of type <float> to $X.
$X = 1;   will assign the value 1 of type <int> to $X.

operations on variables are (usually) possible only
between variables of the same type, but you can force
a value to be of a different type through typecasting.
for example:

$X = (float)1; will assign the value 1.0 of type <float> to $X.

valid typecast are:

(int)
(float)
(string)

===================================================================
Arrays:
===================================================================

Currently, only arrays of <int> <float> and <vector> are supported.
The syntax is the following:

$X[<int>] = value;

The type of array is automatically determined by the kind of value
you put into it the first time.
Memory is allocated dynamically and will only be released
when a 'thank you' statement is reached: if you want to
get back something (memory), you better be polite ;-)

===================================================================
Operations:
===================================================================

it is possible to add, substract, multiply or divide data types.
Some operations are of course not possible (multiplying two strings
or two atom selections).
Adding two strings will produce a concatenation.

$X = "Hello" + " World!"; is equivalent to $X = "Hello World!";

In the case of vectors, multiplication is scalar if one of the member
is of type <float>:
$X = <1.0,1.0,1.0> * 3.0;  will put <3.0,3.0,3.0> into $X.

or performs a dot product if the operation involves two vectors.
the scalar product can be obtained with the 'X' operator:

$X = <0.0,1.0,0.0> X <0.0,0.0,1.0>;

floating point and integer variables can be
pre/post incremented with ++<var> and <var>++ respectively,
or pre/post decremented with --<var> and <var>-- respectively.
This is mainly used for loops.

The remainder (modulo) of an integer diviision can
be accessed by the % operator as in

	print 8 % 3;  

which would give 2

===================================================================
Commands: (alphabetically)  PRELIMINARY for version 3.7b1
                            all commands might not be implemented
					   on all platforms.
					   More commands will be added as needed
===================================================================

You can find several scripts examples in the scripts directory
of the SPDBV distribution. Scripts are named very originally
script01.txt script02.txt etc.
For each of the following commands, it is mentionned in which
example script you can find it.
The scripts are designed to progressively introduce more
and more features and an other way to learn this language is
to study the scripts starting from script01.txt
-------------------------------------------------------------------
access

will get the relative accessibility of a residue X, compared
to a 100% ref value being computed in an extended conformation
in the pentapeptide GGXGG

access(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

access(<layer>,<int>)

returned value is of type <float>.

related commands: name res ss access
Demonstrated in example script:  11
-------------------------------------------------------------------
acos

compute the arc cosine of an expression.

acos(<float>)

values are in radians

related commands: sin asin cos tan atan PI
Demonstrated in example script:  none
-------------------------------------------------------------------
angle

compute the angle AOB between three atoms (vectors).

<floatvar> = angle(A,O,B);

where A,O and B are <vector> values
Result is returned in degrees.

related commands: dist get torsion
Demonstrated in example script:  none
-------------------------------------------------------------------
align

will make a primary sequence alignment between layers.

align <layer> onto <layer>;


where <string> contains the question to be presented to the user.
related commands: if
Demonstrated in example script:  none
-------------------------------------------------------------------
align_pos

will get the position of a residue in an alignment (in
the align window).

align_pos(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

align_pos(<layer>,<int>)

returned value is of type <int>.

related commands: "generate structural alignment" superpose rms fit
Demonstrated in example script:  none
-------------------------------------------------------------------
asin

compute the arc sinus of an expression.

asin(<float>)

values are in radians

related commands: sin cos acos tan atan PI
Demonstrated in example script:  none
-------------------------------------------------------------------
ask

will make a dilaog (yes,no) appear for user feedback.

$int_varname = ask <string>;


where <string> contains the question to be presented to the user.
related commands: if
Demonstrated in example script:  08 and 10
-------------------------------------------------------------------
atan

compute the arc tangent of an expression.

atan(<float>)

values are in radians

related commands: sin asin cos acos tan PI
Demonstrated in example script:  none
-------------------------------------------------------------------
build

add various objects such as amino acids, molecular surface.

build in <layer> molecular surface of quality <int>;

related commands: delete
Demonstrated in example script:  none
-------------------------------------------------------------------
center

center view on a selection or on visible groups.

center on <selection>;
center on visible;
Demonstrated in example script:  05 09 13
-------------------------------------------------------------------
chain

will get the chain name of the first selected group found
in a selection.

chain(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

chain(<layer>,<int>)

returned value is of type <string>.

related commands: name res ss access
Demonstrated in example script:  11
-------------------------------------------------------------------
color

color some parts of the view.
This is functionnally equivalent to the color column of the control panel.

color [in <layer>] <part> of <selection> by <vector>;
color <part> of <selection_variable> by <vector>;
color <part> of <selection_variable> in <color>;

when in <layer> is omitted, the current active layer is amumed.
where <part> can be any combination of
res,side,label,surface,ribbon,vdw
<vector> is a rgb color (with intensity of each component
are between 0.0 and 1.0.
<color> is any of the predefined kyewords:
 red green blue yellow white black grey cyan orange purple
 
example: color in "1crn" ribbon of res "F","N" by <1.0,0.0,0.0>;

related commands: hide show
Demonstrated in example script:  05 13
-------------------------------------------------------------------
compute

performs various computations on a protein

compute in <layer> electrostatic potiential using "[coulomb|pb]" with "[partial|full]" charges;
compute in <layer> hbond;
<floatvar> = compute in <layer> energy;

related commands: discard minimize
Demonstrated in example script:  07 and 09
-------------------------------------------------------------------
clear               ** USEFUL but DANGEROUS **

clear a file on disk.

clear file <string>;  

(where <string> is a variable that contains a filename).

related commands: open close readln
-------------------------------------------------------------------
close

close a layer or a file.

close <layer>;  
close file <file>;

(where <file> is a variable that contains a file previously open).
related commands: open clear readln
Demonstrated in example script:  02 03 and 04
-------------------------------------------------------------------
cos

compute the cosine of an expression.

cos(<float>)
cos(<int>)

This returns the value in radians

related commands: sin asin acos tan atan PI
Demonstrated in example script:  none
-------------------------------------------------------------------
delete

delete selected residues, or hydrogens from a layer.

delete <selection>;
delete in <layer> hydrogens;
delete in <layer> molecular surface;
delete in <layer> electrostatic potential;

related commands: build
Demonstrated in example script:  none
-------------------------------------------------------------------
dist

compute the distance between two atoms (vectors).

<floatvar> = dist(<vector>,<vector>);

related commands: angle get torsion
Demonstrated in example script:  07
-------------------------------------------------------------------
export

this command allows to save images or pov-ray scenes.

export image as <string>;
export stereo image as <string>;
export pov as <string> [and render];

where <string> contains the filename with full path.

alternately, you can save the file in one of the predifined
directories [usrstuff|download|temp] with the following command

export pov in [usrstuff|download|temp] as <string> [and render];

see save for more explanations about path and filemames.
note that the [and render option] will open the file for rendering
on mac and pc, but will automatically launch pov on unix boxes
provided you save the scene in the usrstuff directory.
 
related commands: save
Demonstrated in example script:  09
-------------------------------------------------------------------
fit

this command is equivalent to the fit (from selection) command of spdbv.

fit <layer> onto <layer> using <string>;

where <string> contains the method to be used ("CA", "backbone", "all").
related commands: rms superpose 
Demonstrated in example script:  none
-------------------------------------------------------------------
generate structural alignment
related commands: rms superpose fit
Demonstrated in example script:  none
-------------------------------------------------------------------
get

can access internal spdbv variables or atomic coordinates,
retrieve aa sequences, or capture the current selection status
of a specific layer (when modified directly from the graphical
user interface).
The list of internal variables that can be accessed is
provided at the end of this guide.

$sel = get selection of <layer>;
$varname = get <internal variable>;
$vector_varname = get coord <string> of <selection>;
$string_varname = get seq of <selection>;

where <string> contains the 4 characters atom name (for. ex " CA ")
and selection a selection.
related commands: set
Demonstrated in example script:  07 08 09 and 10
-------------------------------------------------------------------
goto

one of the most useful (and controversal although it is one
of the rare commands to be wired directly on any chip...)
command that allow to continue the execution from a different
point of the script. 

goto <label>;

Execution will continue immediately after <label>, which must end with
a colon.

example:  goto elsewhere;
          elsewhere: print "welcome";

related commands: sub do while return
Demonstrated in example script: none
-------------------------------------------------------------------
groupcount

will return the number of groups in a layer.
This is functionnally equivalent to a select all followed
by a selcount, athough it is quicker.

$int_varname = groupcount of <layer>;

related commands: selcount
Demonstrated in example script:  02 03 and 04
-------------------------------------------------------------------
hide

hide some parts from the view.
This is functionnally equivalent to the control panel.

hide <part> of <selection>;
hide in <layer> <part> of <selection>;

where <part> can be any combination of
res,side,label,surface,ribbon,vdw
related commands: show color
Demonstrated in example script:  06
-------------------------------------------------------------------
inline>
text
<inline

This is used in conjunction with the open command to
load PDB files directly embedded in the script, which
is useful mostly for web servers that need to return
a script+pdb file in a single file.

example:
open pdb INLINE>
ATOM      1  N   THR     1      17.047  14.099   3.625  1.00 13.79
ATOM      2  CA  THR     1      16.967  12.784   4.338  1.00 10.80
ATOM      3  C   THR     1      15.685  12.755   5.133  1.00  9.19
ATOM      4  O   THR     1      15.268  13.825   5.594  1.00  9.85
ATOM      5  CB  THR     1      18.170  12.703   5.337  1.00 13.02
ATOM      6  OG1 THR     1      19.334  12.829   4.463  1.00 15.06
ATOM      7  CG2 THR     1      18.150  11.546   6.304  1.00 14.23
<INLINE;

related commands: open
Demonstrated in example script:  none
-------------------------------------------------------------------
is_selected

is_selected(<layer>,<int>)
is_selected(<int>)

When <layer> is omitted, the current active layer is used.

returned value is of type <int> and is 1 if the group is selected
and 0 otherwise.

related commands: 
Demonstrated in example script:  11
-------------------------------------------------------------------
layername

will return the <string> value of the layer name

<string_var> = layername of <int>

where int is the relative position of the layer from the first loaded
which is number 0, of course.

related commands: 
Demonstrated in example script:  none
-------------------------------------------------------------------
max

will return the max value of two numbers or variables.

max of (<float>,<float>);
max of (<int>,<int>);

related commands: min
Demonstrated in example script:  none
-------------------------------------------------------------------
min

will return the min value of two numbers or variables.

min of (<float>,<float>);
min of (<int>,<int>);

related commands: max
Demonstrated in example script:  none
-------------------------------------------------------------------
minimize

performs an energy minimization using n cycles of steepest descent

minimize <selection> of <layer> with <int> cycles;

related commands: compute
Demonstrated in example script:  07
-------------------------------------------------------------------
move

move a selection.

move <selection> by <vector>;

where <vector> contains the translation in angstroms.

related commands:  zoom rotate
Demonstrated in example script:  09
-------------------------------------------------------------------
mutate

will mutate an amino acid to another.
It is currently not possible to browse the rotamer library
in a script.

mutate <selection> to <string>;

where <selection> must contain one valid amino acid (first selected is taken)
and <string> contains the one letter code of the new residue.

related commands: -
Demonstrated in example script:  none
-------------------------------------------------------------------
name

will get the three letter name of the first selected group found
in a selection.

name(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

name(<layer>,<int>)

returned value is of type <string> for ex: is 'ALA' or 'ATP'.

related commands: num res chain ss access
Demonstrated in example script:  11
-------------------------------------------------------------------
normalize

will normalize a vector.

normalize(<vector>)

returned value is of type <vector>.

related commands: vector operations.
Demonstrated in example script:  none
-------------------------------------------------------------------
num

will get the number of the first selected group found
in a selection.

num(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

num(<layer>,<int>)

returned value is of type <int>.

related commands: name res chain ss access
Demonstrated in example script:  11
-------------------------------------------------------------------
omega

will get the omega peptidic bond torsion angle for the first
selected amino acid found in a selection.

omega(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

omega(<layer>,<int>)

returned value is of type <float> and is returned in degrees.

related commands: phi psi ss
Demonstrated in example script:  none
-------------------------------------------------------------------
open

load a pdb file in the workspace (next available layer).

open [pdb] from "disk|net" <string>;   
note that it is possible to omit "pdb" as it is the default value.

<string> contains the full filename (see below).

- - - - -
The filename must be the absolute path of your file.
Unix users will enderstand what I mean, but Mac users might
be a little confuse. A full path (on Mac) is constructed as follows:

name_of_disl:name_of_folder:name_of_subfolder:name_of_subsubfolder:filename

for example, assume you store your pdb files in a folder named 'pdb'
located in the 'System' disk. You can access the file '1crn.pdb' like this:

System:pdb:1crn.pdb

As you can see, Mac uses ':' as separator.
This is of course different for unix which uses '/' and from windows
which uses '\'.
In order to make your scripts as portable as possible, I would
recommend separating the file name from the path,
which will let you (or other users) change just the path (one line)
to make a generic script run on thieir machine.

consider this example:

open "System:pdb:1crn.pdb";
open "System:pdb:1atp.pdb";

it is better rewriten like this:

$path = "System:pdb:";   # change this line to point to your pdb files directory.
open $path + "1crn.pdb";
open $path + "1atp.pdb";

Alternately, to be cross platform, you
can also use one of the predetermined directories:

open [pdb] from usrstuff <string>;
open [pdb] from temp <string>;
open [pdb] from download <string>;

see below for explanation
- - - - -


This command also allows to create files or open arbitrary text files
for further processing. 


or allows to open a file as read-only.

$file_varname = open file <string>;
$file_varname = open file <string> for reading;

or allows to open a file as write  (CAUTION WHEN USING THIS!).

$file_varname = open file <string> for writing;

or allows to append to a file  (CAUTION WHEN USING THIS!).

$file_varname = open file <string> for appending;



In fact, using the full path of your file (directories+filename)
is potentially dangerous if for sonme reason the
filename get screwed up. Besides, it is not cross-platform
and you likely wish to have your scripts running everywhere, 
I suggest that you and work with files store the files in your 'usrstuff' directory
using the following equivalent commands:


$file_varname = open file <string> in usrstuff;
$file_varname = open file <string> in usrstuff for reading;

or allows to open a file as write  (CAUTION WHEN USING THIS!).

$file_varname = open file <string> in usrstuff for writing;

or allows to append to a file  (CAUTION WHEN USING THIS!).

$file_varname = open file <string> in usrstuff for appending;


where <string> must *ONLY* contain the file name (no directory, no path)



The open command can also be used to open a text file, which
is only useful coupled with the graphical user interface.

open text <string>; 
open text <string> in usrstuff; 




open seq <string>;   

this can be used to load a raw sequence to model.
Sequence must be in format FASTA, SWISSPROT or SEQRES. 

related commands: close clear readln inline print save
Demonstrated in example script:  all
-------------------------------------------------------------------
pause

will stop the script execution for some seconds.

pause <float>;
related commands: stop 'thank you' 'please do'
Demonstrated in example script:  05 06 07 09
-------------------------------------------------------------------
phi

will get the phi torsion angle for the first selected amino acid
found in a selection.

phi(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

phi(<layer>,<int>)

returned value is of type <float> and is returned in degrees.

related commands: psi omega ss
Demonstrated in example script:  01 02 03 04
-------------------------------------------------------------------
PI

return the value of PI.

related commands: sin asin cos acos tan atan
Demonstrated in example script:  none
-------------------------------------------------------------------
please do

initiate a script, and reset all scripts variables.
Note that this statement must be on the FIRST line of the script.

related commands: stop pause 'please do'
Demonstrated in example script:  all
-------------------------------------------------------------------
print

prints a value (string, variable, number etc..) onto
stdout or in a spdbv communication dialog.

print on dialog;
print on stdout;
print on <file> <expression>
print <expression>;

where expression is any combination of aritmetic values or
concatenation of strings.
Note that a newline is printed after each print operation.
You might then need to prepare a string (from concatenation)
before printing.
Demonstrated in example script:  01 02 03 04 06 07 08 11
-------------------------------------------------------------------
psi

will get the psi torsion angle for the first selected amino acid
found in a selection.

psi(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

psi(<layer>,<int>)

returned value is of type <float> and is returned in degrees.

related commands: phi omega
Demonstrated in example script:  03 04
-------------------------------------------------------------------
readln

read the next line from a text file or from a dialog box.

$string_varname = readln from file <file>;
$string_varname = readln from user <string>;

where <file> is a file previously open with the open file command.
and <string> is a prompt that will appear in the dialog.

related commands: open close clear substring
Demonstrated in example script:  04 06
-------------------------------------------------------------------
redraw;

will force the main window to be refreshed.
Useful only in the interactive mode.
Demonstrated in example script:  05 07
-------------------------------------------------------------------
rename;

rename chain of <selection> as <string>;

will change the chain name of the selected residues.

rename <layer> as <string>;
will change the layer name

related commands:  renumber
Demonstrated in example script:  none
-------------------------------------------------------------------
renumber;

renumber <selection> from <int>;
renumber <selection> add <int>;

will change the residue number of selected residues.

related commands:  rename
Demonstrated in example script:  none
-------------------------------------------------------------------
res

will get the one letter name of the first selected group found
in a selection.

res(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

res(<layer>,<int>)

returned value is of type <string> for ex: is 'A' or 'C' or 'D',...

related commands: num name chain ss access
Demonstrated in example script:  11
-------------------------------------------------------------------
rotate

rotate the view successively around axis x,y,z:

rotate <vector>;
where <vector> contains rotation angles in degrees.

This command can also be used to rotate a selection around
a specific axis.

rotate <selection> by <float> [deg|rad] around axis <vector> <vector>;

or to do a torsion (rotate atoms downstream a bond around this
bond) using the following syntax:

rotate atoms of <selection> by <float> [deg|rad] around bond <string> <string>;

related commands:  zoom move
Demonstrated in example script:  05 06 09
-------------------------------------------------------------------
return

It will resume execution where it was before
entering the subroutine.
See sub for more explanations

related commands: goto do while sub
Demonstrated in example script:  08 10
-------------------------------------------------------------------
rms

this command is equivalent to the RMS command of spdbv.

rms of <layer> and <layer> using <string>;
<floatvar> = rms of <layer> and <layer> using <string>;

where <string> contains the method to be used ("CA", "backbone", "all").

related commands: fit superpose
Demonstrated in example script:  05
-------------------------------------------------------------------
save

save a all or part of pdb files from some layers.

save <layer> as <string>;  
save selection of <layer> as <string>;

(where <string> contains the full filename (see discussion in open).

an alternative set of commands that will
save files in predifined directories located under
the spddbv main directory is available.
Directories can be usrstuff,temp or download:

save <layer> as <string> in [usrstuff|temp|download];  
save selection of <layer> as <string> in [usrstuff|temp|download];

in this case <string> must contain *ONLY* the filename, as the directory is
implicit. This is very useful to make scripts portable among the
various OS supported (Windows, Macintosh, IRIX and Linux).

related commands: open
Demonstrated in example script:  06
-------------------------------------------------------------------
search   *This function is not yet available.*

allow to search 3D patterns in pdb files.

search in <layer> <string>;
search in <layer> <string> >> <string>;

where the first <string> contains the filename of the 3Dsearch pattern
description file, and the second (optional) string appends the
output to a file (that might be worth clearing before 
with the clear command).
Demonstrated in example script:  none
-------------------------------------------------------------------
selcount

will return the number of selected groups in a layer.

$int_varname = selcount of <layer>;

related commands: groupcount
Demonstrated in example script:  06
-------------------------------------------------------------------
select

allow to select specific residues and perform logical 
operations on them. This can then be used to color or hide
residues, among other things.

<var> = select [in <layer>] <selection>;
select <var>;

when [in <layer>] is ommitted, the current active layer is assumed.
where <var> must contain a selection
and <selection> can be any combination of:

all
none                
water hoh solvent h2o
strand
helix
het                  will select all HETATM               
aa                   will select all amino acids               
nt                   will select all nucleotides              
res   <string>       residue kind  example:  res "A", "C", "D"
name  <string>       residue name  example:  res "ALA", "OXT", "ATP"
chain <string>       residue chain example:  chain "A", " "
num   <int>          residue number
pos   <int>          residue absolute position in layer (start at 0).
pos   <int> to <int> residue range absolute position in layer (start at 0).
seq   <string>       a sequence (can be a prosite pattern).
within <float> of <selection_var>

example:

$sel1 = select in "1ATP" res "Y" and chain "I";
It is currently not possible to provide very complex
selections in one operation, but this is easily overcomed
as selections can be added or substracted:

example:
$sel = $sel1 + $sel2 + sel3 - sel4;


A special case allows to get the current selection state
of a layer into a variable. This is useful to capture
a selection made directly from the user graphical interface.

$sel = get selection of <layer>;
Demonstrated in example script:  all
-------------------------------------------------------------------
set

can set internal spdbv variables or atomic coordinates.
The list of internal variables that can be accessed is
provided at the end of this guide.

set <internal variable> = $varname;
set coord <string> of <selection> = $vector_varname;

where <string> contains the 4 characters atom name (for. ex " CA ")
and selection a selection.

It also allows to toggle the backbone representation for a 
layer to "ca_trace":

set ca_trace [ON|OFF] for <layer>;

related commands: get
Demonstrated in example script:  07
-------------------------------------------------------------------
show

show some parts from the view.
This is functionnally equivalent to the control panel.

show <part> of <selection>;
show in <layer> <part> of <selection>;

where <part> can be any combination of
res,side,label,surface,ribbon,vdw

related commands: hide color
Demonstrated in example script:  06 09 13
-------------------------------------------------------------------
silent

can be used in conjunction witht the stop command
to prevent any feedback of which line the script was stopped.

silent stop;

related commands: stop
Demonstrated in example script:  08 10
-------------------------------------------------------------------
sin

compute the sinus of an expression.

sin(<float>)
sin(<int>)

This returns the value in radians

related commands: asin cos acos tan atan PI
-------------------------------------------------------------------
ss

will get the secondary structure assignment of the first
selected amino acid found in a selection.

ss(<selection>)

alternately, you can access directly a specific residue
from a specific layer, which is faster and handy in loops with:

ss(<layer>,<int>)

returned value is of type <string> and is 'h' 's' or 'c'.

related commands: phi psi omega
Demonstrated in example script:  11
-------------------------------------------------------------------
stop

will stop the script in a way that it can be continued
from the graphical user interface with "shift" open script.
Very convenient if you want to interactiuvely inspect a molecule
before resuming the script flow.

related commands: 'please do' 'thank you' pause silent
Demonstrated in example script:  06 08
-------------------------------------------------------------------
sub

this command is nothing else than a goto that remembers where
it was before. It will resume execution where it was before
entering the subroutine as soon as a return statement is reached.

sub <label>;  <--- note that this must be the only command on a line

Execution will continue immediately after <label>, which must end with
a colon.
Note that subroutines must be located at the end of the script
(after the thank you statement).
All variables beeing global, be very careful when you
use them, especially loops variables).

example:  

please do
sub elsewhere;
thank you

elsewhere:
{
	print "Is grass really greener here?";
	return;
}

related commands: goto do while return
Demonstrated in example script:  08 10
-------------------------------------------------------------------
substring

allow to access substrings within a string by position.
Substrings are separated by spaces and numbering start from 0.

$string_varname = substring <int> of <string>;

example: 

$X = substring 0 of "Hello World!"; will put "Hello" into $X.
$X = substring 1 of "Hello World!"; will put "World!" into $X.

Demonstrated in example script:  04
-------------------------------------------------------------------
superpose

this command is equivalent to the magic fit of spdbv

<int> = superpose <layer> onto <layer> using <string>;

where <string> contains the method to be used ("CA", "backbone", "all","ss").
This returns the number of solutions as an int.
When "ss" is used, and more than one solution is possible, a temp
file "match.txt" is written and a window will be opene with one solution
per line.

related commands: rms fit
Demonstrated in example script:  05
-------------------------------------------------------------------
system               ** USEFUL but DANGEROUS **

system <string>;

This command is supported only for SGI and Linux versions.
executes a shell system command. It is mainly useful
to execute a script that will put results into a file
that can then be open as read-only with the open file
command and read line by line with readln.

Demonstrated in example script:  none
-------------------------------------------------------------------
tan

compute the tangent of an expression.

tan(<float>)
tan(<int>)

This returns the value in radians

related commands: sin asin cos acos atan PI
Demonstrated in example script:  none
-------------------------------------------------------------------
torsion

compute the torsion angle ABCD between fouratoms (vectors).
In other words, the angle between planes ABC and BCD.

<floatvar> = torsion(A,B,C,D);

where A,B,C and D are <vector> values
Result is returned in degrees.

related commands: dist get torsion
Demonstrated in example script:  none
-------------------------------------------------------------------
thank you

polite way of ending a script, which will also free any
memory assigned for arrays.
Demonstrated in example script:  all
-------------------------------------------------------------------
zoom

this command changes the camera position to zoom in or out

zoom <float>

where <float> is the percent change.
100.0 means no change, 
110.0 will do a close-up (enlarge the image by 10%)
90.0 will zoom out (decrease the image size by 10%)

related commands: rotate move
Demonstrated in example script:  05
-------------------------------------------------------------------
===================================================================
Tests (conditionnal execution):
===================================================================

if (expression test expression)
{
} 
else 
{
}

where test can be
== for identity
!= for different
>  for greater than
>=  for greater than or equal to
<  for smaller than
<=  for smaller than or equal to

Demonstrated in example script:  04 06 08
===================================================================
Loops:
===================================================================

Two kinds of loops are supported that allow to cope with
any situation. The higher level for(;;) statement is not
implemented:


in the following case, statements will be executed at least once,
and more depending on the result of the test.

do
{  <-- note that statements must start on the next line.
  statements;
} 
while (expression test expression);  <-- note the semicolon


in the following case, statements may not be executed at all,
depending on the result of the test.

while (expression test expression)  
{
  statements;
}

Demonstrated in example script:  01 02 03 04 05 06 07 09
===================================================================
Internal variables:
===================================================================

This is the list of recognized internal spdbv variables, that
can be accessed by the get and set commands.
Access to additional variables will be added in the future, as needed.

nbLayer                 returns the position of the last layer
                        as it starts at 0, when one layer is loaded
				    its value is 0. Its value is 1 for two layers
				    etc.
active_layer            returns the position of the currently active
                        layer (the one shown in the control panel).
gDotDensity
gCurrentOS              contains "MAC" "SGI" "LINUX" or "WINDOWS" 

The following variables affect the behaviour of alerts
presented during the load of a protein:

gReconstructSidechain    0 or 1  reconstruct missing sidechains 
gShowConnectAlert        0 or 1  report missing or bad CONECT 
gShowHETATMAlert         0 or 1  report ATOM treated as HETATM
gLoadWater               0 or 1  load solvent molecules
gPartialOccupancyWarning 0 or 1  

Demonstrated in example script:  08 10 for active_layer
*******************************************************************
