File: scriptsyntax

package info (click to toggle)
ploticus-doc 2.33-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 9,392 kB
ctags: 169
sloc: pascal: 469; makefile: 63; sh: 11
file content (1128 lines) | stat: -rw-r--r-- 20,166 bytes
.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: script syntax</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550><tr>
<td>
  <table cellpadding=2 width=550><tr>
  <td><br><h2>Script syntax</h2></td>
  <td align=right>
  <small>
  <a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  Version 2.33 Jun'06
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH Script_syntax PL "02-JUN-2006   PL ploticus.sourceforge.net"

.ig >>
<a name=syntax></a>
.>>

.SH Script syntax
Ploticus scripts are plain ascii files you create in a text editor (or they can
be generated by programs or formed using the 
.ig >>
<a href="api.html">
.>>
\0libploticus API).
.ig >>
</a>
.>>
Every line in a script file must be terminated by a newline or CR-LF.
.LP
\fBSyntax summary:\fR
.LP
\fB#\fR ... lines beginning with \fB#\fR are 
.ig >>
<a href="#directives">
.>>
\0directives
.ig >>
</a>
.>>
, such as \fC#proc\fR, \fC#if\fR or \fC#include\fR.
There can never be more than one directive per line.
Directives can be indented by preceding them with white space.
.LP
\fB//\fR ... lines beginning with \fB//\fR are comments.
.LP
\fB@\fR ... used at the beginning of a 
.ig >>
<a href="#variables">
.>>
\0variable name
.ig >>
</a>
.>>
when its contents are to be displayed or referenced
Comments can be indented by preceding them with white space.
.LP
\fB@@\fR ... literal at-sign, or variable reference that must survive 1st round of evaluation
.LP
\fB$\fR = used at the beginning of
.ig >>
<a href="func.html">
.>>
\0function
.ig >>
</a>
.>>
names
.LP
\fB(blank lines)\fR ... are used to terminate certain attributes that are of multi-line type.  
Otherwise, blank lines can be used as desired for readability.

.ig >>
<a name=procs></a>
.>>
.ig >>
<br><br><br>
.>>

.SH Specifying procedures and attributes
.LP
When writing a script
you tell the graphing engine what to do by using one or more \fBprocedures\fR 
that are executed in top-down or flow-of-control order.
Use the 
.ig >>
<a href="#directives">
.>>
\0#proc directive
.ig >>
</a>
.>>
to specify a procedure.
.ig >>
<a href="#directives">
.>>
\0#endproc
.ig >>
</a>
.>>
may be used to signal the end of a procedure block.
.LP
Below the \fC#proc\fR line may come one or more \fBattributes\fR.
Attributes are one per line (some occupy multiple lines) and may be specified in any order.  
They have the form: \fIattributename\fC: \fIvalue\fR
Attributes that are 
.ig >>
<a href="atypes.html#multiline">
.>>
\0multiline text type
.ig >>
</a>
.>>
must be terminated using a blank line.
.LP
Some simple script examples are available
.ig >>
<a href="scripts.html">
.>>
\0here.
.ig >>
</a>
.>>

.ig >>
<a name=variables></a>
.>>
.ig >>
<br><br><br>
.>>

.SH Variables
More advanced ploticus scripts can set and reference \fBvariables\fR.
An at-sign (\fC@\fR) is used at the beginning of a variable name when its contents
are to be displayed or referenced.  When setting the variable the at-sign is not used.
All variables are global in scope.
There are some special variables that are set automatically by ploticus.
.ig >>
<a href="variables.html">
.>>
\0More info on variables.
.ig >>
</a>
.>>

.ig >>
<a name=functions>
.>>
.ig >>
<br><br><br>
.>>

