ploticus: ploticus scripts

## Ploticus scripts | Welcome Gallery Handbook |
| Manual page for Ploticus_scripts(PL)

## DESCRIPTION

Ploticus is controlled by scripts that a user creates in a text editor and saves in a file.`` The scripts can also be created by other programs.`` Script files should be plain ascii text files, and they may be named anything, however a file name ending of .p, .pl, .plo, .pls, .htm or .html is recommended.``

## EXAMPLE

Here is an example of a ploticus script:

     #proc areadef
       rectangle: 1 1 4 2
       xrange: 0 5
       yrange: 0 100

     #proc xaxis:
       stubs: text
     	Africa
     	Americas
     	Asia
     	Europe,\nAustralia,\n Pacific

     #proc yaxis
       label: Growth Rate
       stubs: inc 20
       minortics: yes
       minorticinc: 5

     #proc getdata
       data: 76
     	54
     	60
     	59

     #proc bars
       lenfield: 1
       color: teal
       barwidth: 0.2

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

The above Ploticus script invokes a number of procedures (procs).`` First, proc areadef to set up a plotting area, then proc xaxis and yaxis to render the axes.`` Then proc getdata is invoked to define some data, and then finally proc bars is invoked to produce a bar graph.``

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 `proc areadef` and specified values for these attributes: `rectangle`, `xrange`, and `yrange`. All of the procs, as well as the names, types, and acceptable values for all attributes, are described in the ploticus handbook.``

A large collection of script examples may be found in the ploticus gallery.`` One way to proceed is to locate an example that is similar to what you want, and then copy it and play with it.``

## PROCEDURES (PROCS) AND ATTRIBUTES

Procedures (procs) are always invoked using this construct: `#proc` procname.`` The word `#proc` indicates the start of a procedure specification block; the other word is the name of a procedure (case insensitive).``

Attributes within a procedure may be specified in any order. A colon (:) 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 line.``

The following script directives are used by ploticus in executing procedures:

## #proc

  This directive signals the beginning of a ploticus procedure (proc).
  Example: `#proc bars`

## #endproc

  This may also be written #proc endproc.`` It is not necessary to use this routinely.`` #endproc formally signals the end of a ploticus procedure, and must be used when a proc sets a variable and then that variable is referenced before the next #proc statement.`` Examples from the gallery that use #endproc are lineplot4 and distrib

## #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 procedure should contain a `#saveas`.``
  Example: `#procdef bars`

## #saveas

  Makes the current proc available to be cloned by procs encountered later in the script, and assigns it an identifier (B1 in the example below).`` A gallery example that uses saveas and clone is rangebar1 . May be used anywhere within the proc.``
  Example: `#saveas B1`

## #clone

  clone is used like an attribute.`` Inherits all attribute values from a previously saved proc. May be used anywhere within the proc.`` Attributes may be overridden locally as desired.``
  Example: `#clone B1`

Other general purpose directives are described below.``

## SYNTAX AND VARIABLES

Any line where the first non-whitespace content is `//` is a comment and is ignored. Comments must be alone on the line.`` Any line where the first non-whitespace content begins with # is a directive (an operator that does something).`` Everything else is generally HTML and is passed through transparently, except for evaluation of variables, and possible processing of certain inline formatting codes .``

Double quotes (") may be used to enclose character strings in set , setifnotgiven , if, elseif and call .`` Everywhere else, quotes have no special syntactical meaning and may be used freely without any special treatment.`` It is safe to use TABs to indent lines of code and in transparent output; other uses (such as embedding TAB in variable contents) should be avoided.``

Scripts can set and reference variables.`` Variable names must begin with a letter and may contain letters, digits, underscore (_) and period (.).`` Names are case-sensitive.`` Maximum length of a variable name is 38 characters.`` Variables may hold numbers, alphanumerics, or single-line text strings, up to a maximum content length of 250 characters. Variables cannot hold more than one line of text.`` All data, including numbers, are stored as characters.`` Where a variable is to be evaluated, it should be prefaced with an at-sign (@).`` In order to print an at-sign a double at sign (@) may be used.`` When setting or identifying a variable, the at-sign should not be used.`` Examples:

    	 Hello, my name is @NAME
    	 #shell cat data | recsel "@@3 = res"
    	 #set NAME = "Harvey Smith"

An attempt to evaluate a variable that has never been assigned a value will result in cancellation of the evaluation (the variable name will be passed through transparently) and no error condition will be raised.`` Several reserved variables exist. All variables are global in scope.``

## FUNCTIONS

Functions may be used 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`.``

## MORE DIRECTIVES

Directives are operators that do something, such as `#set`.`` Directives always begin with a pound sign (#), and usually occupy one line alone (a few of the directives, such as shell and sql can be multiline constructs).`` Individual "words" or tokens within a directive must be separated by white space.`` Directives may be indented using spaces or tabs.``

Descriptions of the flow-of-control directives follow:

## #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 (the closing quote may be omitted if desired).`` The variable may be a simple standalone variable or a field in a logical record .`` Whitespace must follow the `#set`, the variable, and the equals sign (=).`` Multiple alphanumeric variables or constants may be used on the right hand side, resulting in concatenation, however they must be separated by whitespace.`` Other directives that can set variables include: setifnotgiven and shell Examples:

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

## #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.``
  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.``
  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` `[noclose]`

  Write text to file.`` file may be a file name or `stderr` or `stdout`.`` filemode is either `w` to create, or `a` to append.`` 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 and the `noclose` option should be given with #endwrite.``

  The following example, if used in header code included by all pages in a cgipal project, would log page hits with date, time, name of page, and the HTTP info.``

       #set RH = $getenv(HTTP_REMOTE_HOST)
       #set RF = $getenv(HTTP_REFERER)
       #call $setdatefmt(yyyy/mmm/dd)
       #set DATE = $todaysdate()
       #set TIME = $time()
       #write /tmp/mylog a
       @DATE @TIME @_PAGE @RH @RF
       #endwrite

## #control

  `#control` attribute`` value

  Set various operational modes.`` attribute may be one of: `allowinlinecodes`, `dbquote`, `htmlqhmode`, `listsep`, `evalvars` , `suppressdll`, `leavenulls`, or `dot_in_varnames`.``

  Full description of #control directive

## #shell

  `#shell` option`` command`[#endshell]`

  Execute the given shell command, and optionally display or capture the results.`` The command may use a single line construct or a multi-line construct. `#endshell` must be used to terminate a multi-line construct.`` An option may be given; available options are `#load`, `#processrows`, `#dump` (the default), `#dumptab`, `#dumphtml`, and `#dumpsilent`.``

  More on #shell and interacting with the shell
  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` December 10, 2002.