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. The scripts can also be created by other programs.

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 (click here)

SYNTAX

Comments: any line beginning with a double slash (//) is taken as a comment. Also, HTML tags and just about anything can be included as long as it is above the first #proc.

Procedures 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 (zero-length) line.

Variables may be used within scripts. Variables may be named anything. Our convention is to use all capital letters, but this is not required. A number of variables are set automatically by ploticus for use in your scripts if desired. Otherwise, all variables must be #declared (see below) before use. The #set operator (see below) assigns values to variables. Variables may also be declared and set by supplying them on the ploticus command line as a var=value pair . When a variable is dereferenced, its name must begin with an at-sign (@). The at-sign is not used with #declare, #musthave, or #set.

Functions may occasionally appear in scripts. They are usually used with the #set operator to produce a value, or in conditional expressions . Function calls always begin with a dollar sign ($). The construct is $name(arg1,..argn). Embedded spaces are not allowed anywhere in the function construct when used in conditional expressions, but they are allowed with #set. See also functions for a list of available built-in functions.

Script Operators all begin with a pound sign (#). The most commonly used operators are #proc, #clone, and #saveas; many scripts use no script operators other than #proc.

#clone objname

#clone is used like an attribute. It causes the attribute values from another proc to be copied into the current one. The other proc may be located by itself in a file, or one in the current script that has already been executed (it must have a #saveas).
Example: #clone: A
For a real example see rangebar1 in the Gallery (click here)

#declare varname [,varname2, varname3, etc.]

Declare one or more script variables. All variables must be declared before they may be used, either by #declare, or by specifiying a var=value pair on the command line.
You can also attach the modifier soft, which allows the variable to be passed in from the command line, or if not present on the command line, declared.
Example: #declare BCOLOR
Example:
#declare COLOR1, COLOR2, COLOR3

#exit

Stop executing the script at this point.

#hideund

hide any embedded underscores by converting to space. See also #showund.

#if conditional-expression
#endif

conditional execution. See condex(pli) for a description of conditional expression syntax (click here) Tokens within conditional expressions must be separated by one or more spaces.
Example:

 #if @MODE = 1
   #exit
 #endif

#include scriptname

include contents of another file. Variable evaluation will occur on included lines and special #operators may be used in the included file. However, #includes may not be nested. Also, mismatched #if/#endif or #loop/#endloop may give strange results. or #loop/#endloop may give strange results.
Example: #include myscript.p

#includesh command

Same as #include above, but executes shell command instead of opening an explicitly named file.

#intrailer

Include content from a proc trailer located at the end of the script file. #intrailer is used like an attribute. It may be useful for integrating data into a script but getting it out of the way. For a real example of this see km (click here)

#loop
#break
#continue
#endloop
= set up an iterative loop. Loops cannot be nested.
Here is a simple loop example:

 	#declare I
 	#set I = 0
         #loop
           #set I = $arith(@I+1)
           #if @I > 10
             #break
           #endif
         #endloop

#musthave varname [,varname2, varname3, etc.]

insist that a variable be provided as a var-value pair on the command line. Example: #musthave MODE

#proc procname

execute a ploticus procedure. Attribute specifications typically follow.

#procdef procname

Same syntax as #proc, but only defines the procedure rather than executing it. One of the attributes should be a #saveas.
Example: #saveas: A

#saveas objname

#saveas is used like an attribute. It causes a proc's attribute values to be saved so that they may be #cloned later

#set varname = value or function

set a variable to a value or function result. By default, values are treated as numerics and leading zeros truncated; to avoid this use a leading double quote ("). All tokens in a #set expression should be separated by one or more spaces.
Example: #set GROUP = A
Example: #set IDNUM = "00329

#showund

show embedded underscores. This is the default behavior. See also #hideund.


data display engine  
Copyright Steve Grubb


Markup created by unroff 1.0,    June 18, 2001.