.SH Functions
More advanced ploticus scripts can use functions to assign a value to a variable (
.ig >>
<a href="#set">
.>>
\0set
.ig >>
</a>
.>>
, 
.ig >>
<a href="#setifnotgiven">
.>>
\0setifnotgiven
.ig >>
</a>
.>>
), and in 
.ig >>
<a href="#if">
.>>
\0if
.ig >>
</a>
.>>
statements.  Function names always begin with a dollar sign ($), for
example: \fC$strlen( "hello world" )\fR.
For descriptions of the
available functions, see the
.ig >>
<a href="functions.html">
.>>
\0functions man page
.ig >>
</a>
.>>
\0.

There are functions for
.ig >>
<a href="functions.html#ploticus">
.>>
\0plotting
.ig >>
</a>
.>>
,
.ig >>
<a href="functions.html#arithmetic">
.>>
\0arithmetic
.ig >>
</a>
.>>
,
.ig >>
<a href="functions.html#strings">
.>>
\0strings
.ig >>
</a>
.>>
,
.ig >>
<a href="functions.html#commalists">
.>>
\0commalists
.ig >>
</a>
.>>
,
.ig >>
<a href="shell.html">
.>>
\0shell
.ig >>
</a>
.>>
,
.ig >>
<a href="sql.html">
.>>
\0sql
.ig >>
</a>
.>>
,
.ig >>
<a href="functions.html#dates">
.>>
\0dates
.ig >>
</a>
.>>
,
.ig >>
<a href="functions.html#times">
.>>
\0times
.ig >>
</a>
.>>
, and 
.ig >>
<a href="functions.html#misc">
.>>
\0other
.ig >>
</a>
.>>
\0.
Custom functions may be implemented in \fCcustom.c\fR.

.ig >>
<a name=directives></a>
.>>

.ig >>
<br><br><br>
.>>

.SH Directives 
.LP
The following script directives are available.  
Parameters that go with the directives must be separated by whitespace.
.ig >>
<a name=proc></a>
.>>

.SH #proc
.IP \0
This directive signals the beginning of a ploticus procedure (proc).  
.br
Usage: \fCproc \fIprocname\fR
.br
Example: \fC#proc getdata\fR

.ig >>
<br><br>
.>>
.ig >>
<a name=endproc></a>
.>>

.SH #endproc 
.IP \0
\fB#endproc\fR formally signals the end of a ploticus procedure.
It doesn't always need to be used.
It \fBmust\fR be used when the proc sets a variable and then
that variable is referenced before the next #proc statement.
\fB#endproc\fR may also be written \fB#proc endproc\fR.
.br
Usage: \fC#endproc\fR

.ig >>
<br><br>
.>>
.ig >>
<a name=procdef></a>
.>>

.SH #procdef
.IP \0
This directive is used similarly to #proc, but it does not
execute the procedure; it only defines it so that it may
be \fB#clone\fRd later.
The procdef block should contain a \fB#saveas\fR.
.br
Usage: \fC#procdef \fIprocname\fR
.br
Example: \fC#procdef scatterplot\fR

.ig >>
<br><br>
.>>
.ig >>
<a name=saveas></a>
.>>

.SH #saveas
.IP \0
Makes the current proc available to be \fBclone\fRd by procs 
encountered later in the script, and assigns it an identifier.
The identifier can be any alphanumeric, max length 30.
A gallery example that uses \fBsaveas\fR and \fBclone\fR is
.ig >>
<a href="../gallery/rangebar1.htm">
.>>
\0rangebar1.
.ig >>
</a>
.>>
May be used anywhere within the proc.  
There are some 
.ig >>
<a href="limits.html">
.>>
\0limitations
.ig >>
</a>
.>>
that come into play if #saveas is invoked many times such as within a loop.
.br
Usage: \fC#saveas \fIidentifier\fR
.br
Example: \fC#saveas B1\fR

.ig >>
<br><br>
.>>
.ig >>
<a name=clone></a>
.>>

