#set TITLE = "Ploticus scripts"
#include top

.SH DESCRIPTION
.LP
Ploticus is controlled by scripts that a 
user creates in a text editor.
The scripts can also be created by other programs.

.SH EXAMPLE
Here is an example of a ploticus script:
.nf
.ft C
.ig >>
<br><img src="../gallery/sa1.gif"><br>
.>>
\0#proc areadef
\0  rectangle: 1 1 4 2
\0  xrange: 0 5
\0  yrange: 0 100
\0
\0#proc xaxis:
\0  stubs: text
\0	Africa
\0	Americas
\0	Asia
\0	Europe,\\nAustralia,\\n\& Pacific
\0
\0#proc yaxis
\0  label: Growth Rate
\0  stubs: inc 20
\0  minortics: yes
\0  minorticinc: 5
\0
\0#proc getdata
\0  data: 76 
\0	54 
\0	60 
\0	59
\0
\0#proc bars
\0  lenfield: 1
\0  color: teal
\0  barwidth: 0.2
\0
.ft R
.fi

.LP
As you can see, this is not low-level 3GL-style code.  It is a sort of
hybrid; plotting actions (#procs) are specified in procedural order,
but within each #proc the language is goal-driven (4GL).  Thus, traditional
procedural programming skills are not required.
.LP
The above Ploticus script invokes a number of procedures (procs).
First,
\fBproc areadef\fR to set up a plotting area, then
\fBproc xaxis\fR and \fByaxis\fR to render the axes.
Then \fBproc getdata\fR is invoked to define some data, 
and then finally \fBproc bars\fR is invoked to produce a bar graph.
.LP
For each proc, the user may specify a various attributes or options.
Attributes that are not specified use a default when possible.
In the above example, the user has invoked \fCproc areadef\fR
and specified values for these attributes: \fCrectangle\fR, \fCxrange\fR,
and \fCyrange\fR.  
All of the procs, as well as the names, types, and acceptable 
values for all attributes, are described in the Ploticus Handbook
.ig >>
<a href="../doc/Contents.html">(click here)</a>
.>>

.SH SYNTAX
.LP
\fBComments\fR: any line beginning with a double slash (\fB//\fR) is
taken as a comment.  Also, HTML tags and just about anything can be
included as long as it is above the first \fC#proc\fR.
.LP
\fBProcedures\fR are always invoked using this construct: \fC#proc \fIprocname\fR.
The word \fC#proc\fR indicates the start of a procedure specification block;
the other word is the name of a procedure (case insensitive).
.LP
\fBAttributes\fR within a procedure may be specified in any order.  
A colon (\fB:\fR) may be used after an attribute
name or a procedure name (however it is not required).  
All proc names and attribute names are case-insensitive.  
Attributes that are multiline text type
are terminated by a blank (zero-length) line.
.ig >>
<a name=variables></a>
.>>
.LP
\fBVariables\fR may be used within scripts.  
Variables may be named anything.  
Our convention is to use all capital letters,
but this is not required.
A number of 
.ig >>
<a href="variables.html">
.>>
variables are set automatically by ploticus 
.ig >>
</a>
.>>
for use in your scripts if desired.
Otherwise, all variables must be #declared (see below) 
before use.
The \fC#set\fR operator (see below) assigns values to variables.
Variables may also be declared and set by supplying them on the
ploticus command line as a 
.ig >>
<a href="pl.1.html#varvalue">
.>>
\fI var=value pair \fR
.ig >>
</a>
.>>
 .  When a variable
is dereferenced, its name must begin with an at-sign (\fB@\fR).  
The at-sign is not used with \fC#declare\fR, \fC#musthave\fR, or \fC#set\fR.

.ig >>
<a name=functions></a>
.>>
.LP
\fBFunctions\fR may occasionally appear in scripts.  They are usually
used with the \fC#set\fR operator to produce a value, or in 
.ig >>
<a href="condex.html">
.>>
 conditional expressions 
.ig >>
</a>
.>>
 .  Function calls always begin with a dollar sign (\fB$\fR).
The construct is  $\fIname\fR(\fIarg1\fR,..\fIargn\fR).
Embedded spaces are not allowed anywhere in the function construct
when used in conditional expressions, but they are allowed with #set.
See also 
.ig >>
<a href="functions.html">
.>>
 functions 
.ig >>
</a>
.>>
for a list of available built-in functions.

.LP
\fBScript Operators\fR all begin with a 
pound sign (\fB#\fR).  
The most commonly used operators are \fC#proc\fR, \fC#clone\fR, 
and \fC#saveas\fR;
many scripts use no script operators other than \fC#proc\fR.

.LP
\fB#clone\fR \fIobjname\fR
.IP
#clone is used like an attribute.
It causes the attribute values from another proc to be copied into
the current one.  
The other proc may be located by itself in a file, or one in the current script that
has already been executed (it must have a #saveas).  
.br
Example: \fC#clone: A\fR
.br
For a real example see rangebar1 in the Gallery
.ig >>
<a href="../gallery/rangebar1.htm">(click here)</a>
.>>

.LP
\fB#declare\fR \fIvarname\fR [,\fIvarname2\fR, \fIvarname3\fR, \fIetc.\fR]
.IP
Declare one or more script variables.  All variables must be
declared before they may be used, either by #declare, or
by specifiying a var=value pair on the command line.
.br
You can also attach the modifier \fCsoft\fR, which allows the
variable to be passed in from the command line, or if not present
on the command line, declared.
.br
Example: \fC#declare BCOLOR
.br
Example: \fC#declare COLOR1, COLOR2, COLOR3\fR

.LP
\fB#exit\fR
.IP
Stop executing the script at this point.

.LP
\fB#hideund\fR
.IP
hide any embedded underscores by converting to space.  See also \fB#showund\fR.

.LP
\fB#if \fIconditional-expression\fR
.br
\0#endif
.IP
conditional execution.  See condex(pli) for a description
of conditional expression syntax
.ig >>
<a href="condex.html">(click here)</a>
.>>
Tokens within conditional expressions must be separated by one or more spaces.
.br
Example: 
.nf
.ft C
\0#if @MODE = 1
\0  #exit
\0#endif
.fi
.ft R

.LP
\fB#include\fR  \fIscriptname\fR
.IP
include contents of another file.
Variable evaluation will occur on included lines and 
special #operators may be used in the included file.
However, \fB#include\fRs may not be nested.
Also, mismatched #if/#endif or #loop/#endloop may give
strange results. or #loop/#endloop may give
strange results.
.br
Example: \fC#include myscript.p\fR

.LP
\fB#includesh\fR  \fIcommand\fR
.IP
Same as #include above, but executes shell \fIcommand\fR instead of
opening an explicitly named file.  

.LP
\fB#intrailer\fR
.IP
Include content from a \fBproc trailer\fR located at the end 
of the script file.  #intrailer is used like an attribute.
It may be useful for integrating data into a script but getting
it out of the way.  For a real example of this see km 
.ig >>
<a href="../gallery/km.htm">(click here)</a>
.>>


.LP
\fB#loop
.br
\0#break
.br
\0#continue
.br
\0#endloop
\fP = set up an iterative loop.
Loops cannot be nested.
.br
Here is a simple loop example:
.nf
.ft C
\0	#declare I
\0	#set I = 0
\0        #loop
\0          #set I = $arith(@I+1)
\0          #if @I > 10
\0            #break
\0          #endif
\0        #endloop\fR
.fi
.ft R

.LP
\fB#musthave\fR  \fIvarname\fR [,\fIvarname2\fR, \fIvarname3\fR, \fIetc.\fR]
.IP
insist that a variable be provided as a var-value pair 
on the command line.
Example: \fC#musthave MODE\fR

.LP
\fB#proc\fR  \fIprocname\fR
.IP
execute a ploticus procedure.
Attribute specifications typically follow.

.LP
\fB#procdef\fR  \fIprocname\fR
.IP
Same syntax as #proc, but only defines
the procedure rather than executing it.
One of the attributes should be a \fC#saveas\fR.
.br
Example: \fC#saveas: A\fR

.LP
\fB#saveas\fR  \fIobjname\fR
.IP
#saveas is used like an attribute.
It causes a proc's attribute values to be saved so that they may 
be #cloned later

.LP
\fB#set\fR  \fIvarname\fR  =  \fIvalue or function\fR
.IP
set a variable to a value or function result.
By default, values are treated as numerics and leading zeros
truncated; to avoid this use a leading double quote (\fB"\fR).
All tokens in a #set expression should be separated by one or
more spaces.
.br
Example: \fC#set GROUP = A\fR
.br
Example: \fC#set IDNUM = "00329\fR

.LP
\fB#showund\fR
.IP
show embedded underscores.  This is the default behavior.  
See also \fB#hideund\fR.


#include bottom
