Basics

Calcscript is a stack based language.

Script is executed from left to right. When a number is found it is pushed onto the stack and appears on the right side of result. Each operator takes arguments from the top of the stack (right side) and leaves result on the stack.

Let's look how this fragment of code is executed: 2 3 8+* .

First number 2 is found and placed on top of the stack:

2

The space between 2 and 3 is ignored.

Then 3 is placed on the stack:

2 3

The same happens for 8 :

2 3 8

Next symbol - + is an operator that takes two top-most numbers from stack and places a result. After applying it the stack looks like that:

2 11

Multiplying star also takes two arguments and leaves one result:

22

Below you have an interactive Calcscript session, change numbers or operators to see what happens:

22

Defining custom functions

Calcscript has several built-in functions for simple calculations like sum of an array sum: [1 2 3]sum.

But what if we need something custom? Calcscript allows you to define your own function based on the built-in operators.

As an example lets define an function that calculates the average of an array.

First, take a sample set of data that will be used to calculate the average:

[1 2 4]

An arithmetic average can be calculated by dividing a sum of all elements by number of elements in array. Two operations (sum and number of elements) require two copies of an input array. To copy top of the stack use dot operator . [1 2 4].

[1 2 4] [1 2 4]

Next use sum function to - well - sum its elements: [1 2 4].sum:

[1 2 4] 7

Now to get the number of elements of the array we need to move it to the top of the stack (right side of the result). There is a built-in operator \ that swaps two top elements on stack [1 2 4].sum\:

7 [1 2 4]

The number of elements can be retrieved by comma operator , [1 2 4].sum\,

7 3

Now it's easy to get the average by dividing those two numbers [1 2 4].sum\,/ using /:

2.333

Notice that the data are clearly separated from the operations on those data and the operations are generic. Changing the array will automatically reflect the calculated average: [1 2 4 7].sum\,/

3.5

There is one more improvement that can be applied. The operation of calculating an average can be stored so it will be easier to use later. Use curly brackets to surround the operations: [1 2 4 7]{.sum\,/}

[1 2 4 7] {.sum\,/}

The curly brackets create a block of code - set of instructions that are not executed immediately. This block can be assigned to a variable, lets call it avg: [1 2 4 7]{.sum\,/}:avg. When a script contains an assignment like this Calcscript will not execute it while typing. Press = to execute it now. After that the new variable will be placed on the suggestions list.

This new variable can be used to easily calculate averages of arrays. Let's delete current calculations by long pressing on ← and type new ones: [8 4 2]avg.

4.667

This new function can be used just like a built-in one. For example to calculate an average of many arrays at once you can use [[1 2][3 4][5 6]]{avg}%

[1.5 3.5 5.5]