.SH #clone
.IP \0
\fBclone\fR is used like an attribute.
It causes the current proc to inherit all attribute values from a previously \fBsave\fRd proc. 
I usually place a \fC#clone\fR directive as the first thing in a proc, but it may be specified anywhere 
within the proc.  Attributes may be overridden locally as desired.
.br
Usage: \fC#clone \fIidentifier\fR ... where \fIidentifier\fR names something
that was \fC#saveas\fRd earlier.
.br
Example: \fC#clone B1\fR

.ig >>
<br><br><br>
.>>

.ig >>
<a name=set></a>
.>>

.SH #set
.RS
.LP
\fC#set  \fIvariable\fC  =  \fInumeric\fR
.br
\fC#set  \fIvariable\fC  =  "\fItext\fC"\fR
.br
\fC#set  \fIvariable\fC  =  $\fIfunction\fR
.LP
Assigns a value to a \fIvariable\fR.
The value may be a constant or a variable, and
may be a numeric, alphanumeric/text, or 
.ig >>
<a href="functions.html">
.>>
\0function
.ig >>
</a>
.>>
result.
Alphanumeric/text literals should be enclosed in double quotes, especially if the literal
could contain embedded whitespace.
Multiple alphanumeric variables or constants may be used on the right hand side, resulting
in concatenation (they must be separated by whitespace).
The
.ig >>
<a href="#setifnotgiven">
.>>
\0setifnotgiven
.ig >>
</a>
.>>
and
.ig >>
<a href="#shell">
.>>
\0shell
.ig >>
</a>
.>>
directives can also be used to set variables.
.LP
Examples of \fC#set\fR:
.LP
.nf
\0#set COUNT = 0
\0#set LABEL = "My favorite martian"
\0#set LABEL = "My favorite martian    
\0#set LABEL = @A @B        
\0#set LABEL = @A ", " @B        
\0#set TODAY = $todaysdate()
\0#set TOTAL = $arith(@X+@Y+@Z)     
.fi
.RE

.ig >>
<a name=setifnotgiven></a>
.>>

.ig >>
<br><br>
.>>


.SH #setifnotgiven
.RS
.LP
\fC#setifnotgiven  \fIvariable\fC  =  \fIvalue\fR
.LP
Similar to
.ig >>
<a href="#set">
.>>
\0set
.ig >>
</a>
.>>
except that it takes action only if \fIvariable\fR is empty ("") or 
has never been assigned a value.  Useful in assigning a default value to 
optional passed variables.
.br
Example: \fC#setifnotgiven CUTOFF = 0.5\fR
.RE

.ig >>
<br><br>
.>>

.ig >>
<a name=call></a>
.>>

.SH #call
.RS
.LP
\fC#call  \fIfunction\fR
.LP
Invoke a \fI
.ig >>
<a href="functions.html">
.>>
\0function
.ig >>
</a>
.>>
\fR without retaining its return value.  
.br
Example: \fC#call $setdatefmt( "yyyy-mmm-dd" )\fR
.RE

.ig >>
<br><br>
.>>

.ig >>
<a name=if></a>
.>>

.SH #if  
.RS
Alter execution flow of control based on \fI
.ig >>
<a href="condex.html">
.>>
\0conditional expressions
.ig >>
</a>
.>>
\fR. 
\fBif\fR and \fBendif\fR are required.  
\fBelseif\fR and \fBelse\fR are optional.
An example of an #if construct:
.LP
.nf
\0#if @mode = A
    <h4>Mode is A</h4>
\0#elseif @mode = B
    <h4>Mode is B</h4>
\0#else
    <h4>Mode not given</h4>
\0#endif
.fi
.LP
Variables that have never been assigned are left as is by the script interpreter.
This usually gives intuitively correct results, eg. suppose MODE is unassigned:
\fC#if @MODE = \fIanything\fR will always be false, and
\fC#if @MODE != \fIanything\fR will always be true.
.ig >>
<a href="#setifnotgiven">
.>>
\0setifnotgiven
.ig >>
</a>
.>>
can be used to assign values to optional passed variables. 
.LP
Some examples of conditional expressions:
.LP
.nf
\0#if @tag = TOTAL
\0#if @meas > 0.0 && @meas < 8.5
\0#if @name = ""
\0#if @type like "west*" || @type = "bl*"
\0#if $arith(@A+@B) > 10
.fi
.RE
.LP

