Search
Ploticus >
Scripts >
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
libploticus API).
Every line in a script file must be terminated by a newline or CR-LF.
Syntax summary:
# ... lines beginning with # are
directives
, such as #proc, #if or #include.
There can never be more than one directive per line.
Directives can be indented by preceding them with white space.
// ... lines beginning with // are comments.
@ ... used at the beginning of a
variable name
when its contents are to be displayed or referenced
Comments can be indented by preceding them with white space.
@@ ... literal at-sign, or variable reference that must survive 1st round of evaluation
$ = used at the beginning of
function
names
Blank lines ... must be used to terminate multiline text attributes.
Otherwise, blank lines can be used as desired for readability.
Lower case ... proc names, attribute names, and directives must be given in lower-case
unless otherwise noted.
Specifying procedures and attributes
When writing a script
you tell the graphing engine what to do by using one or more procedures
that are executed in top-down or flow-of-control order.
Use the
#proc directive
to specify a procedure.
#endproc
may be used to signal the end of a procedure block.
Below the #proc line may come one or more attributes.
Attributes are one per line (some occupy multiple lines) and may be specified in any order.
They have the form: attributename: value
Attributes that are
multiline text type
must be terminated using a blank line.
Some simple script examples are available
here.
Variables
Variables can be set and referenced.
An at-sign (@) 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.
More info on variables.
Functions
There are a number of functions available for use by ploticus scripts. Functions
are used to assign a value to a variable (
set
,
setifnotgiven
). Functions are also used as elements in
if
statements. Function names always begin with a dollar sign ($), for
example: $strlen( "hello world" ).
For descriptions of the
available functions, see the
functions man page
.
There are functions for
plotting
,
arithmetic
,
strings
,
commalists
,
shell
,
dates
,
times
, and
other
.
Custom functions may be implemented in custom.c.
Directives
The following script directives are available.
Parameters that go with the directives must be separated by whitespace.
#proc
This directive signals the beginning of a ploticus procedure (proc).
Usage: proc procname
Example: #proc getdata
#endproc
#endproc formally signals the end of a ploticus procedure.
It doesn't always need to be used.
It must be used when the proc sets a variable and then
that variable is referenced before the next #proc statement.
#endproc may also be written #proc endproc.
Usage: #endproc
#procdef
This directive is used similarly to #proc, but it does not
execute the procedure; it only defines it so that it may
be #cloned later.
The procdef block should contain a #saveas.
Usage: #procdef procname
Example: #procdef scatterplot
#saveas
Makes the current proc available to be cloned 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 saveas and clone is
rangebar1.
May be used anywhere within the proc.
There are some
limitations
that come into play if #saveas is invoked many times such as within a loop.
Usage: #saveas identifier
Example: #saveas B1
#clone
clone is used like an attribute.
It causes the current proc to inherit all attribute values from a previously saved proc.
I usually place a #clone directive as the first thing in a proc, but it may be specified anywhere
within the proc. Attributes may be overridden locally as desired.
Usage: #clone identifier ... where identifier names something
that was #saveasd earlier.
Example: #clone B1
#set
#set variable = numeric
#set variable = "text"
#set variable = $function
Assigns a value to a variable.
The value may be a constant or a variable, and
may be a numeric, alphanumeric/text, or
function
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
setifnotgiven
and
shell
directives can also be used to set variables.
Examples of #set:
#set COUNT = 0
#set LABEL = "My favorite martian"
#set LABEL = "My favorite martian
#set LABEL = @A @B
#set LABEL = @A ", " @B
#set TODAY = $todaysdate()
#set TOTAL = $arith(@X+@Y+@Z)
#setifnotgiven
#setifnotgiven variable = value
Similar to
set
except that it takes action only if variable is empty ("") or
has never been assigned a value. Useful in assigning a default value to
optional passed variables.
Example: #setifnotgiven CUTOFF = 0.5
#call
#if
Alter execution flow of control based on
conditional expressions
.
if and endif are required.
elseif and else are optional.
An example of an #if construct:
#if @mode = A
<h4>Mode is A</h4>
#elseif @mode = B
<h4>Mode is B</h4>
#else
<h4>Mode not given</h4>
#endif
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:
#if @MODE = anything will always be false, and
#if @MODE != anything will always be true.
setifnotgiven
can be used to assign values to optional passed variables.
Some examples of conditional expressions:
#if @tag = TOTAL
#if @meas > 0.0 && @meas < 8.5
#if @name = ""
#if @type like "west*" || @type = "bl*"
#if $arith(@A+@B) > 10
#ifspec
ifspec is a shortcut introduced in version 2.20 to assist in writing the scripts
that are used by ploticus prefabs.
Usage: #ifspec varname [attributename]
If varname has been assigned a value other than "", a ploticus proc
attribute setting is executed. If attributename is given, attributename is set to the value.
Otherwise, attribute name and varname are assumed to be the same.
If varname has never been assigned a value, or has a value of "", nothing happens.
#for
#for var in commalist
..
#endloop
#for var across multirow-response
..
#endloop
Loop the flow of control, iterating across members of
commalist
var will be set to each member from first to last.
If commalist
or multirow-response
is empty, the loop body will not be executed.
This example illustrates the construct, without doing
anything useful:
#set COLORLIST = "red,blue,green,yellow
#for COLOR in @COLORLIST
#if @COLOR = green
#break
#elseif @COLOR = blue
#continue
#endif
#endloop
#while
#while conditional expression
..(loop body)..
#endloop
Loop the flow of control while
conditional
is true.
If conditional expression is initially false, the loop body
will not be executed at all.
The following example loops until I > 10:
#set I = 0
#while @I <= 10
#set I = $arith(@I+1)
#endloop
#loop
#loop
..
#endloop
Loop the flow of control. A
break
statement must be used to terminate the loop.
The following example loops until I > 10:
#set I = 0
#loop
#set I = $arith(@I+1)
#if @I > 10
#break
#endif
#endloop
#break
Terminate the iteration of the most recently invoked
for
loop,
while
loop, or plain
loop
. Script execution resumes at the statement immediately following
the corresponding endloop.
There are restrictions if used within an
included
file.
#continue
Proceed directly to the next
iteration of the most recently invoked
for
loop,
while
loop, or plain
loop
.
There are restrictions if used within an
included
file.
#exit
Terminate execution immediately. Example:
#if @_DEBUG = 1
#exit
#endif
#include
Include script code from a file.
file 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.
included code is interpreted in the same manner as ordinary code.
However,
break
and
continue
may be used only if the corresponding loop / #endloop is also within
the included file.
return
may be used to immediately exit the included file and resume execution
in the including file.
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 ../ construct (used as a hack
to see higher levels of the file system).
Example: #include projectheader
Example: #include $chunk_logtics
#cat
Copy the contents of files to the standard output.
No processing or interpretation is done to the contents.
Suitable for text files or binary files.
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 ../ construct (used as a hack
to see higher levels of the file system).
Example: #cat /home/scg/img/banner.gif
#return
Terminate execution of an
included
file immediately.
Execution is resumed at the statement immediately following
the include.
#write
#write file [filemode]
..text..
#endwrite
Write some text to standard output, standard error, or a file.
file should be given as stderr, stdout, or a file pathname.
filemode is either w to create, or a to append (if omitted w is assumed).
Within the construct, other directives, such as
#if
,
#for
,
#include
and so on may be freely used.
If stdout or stderr are used, the filemode is ignored.
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 ../ construct (used as a hack
to see higher levels of the file system).
#write stdout
X = @X and Y = @Y
#endwrite
#shell
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).
To set ploticus variable(s), use a construct such as this:
#shell #processrows
date
#endshell
#call $shellrow( todaysdate )
The above example sets one ploticus variable (todaysdate) to the entire
line of results returned by the unix date command.
When only one variable is listed in the $shellrow() 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: Wed Mar 16 09:31:27 EST 2005
#shell #processrows
date
#endshell
#call $shellrow( wday, mon, day, time, tz, year )
If your shell command is returning more than one row, you can capture multiple rows
like this:
#while $shellrow( x, y, z ) = 0
...
#endloop
You can also use #shell to get miscellaneous inline script content.
This can be done anywhere in the script. Here's an example:
#proc annotate
location: 5.4 2.3
text:
#shell
some command
#endshell
#shell generally can't be used to write the command's standard output
directly to the terminal. #shell is implemented internally using popen().
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 #shell / #endshell construct.
The developer should verify that this is working as expected.
