Cavor Scripting Language ("sizzle")

Note: This is only partially implemented at this point (April 2001). Think of this as more of a design document than a reference document.

CSL is the language in which Cavor applications are written. Of couse other languages such as C and C++ may be used to provide additional modules or extend Cavor, and someone might choose to provide, say, Tcl/Tk (for example) bindings for the Cavor components.

The language is similar in flavor to the various Unix shell scripting languages, to Tcl, and also ocmprises a modified SQL. Anyone familiar with any of these should easily understand CSL. It is somewhat based on the GML ("GeoVision/Geographic Macro Language") used to script the VISION* product, although GML scripts ("macros") won't run unmodified. (At least, I'd be surprised if they did -- I don't remember all of GML, and I've cleaned up the syntax some from what I do remember.)

Basic Concepts

A CSL program or script is a sequence of commands, separated by semicolons (;) and terminated with a period (.).

Comments start with a hash (#) and continue to end-of-line. Identifiers are alphanumeric.

CSL variables can be considered to be stored as strings, although purely numeric strings may also be treated as numbers. There is also the data type "coord" (coordinate or point) which can represent a 2D or 3D coordinate value as an ordered pair (or triplet). E.g. (3.5, 7.1).

TODO: fill in here

Commands

Expressions

An expression is any operation or sequence of operations that returns a value. The simplest expressions are constants (e.g. 42, 3.1415926, 'foo') or variable names ($bar, $my_var). Other expressions may include arithmetic expressions ( $bar+7), logical expressions ( $bar != $bletch) or function calls ( cos($theta) ), or combinations thereof.

Simple commands

Simple commands take the form keyword operands where operands may be optional or may include some additional key words to identify the operands.

;

Null command. Does nothing.

expression ;

Evaluates the expression but discards any returned result.

assign variable expression ;

variable := expression;

Stores the value of expression in the named variable. Creates the variable if it doesn't already exist. E.g. assign answer 42; or answer := 42;

draw line [ from coord ] to coord [[ to coord ] ... ] [color color] [into object] ;

Draws a line starting at the current point or the optional 'from' point, through successive 'to' points. Uses the current drawing color if no color is specified, and the currently active object (entity) if no new object is specified.

draw object object-expression ;

Object-expression should evaluate into the numeric identifier of an existing entity (entity-id). That entity is then rendered (drawn) according to the current symbology settings.

message expression ;

Displays the result of the expression to the user.

return expression ;

Useful only in function definitions (see below). Returns the value of expression to the caller of the function.

TODO: more commands

Compound commands

These commands may comprise multiple commands.

{ command [[ ; command ] ... ] }

Any sequence of one or more commands can be treated as a single command if it enclosed in braces. Braces nest.

function name ( ) { command [[ ; command ] ... ] } ;

Defines a function called name. Parameters are substituted by position at call time, they are not prototyped in the definition. No commands are executed until the function is invoked.

select column_list from table_list [ where sql_expression ] [ process { command-list } ] ;

Select the named column(s) from the named table(s). If the process clause exists, the listed commands are executed for each row returned. Sql_expression is the usual SQL where clause plus Cavor spatial extensions.

TODO: more commands, examples

Control commands

These commands control program flow.

if ( expression ) command1 [ else command2 ]

If the expression evaluates to true (or non-zero), command1 is executed, otherwise it is skipped. If there is an 'else' part, command2 is executed when expression is false (zero).

while ( expression ) command

If expression evaluates to true (non-zero), command is executed. The expression is re-evaluated after each time command is processed.

Built-in Functions

There are a number of built in arithmetic, trignometric and string functions that can be used in the same ay as user-defined functions. These are:

abs(x)

ceil(x)

exp(x)

floor(x)

ln(x)

log(x)

sign(x)

sqrt(x)

trunc(x)

sin(x)

cos(x)

tan(x)

asin(x)

acos(x)

atan(x)

Examples

The following example is a simple 'while' loop that counts down from 5:

# test case for a while loop 
message "Countdown"; 
idx := 5; 
while ( $idx > 0 ) { 
        message " idx = "; 
        message $idx; 
        idx := $idx - 1; 
}; 
message "done."; 
. 

The next example illustrations function definition and use:

# demo a function 
function square() { 
        return $p1 * $p1; 
}; 
message "Testing"; 
message "3 squared is"; 
message square(3); 
message "45 squared is" + square(45); 
message "done."; 
. 

TODO: more examples, show output.

Appendix: CSL Grammar

TODO: include here the flex/bison (lex/yacc) files.