.ig >>
<br><br>
.>>
.ig >>
<a name=ifspec></a>
.>>

.SH #ifspec
.IP \0
\fBifspec\fR is a shortcut introduced in version 2.20 to assist in writing the scripts
that are used by ploticus prefabs.
Usage: \fC#ifspec \fIvarname\fR [\fIattributename\fR]
.br
If \fIvarname\fR has been assigned a value other than \fC""\fR, a ploticus proc
attribute setting is executed.  If \fIattributename\fR is given, \fIattributename\fR is set to the value.
Otherwise, attribute name and \fIvarname\fR are assumed to be the same.
If \fIvarname\fR has never been assigned a value, or has a value of \fC""\fR, nothing happens.

.ig >>
<br><br>
.>>

.ig >>
<a name=for></a>
.>>

.SH #for
.RS
\fC#for  \fIvar\fC  in  \fIcommalist\fR
.br
\0..
.br
\fC#endloop\fR
.br
.br
\fC#for  \fIvar\fC  across  \fImultirow-response\fR
.br
\0..
.br
\fC#endloop\fR
.LP
Loop the flow of control, iterating across members of 
.ig >>
<a href="commalist.html">
.>>
\0commalist
.ig >>
</a>
.>>
\fIvar\fR will be set to each member from first to last.
If \fIcommalist\fR
or \fImultirow-response\fR
is empty, the loop body will not be executed.
This example illustrates the construct, without doing
anything useful:
.LP
.nf
\0#set COLORLIST = "red,blue,green,yellow
\0#for  COLOR  in  @COLORLIST
\0    #if  @COLOR  =  green
\0        #break
\0    #elseif  @COLOR  =  blue
\0        #continue
\0    #endif
\0#endloop
.fi
.RE

.ig >>
<br><br>
.>>

.ig >>
<a name=while></a>
.>>

.SH #while
.RS
\fC#while\fC  \fIconditional expression\fR
.br
\0..(loop body)..
.br
\fC#endloop\fR
.LP
Loop the flow of control while 
.ig >>
<a href="condex.html">
.>>
\0conditional
.ig >>
</a>
.>>
is true.
If \fIconditional expression\fR is initially false, the loop body
will not be executed at all.
The following example loops until I > 10:
.LP
.nf
\0#set I = 0
\0#while @I <= 10
\0  #set I = $arith(@I+1)
\0#endloop
.fi
.RE

.ig >>
<br><br>
.>>

.ig >>
<a name=loop></a>
.>>

.SH #loop
.RS
.LP
\fC#loop\fR
.br
\0..
.br
\fC#endloop\fR
.LP
Loop the flow of control.  A 
.ig >>
<a href="#break">
.>>
\0break
.ig >>
</a>
.>>
statement must be used to terminate the loop.
The following example loops until I > 10:
.LP
.nf
\0#set I = 0
\0#loop
\0   #set I = $arith(@I+1)
\0   #if @I > 10
\0       #break
\0   #endif
\0#endloop
.fi
.RE

.ig >>
<br><br>
.>>

.ig >>
<a name=break></a>
.>>

.SH #break
.RS
Terminate the iteration of the most recently invoked
.ig >>
<a href="#for">
.>>
\0for
.ig >>
</a>
.>>
loop,
.ig >>
<a href="#while">
.>>
\0while
.ig >>
</a>
.>>
loop, or plain
.ig >>
<a href="#loop">
.>>
\0loop
.ig >>
</a>
.>>
\0.  Script execution resumes at the statement immediately following
the corresponding \fBendloop\fR.
There are restrictions if used within an 
.ig >>
<a href="#include@_SL01">
.>>
\0included
.ig >>
</a>
.>>
file.
.RE

