## Script syntax

Version 2.32

Manual page for Script_syntax(PL)

## 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) ... are used to terminate certain attributes that are of multi-line type. Otherwise, blank lines can be used as desired for readability.``

## 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

More advanced ploticus scripts can set and reference variables.`` 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

More advanced ploticus scripts can use functions to assign a value to a variable ( set , setifnotgiven ), and 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 , sql , 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 `#saveas`d 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

  `#call` function

  Invoke a function without retaining its return value.
  Example: `#call $setdatefmt( "yyyy-mmm-dd" )`

## #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` file

  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

  `#cat` file1 [..fileN]

  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).``

  Example:

         #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.``

## #sql

  Note: This directive is currently supported only in certain builds, such as quisp/ploticus.``

  `#sql` allows you to access data from an SQL database to set ploticus variables or provide inline script content, in a similar manner to `#shell` above.

  To set ploticus variables use a construct such as this:

         #sql #load select id, remark from usernotes where id = 002

  This sets ploticus variables `id` and `remark`.`` If your sql command is returning more than one row, you can capture multiple rows like this:

         #sql #processrows  select id, remark from usernotes
         #while $sqlrow( id, remark ) = 0
          ...
         #endloop

  To provide inline script content use a construct such as this:

         #proc annotate
          location: 5.4 2.3
          text:
           #sql #dump select * from ....

  Longer sql commands can be accomodated using constructs like this:

         #sql #processrows
           select .... from ...
           where ....
         #endsql

  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` August 23, 2005.