surf version 1.0.1: Introduction to surf's command language

2. Introduction to surf's command language

2.1 Data types

The language used in surf's scripts is quite simple. It has got a (very restricted) C-like syntax and provides the four data types

int (integer),
double (double precision float value),
string (any ""-quoted string) and
poly (any polynomial in x, y and z).

So a valid declaration/initialisation looks like:

int a=3; or int a; a=3;
double b=3.3; or double b; b=3.3;
string c="test.xwd"; or string c; c="test.xwd";
poly d=(x-3)^3-y^2+z; or poly d; d=(x-3)^3-y^2+z;

There is no comma separator like in C. Declaring a name twice results in an error. The scope of the name begins at the point of its declaration and lasts until the end of the file. There is no method of undeclaring a name.

2.2 Operators

The following arithmetic operators are implemented:

    operator | meaning          | valid data types 
    -----------------------------------------------------------------------
    +        | binary plus      | {int,double,poly}+{int,double,poly}
    +        | concatenation    | {string}+{string}
    +        | unary plus       | +{int,double,poly}
    -        | binary minus     | {int,double,poly}-{int,double,poly}
    -        | unary minus      | -{int,double,poly}
    *        | multiplication   | {int,double,poly}*{int,double,poly}
    /        | division         | {int,double,poly}/{int,double}
    %        | remainder        | {int}%{int}
    ^        | power            | {int,double}^{int,double}
             |                  | {poly}^{int}
    ( )      | brackets         | ({int,double,poly})
    =        | equals           | {poly}={int,double,poly}
             |                  | {double}={int,double}
             |                  | {int}={int}
             |                  | {string}={string}
    ==       | equal            | {int,double}=={int,double}
    !=       | not equal        | {int,double}!={int,double}
    <        | smaller than     | {int,double}<{int,double}
    <=       | smaller or equal | {int,double}<={int,double}
    >        | greater than     | {int,double}>{int,double}
    >=       | greater or equal | {int,double}>={int,double}

The precedence of operators copied from C.

2.3 Mathematical functions

There are some built-in math functions:

    function | meaning       | valid arguments            | returns
    ---------------------------------------------------------------
    sqrt     | square root   | sqrt({int,double})         | double
    pow      | power         | pow({int},{int,double})    | double
             |               | pow({double},{int,double}) | double
    sin      | sinus         | sin({int,double})          | double
    cos      | cosinus       | cos({int,double})          | double
    arcsin   | arcus sinus   | arcsin({int,double})       | double
    arccos   | arcus cosinus | arccos({int,double})       | double
    tan      | tangens       | tan({int,double})          | double
    arctan   | arcus tangens | arctan({int,double})       | double

They take int and double as argument.

2.4 String functions

There are also two functions returning strings:

    function | meaning       | valid arguments      | returns
    ------------------------------------------------------------------------
    itostr   | int to string | itostr({int})        | string
    itostrn  | int to string | itostrn({int},{int}) | string of spec. length

itostr converts its argument to a string without blanks. For example itostr( 31 ) returns "31". itostrn allows to specify the length of the string. For example:

itostrn( 3,88 ) returns "088"
itostrn( 4,88 ) returns "0088"

2.5 Polynomial functions

Some functions work on polynomials:

    function | meaning       | valid arguments           | returns
    --------------------------------------------------------------
    deg      | degree        | deg({poly})            | int
    len      | length        | len({poly})            | int
    diff     | derivative    | diff({poly},{x,y,z})   | poly
    rotate   | rotation      | rotate({poly},{double} |
             |               |   {xAxis,yAxis,zAxis}) | poly
    hesse    | hesse surface | hesse({poly})          | poly

This enables you to work out arbitrary polynomials.

2.6 First examples

Values can be passed to surf by setting global variables. The most important two global variables are curve and surface, which should be set to the polynomial whose zero set should be visualized. So the shortest effective script contains only three lines, for example:

1st example: draw the newton knot

        clear_screen;
        curve=y^2-x^2*(x+1);
        draw_curve;

2nd example: draw a sphere

        clear_screen;
        surface=x^2+y^2+z^2-80;
        draw_surface;

Both examples can be invoked by pressing the button execute script. The command draw_curve is somehow equivalent to pressing the button draw curve. The command draw_surface is somehow equivalent to pressing the button draw surface.

2.7 Conditional statements

CAUTION: There are no for and no while statements. There is only the crude

    if( INTEGER-EXPRESSION ) goto LABEL;

which you might remember from your early BASIC sessions. Here INTEGER-EXPRESSION can be arbitrary complicated as long as it results in an integer. LABEL is something like NAME: which has occurred before. Consider the example

    int i=0;
    loop:
        surface=x^2+y^2+z^2-(i+1.0)/2.0;
        clear_screen;
        draw_surface;
        filename="sphere"+itostrn( 2,i )+".ras";
        save_color_image;
        i=i+1;
    if( i<50 ) goto loop;

which obviously draws fifty spheres of increasing radius and saves them into the SUN rasterfiles:

sphere00.ras ... sphere49.ras

There exist some more commands explained briefly afterwards. C++ comments are welcome. Warning: Check if your loop terminates!

Next Previous Contents