.ig >>
<br><br>
.>>

.ig >>
<a name=continue></a>
.>>

.SH #continue
.RS
Proceed directly to the next
iteration of the most recently invoked
.ig >>
<a href="#for">
.>>
\0for
.ig >>
</a>
.>>
loop,
.ig >>
<a href="#while">
.>>
\0while
.ig >>
</a>
.>>
loop, or plain
.ig >>
<a href="#loop">
.>>
\0loop
.ig >>
</a>
.>>
\0.  
There are restrictions if used within an 
.ig >>
<a href="#include">
.>>
\0included
.ig >>
</a>
.>>
file.
.RE

.ig >>
<br><br>
.>>

.ig >>
<a name=exit></a>
.>>

.SH #exit
.RS
Terminate execution immediately.  Example:
.LP
.nf
\0#if @_DEBUG = 1
\0    #exit
\0#endif
.fi
.RE

.ig >>
<br><br>
.>>

.ig >>
<a name=include></a>
.>>

.SH #include
.IP \0
\fC#include  \fIfile\fR
.IP 
Include script code from a \fIfile\fR.
\fIfile\fR should be a pathname, or if it begins with a dollar-sign ($) it 
is taken to reside in the ploticus prefabs directory (useful when a standard
location is needed).
Includes may be nested.
\fBinclude\fRd code is interpreted in the same manner as ordinary code.
However, 
.ig >>
<a href="#break">
.>>
\0break
.ig >>
</a>
.>>
and
.ig >>
<a href="#continue">
.>>
\0continue
.ig >>
</a>
.>>
may be used only if the corresponding loop / #endloop is also within
the included file.
.ig >>
<a href="#return">
.>>
\0return
.ig >>
</a>
.>>
may be used to immediately exit the included file and resume execution
in the including file.
.IP
Security concern: user-supplied values (such as CGI user variables) should not be used to build the filename, unless
proper measures are taken to detect and remove the \fC../\fR construct (used as a hack 
to see higher levels of the file system).
.IP
Example: \fC#include projectheader\fR
.IP
Example: \fC#include $chunk_logtics\fR

.ig >>
<br><br>
.>>

.ig >>
<a name=cat></a>
.>>
.SH #cat
.IP \0
\fC#cat  \fIfile1\fR [..\fIfileN\fR]
.IP 
Copy the contents of \fIfile\fRs to the standard output.
No processing or interpretation is done to the contents.
Suitable for text files or binary files.
.IP
Security concern: user-supplied values (such as CGI user variables) should not be used to build the filename, unless
proper measures are taken to detect and remove the \fC../\fR construct (used as a hack 
to see higher levels of the file system).
.IP
Example: \fC#cat /home/scg/img/banner.gif\fR

.ig >>
<br><br>
.>>

.ig >>
<a name=return></a>
.>>

.SH #return
.RS
Terminate execution of an
.ig >>
<a href="#include">
.>>
\0included
.ig >>
</a>
.>>
file immediately.
Execution is resumed at the statement immediately following
the \fBinclude\fR.
.RE


.ig >>
<br><br>
.>>

.ig >>
<a name=write></a>
.>>

.SH #write
.IP \0
\fC#write  \fIfile\fC  [\fIfilemode\fR]
.br
\0..\fItext\fR..
.br
\fC#endwrite\fR 
.IP
Write some \fItext\fR to standard output, standard error, or a file.
\fIfile\fR should be given as \fCstderr\fR, \fCstdout\fR, or a file pathname.
\fIfilemode\fR is either \fCw\fR to create, or \fCa\fR to append (if omitted \fCw\fR is assumed).
Within the construct, other directives, such as
.ig >>
<a href="#if">
.>>
\0#if
.ig >>
</a>
.>>
,
.ig >>
<a href="#for">
.>>
\0#for
.ig >>
</a>
.>>
,
.ig >>
<a href="#include@_SL01">
.>>
\0#include
.ig >>
</a>
.>>
and so on may be freely used.
If \fCstdout\fR or \fCstderr\fR are used, the \fIfilemode\fR is ignored.
.IP
Security concern: user-supplied values (such as CGI user variables) should not be used to build the filename, unless
proper measures are taken to detect and remove the \fC../\fR construct (used as a hack 
to see higher levels of the file system).
.IP
Example:
.nf
\0  #write stdout
\0    X = @X and Y = @Y
\0  #endwrite
.fi



