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

 #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

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"

MORE DIRECTIVES

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