# Special Operators

This section presents a collection of operators that do not fit into any of the other categories. Nevertheless, most of them are extremely useful. Some of them are even necessary for the interaction of Cinderella and CindyScript.

## Moving Elements

The calculations within CindyScript can be used to control the positions of free elements in a Cinderella construction. One way of doing this is to explicitly set the position information of a free element. For instance, if `A` is a free point, the line `A.xy=[1,1]` sets this point to the coordinates `[1,1]`. Another way of moving an element is with the `moveto` operator.

### Moving a Free Element `moveto(<geo>,<vec>)`:

Description: In this operator, `<geo>` is a free geometric object and `<vec>` describes a position to which this object should be moved. Invoking this operator simulates a move for this geometric object.
If `<geo>` is a free point, then `<vec>` can be a list `[x,y]` of two numbers or a list `[x,y,z]` of three numbers. The first case is interpreted as Euclidean coordinates, while the second case is interpreted as homogeneous coordinates and sets the point to `[x/z,y/z]`.
If `<geo>` is a free line, then `<vec>` has to be a list of three numbers `[a,b,c]`, and the line is set to the line described by the equation `a∗x + b∗y + c = 0`.
Examples: The following code lines summarize possible ways to move geometric elements (we also include the possibilities of moving elements by accessing their data fields):

    //A is a free point
    moveto(A,[1,4]);        //moves A to Euclidean coordinates [1,4]
    A.xy=[1,4];             //moves A to Euclidean coordinates [1,4]
    A.x=5;                  //sets the x coordinate of A to 5, lets the y coordinate unchanged
    A.y=3;                  //sets the y coordinate of A to 3, lets the x coordinate unchanged
    moveto(A,[2,3,2]);      //moves A to homogeneous coordinates [2,3,2]
    A.homog=[2,3,2];        //moves A to homogeneous coordinates [2,3,2]

    //a is a free line
    moveto(a,[2,3,4]);      //moves a to homogeneous coordinates [2,3,4]
    a.moveto=[2,3,4];       //moves a to homogeneous coordinates [2,3,4]

    //b is a line through a point
    a.slope=1;              //sets the slope of the line to 1

    //C is a circle with free radius
    C.radius=1;             //sets the radius of the circle to 1

### Who has moved `mover()`:

Description: This operator gives a handle to the element that is currently moved by the mouse.

### The simulation `simulation()`:

Description: This operator provides a handle to the simulation environment. With this operator one can access, for instance, the total kinetic or potential energy. The following fields are important in accessing a simulation:

- friction: total friction of the simulation (real number, read write)
- gravity: total gravity of the simulation (real number, read write)
- kinetic: total kinetic energy of the simulation (real number, read only)
- ke: total kinetic energy of the simulation (real number, read only)
- potential: total potential energy of the simulation (real number, read only)
- pe: total potential energy of the simulation (real number, read only)

## User Input

Sometimes it is desirable to handle user input by mouse or the keyboard explicitly. There are special evaluation times "Mouse Down," "Mouse Up," "Mouse Click," "Mouse Drag," and "Key Typed" for this (see Entering Program Code). These evaluation times are captured exactly when the corresponding events occur. If one wants to react to the corresponding event data, there are two operators that read the input data.

### Mouse position `mouse()`:

Description: Returns a vector that represents the current position of the mouse if the mouse is pressed. The vector is given in homogeneous coordinates (this allows also for acces of inifite objects). If one needs the two-dimensional euclidean coordinates of the mouse position one can access them via `mouse().xy`.

### Key input `key()`:

Description: Returns a string that contains the last typed character.

## Console Output

The CindyScript input window possesses a console to which one can direct text output. For most practical purposes this will not be used for the final construction. However, it is extremely useful for debugging.

### Printing text `print(<expr>)`:

Description: This operator prints the result of evaluating `<expr>` to the console.

### Printing text `err(<expr>)`:

Description: Prints the result of evaluating `<expr>` to the console. If `<expr>` is a variable, the variable name is printed as well. Very useful for debugging.

### Printing text `println(<expr>)`:

Description: This operator prints the result of evaluating `<expr>` to the console and adds a newline character to the end of the text.

### Printing a newline `println()`:

Description: This operator prints a newline character to the console.

### Clearing the console `clearconsole()`:

Description: Removes all text from the console.

### Conditional print `assert(<bool>,<expr>)`:

Description: This operator is mainly meant for convenience purpose when generating own error mesages. it is equivalent to `if(!<bool>,println(<expr>))`. It can be used to test wheter a condition is met and otherwise generate an error message.
Example: A typical usage of this operator may look as follows

    assert(isinteger(k),"k is not an integer");

## Time

CindyScript has an internal clock that provides access to the current date and time. The clock can be also used to synchronize some automated animations. Furthermore, an operator is provided that is synchronized with the current timestamp of a running animation or physics simulation.

### Accessing time `time()`:

Description: This operator returns a list `[h,m,s,ms]` of four integers. The four values correspond to "hour," "minute," "second," "millisecond" on the computer's clock.
Example: The following code produces a simple clock on a Cinderella view. The variable `t` contains the time information. The subsequent code is used to produce a clocklike drawing on the view. An auxiliary function `p(w)` is defined that produces points on the unit circle. The code must be placed in the "Tick" section of CindyScript in order for it to run continuously.

    t=time();

    p(x):=[sin(2*pi*x),cos(2*pi*x)];
    O=[0,0];
    S=p(t_3/60)*4;
    M=p(t_2/60)*5;
    H=p((t_1*60+t_2)/(12*60))*3.5;
    draw(O,S);
    draw(O,M,size->2);
    draw(O,H,size->3);
    apply(1..12,draw(p(#/12)*5));
    apply(1..60,draw(p(#/60)*5,size->1));

    drawtext((3,5),t);

### Accessing the date `date()`:

Description: This operator returns a list `[y,m,d]` of three integers. The three values correspond to "year," "month," and "day" on the computer's calendar.

### Timestamp `seconds()`:

Description: Returns the time elapsed since the last evaluation of `resetclock()`. The time is scaled in a way such that one unit corresponds to one second. The time's resolution is on the millisecond scale.

### Resetting the internal seconds `resetclock()`:

Description: Resets the value of the `seconds()` operator.

### Accessing the timestamp of a simulation `simulationtime()`:

Description: This operator gives a handle to the running time clock synchronized with the progression of an animation or simulation.
Caution: This operator is not yet properly implemented.

## File operations

There is a limited number of operations that allow for the interaction of CindyScript with files that are stored elsewhere on the computer.

### Loading data `load(<string>)`:

Description: This operator takes the argument `<string>`, which is considered to be a file name (possibly preceded by directory information). If the file name is legitimate, then the entire information contained in the file will be returned as a string. This operator is particularly useful together with the `tokenize` operator, which helps to analyze structured data. The data are read from the currently active directory, which can be set with the `setdirectory` operator.
Example: Assume that in the file `LoadDemo.txt` the following data are stored:
`abc,gfdg;1,3,5.6,3.141;56,abc,xxx,yyy`
The following code reads the data and creates a list by tokenizing it with respect to ";" and ",".

    x=load("LoadTest.txt");
    y=tokenize(x,(";",","));
    apply(y,println(#));

The resulting output is

    [abc,gfdg]
    [1,3,5.6,3.141]
    [56,abc,xxx,yyy]

### Importing program code `import(<string>)`:

Description: This operator takes the argument `<string>`, which is considered to be a file name (including directory information). If the file name is legitimate, then the whole content of the file is assumed to be able to be parsed by CindyScript code, and it is immediately executed. In this way, one can load libraries with predefined functionality. It is advisable to use the `import` operator only in the "Init" section of CindyScript, since otherwise, the file will be read for each move.

### Setting the directory `setdirectory(<string>)`:

Description: This operator sets the directory for all subsequent file operations.

### Opening a web page `openurl(<string>)`:

Description: Opens a browser with the webpage given in <string>.

## Parsing

### Parsing a string `parse(<string>)`:

Description: This operator parses a string to an expression and evaluates this expression. This operator is particularly useful in handling user input from text fields in a construction.
Examples:

expression | evaluates to
`parse("3+7")` | `10`

The code fragment

    text="sin(x)+cos(x)";
    f(x):=parse(text);

defines the function `f(x)` to be `sin(x)+cos(x)`.

## Interaction with geometry

### Forcing a repaint operation `repaint()`:

Description: This operator causes an immediate repaint of the drawing surface. This operator is meant to be used whenever a script has updated a construction and wants to display the changes. It is not allowd to use this operator in the `draw` or in the `move` slot.

### Points on a locus `locusdata(<locus>)`:

Description: This operator returns a list of points in xy-coordinates that are all on a locus given by the name `<locus>` of a geometric element.

### Points on a locus `incidences(<geo>)`:

Description: This operator returns a list all the elements that are generically incident to a geometric element `<geo>`.

## Physics

### Applying a force `addforce(<mass>,<vec>)`:

Description: Applying a force `<vec>` to an existing mass `<mass>`. This operator is very useful to implement user defined force fields. It should be called in the `Integration Tick` slot.

### Applying a force `setforce(<mass>,<vec>)`:

Description: Setting the force `<vec>` for an existing mass `<mass>`. This operator is very useful to implement user defined force fields. It should be called in the `Integration Tick` slot.

### Probing particle forces `force(<vector>)`:

The operator `force` is closely related to physics simulations in CindyLab. It can be used for testing the force that would affect a mass particle at a specific position. The vector `<vector>` represents the position. The operator returns a two-dimensional vector that is the force at this position. If no modifiers are used, the operator assumes that the probe particle has `mass=1`, `charge=1` and `radius=1` (see Free Mass).
The following picture was generated using the `drawforces` operator and a color plot of the `force` operator. It shows the force field and force strength of the electrostatic field of two charges.

    A.charge=(|C,G|-3)*3;
    B.charge=(|E,H|-3)*3;
    f(x):=max((0,min([x,1])));
    colorplot([0.1,0.1,0.1]+hue(f(abs(force(#)/3))),(-10,-10),(20,10));
    drawforces(stream->true,move->0.2,color->[0,0,0],resolution->10);

Modifiers: It is also possible to set the values of mass, charge and radius explicitly. Each of these values can be set by a modifier of the same name. If at least one of these values is set explicitly, then all unset values are set to zero. Thus `force((0,0),charge->2)` tests the force that would be present for a particle of `charge=2`, `mass=0`, and `radius=0` at `point [0,0]`.

Page last modified on Thursday 25 of May, 2006 [23:32:00 UTC].
The original document is available at http://doc.cinderella.de/tiki-index.php?page=Special%20Operators