.ig >>
<br><br>
.>>





.ig >>
<br><br>
.>>

.ig >>
<a name=shell></a>
.>>

.SH #shell 
.IP
Execute an external shell command and capture the standard output of the command, 
in order to set ploticus variables or get inline content for your ploticus 
script (such as annotation text).  
.IP
To set ploticus variable(s), use a construct such as this:
.nf
\0  #shell #processrows
\0     date
\0  #endshell
\0  #call $shellrow( todaysdate )
.fi
The above example sets one ploticus variable (\fCtodaysdate\fR) to the entire
line of results returned by the unix \fCdate\fR command.
When only one variable is listed in the \fC$shellrow()\fR statement, the entire 
line of results will be captured into the variable; when more than one variable is 
listed, whitespace-delimited fields will be captured.
Here's another example where we capture individual fields and set several
ploticus variables.  We assume here that the unix date command result is something
like this: \fCWed Mar 16 09:31:27 EST 2005\fR
.nf
\0  #shell #processrows
\0     date
\0  #endshell
\0  #call $shellrow( wday, mon, day, time, tz, year )
.fi
If your shell command is returning more than one row, you can capture multiple rows 
like this:
.nf
\0  #while $shellrow( x, y, z ) = 0
\0   ...
\0  #endloop
.fi
.IP
You can also use \fC#shell\fR to get miscellaneous inline script content.  
This can be done anywhere in the script.  Here's an example:
.nf
\0 #proc annotate
\0  location: 5.4 2.3
\0  text:
\0   #shell
\0     some command
\0   #endshell
.fi
.IP
\fC#shell\fR generally can't be used to write the command's standard output
directly to the terminal.  \fC#shell\fR is implemented internally using \fCpopen()\fR.
.IP
Security concern: Avoid building the shell command using user-supplied values (such as CGI user variables). 
Where this must be done, #shell provides automatic removal of
hazardous shell metacharacters present in variables that are evaluated within the \fC#shell\fR / \fC#endshell\fR construct.
The developer should verify that this is working as expected.

.ig >>
<br><br><br>
.>>

.ig >>
<a name=sql></a>
.>>

.SH #sql
.IP \0
Note: This directive is currently supported only in certain builds, such as quisp/ploticus.
.IP
\fC#sql\fR allows you to access data from an SQL database to set ploticus variables or 
provide inline script content, in a similar manner to \fC#shell\fR above.  
.IP
To set ploticus variables use a construct such as this:
.nf
\0  #sql #load select id, remark from usernotes where id = 002
.fi
This sets ploticus variables \fCid\fR and \fCremark\fR.
If your sql command is returning more than one row, you can capture multiple rows
like this:
.nf
\0  #sql #processrows  select id, remark from usernotes
\0  #while $sqlrow( id, remark ) = 0
\0   ...
\0  #endloop
.fi

.IP
To provide inline script content use a construct such as this:
.nf
\0  #proc annotate
\0   location: 5.4 2.3
\0   text:
\0    #sql #dump select * from ....
.fi
Longer sql commands can be accomodated using constructs like this:
.nf
\0  #sql #processrows
\0    select .... from ...
\0    where ....
\0  #endsql
.fi


.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif"> 
</center>
</td></tr>
</table>
<br>
<center>
Ploticus is hosted at http://ploticus.sourceforge.net <br>
<img src="http://sourceforge.net/sflogo.php?group_id=38453" width="88" height="31" border="0" alt="SourceForge Logo">
</center>
.>>