Functions and Scripts - dialogos-project/dialogos GitHub Wiki

(this page in German)

This chapter describes the DialogOS scripting language used in script nodes and user-defined functions. This section begins by listing all statement types, continues with descriptions of conditions and loops, and ends with details of all built-in helper functions available to simplify data access.

Note that functions can also be written in Groovy, instead of in the DialogOS scripting language.

A script can be viewed as a sequence of statements evaluated in order. A function consists of a function header containing the return type, function name and parameters in the order given, and a function body enclosed in curly brackets. An arbitrary number of parameters can be given as an expression of the form type1 name1, type2 name2, ... in parentheses. If the return type is not void, the function must return a value.

The syntax for a function is thus: return_type function_name(parameters) { function_body }. For example: int sum(int a, int b) { return a + b; }, where the parameters a and b and the return value a + b are all expressions of type int.

Statements

The DialogOS scripting language contains a number of frequently used standard statements.

Declarations: Declares a new variable. Declarations consist of the data type and the name for the new variable. Optionally, you can initialize the variable to a specified value. Example declarations are:

struct newStructure;

real pi = 3.142;

struct completeStructure = { date = { dow = "monday", month = "may" }, weekdays = [ "monday", "tuesday", "wednesday" ] };

You must declare all variables you intend to use in a script node before you write any of the other statements in the script. (With the notable exception of index variables in for loops, see below.)

Assignments:
Each variable declared in the same script scope or defined in DialogOS can be assigned a new value. The available assignment operators are =, +=, -=, /= and *=. The postfix and prefix notation of ++ and -- on variables can also be viewed as an assignment, since a = a + 1; is equal to a += 1; and a++; or ++a;.

Returns:
Within functions, it is important that a value of the correct type is returned at the end. This holds true for all data types except void. A return statement always consists of the keyword return followed by an expression that evaluates to the function's return type. For functions that return void, the return statement consists only of the keyword return. Examples:

return 3.142;

return a + b;

return;

Conditions and Looping

Functions StatementsDialogOS supports conditions and loops to control if and how often a statement or block will be executed. The following types of conditions, condition statements, and loops are available:

break;
The break statement can be used in loops or switch statements to end execution in the block currently being executed. Execution will resume with the next statement immediately following the block.

if-else
The if-else construct in DialogOS takes the form of the header and a statement block, as in:

if (expression) {}

The expression must evaluate to the boolean true or false, and the following block of statements will be executed if the condition is true. Optionally, an alternative else clause can be added causing the corresponding statement block to execute if the expression evaluates to false. If the body of the block consists of more than one statement, they must be enclosed with curly braces; otherwise, curly braces are optional for single-line statements.

Example:

if (x != 0) { x = 0; } else { x++; }

switch
Switch contructions offer the possibility of comparing a single expression with different values and then exectuting statement blocks based on a successful match. Typically, a switch statement is constructed as followed:

switch(expression) { 
   case Value: { commands; break; } 
   case Value2: 
   ... 
   default: { commands; break; }
}

A block of commands will be executed if the expression matches the Value, as shown in the example above. If you use the command break at the end of a block, the expression will not be compared to any further value, but will leave the switch block at that point. The block with the default value will be executed in any case where the switch construction was not left by way of a break.

while
A while loop consists of a condition and a block of commands that will execute as long as the given condition evaluates to true. The condition of the loop, while(expression), must contain an expression that results in a boolean value, and the body of the loop should have a block of commands to execute, as in:

int num=345; 
int fact = 1; 
while(num\>1) fact \*= num--;

do-while
A do-while loop is similar to while in that it contains a condition and a set of statements to execute. In contrast to while, the block of commands will be executed at least once before the condition is checked for the first time. The header here only consists of the keyword "do", whereas the while condition appears at the end. The condition statement has to be marked with a semicolon, as in the following example:

int num = 345; 
int fact = 1; 
do { fact \*= num--; } while(num \>1);

for
A for loop allows you to have the looping controls within the header. The header consists of three parts: initialization, the condition for looping, and a statement that will execute at the end of an iteration, typically a variable increment. The initialization can be a variable declaration or an assigment. The final statement can only be an assigment.

int num = 345; 
for(int fact = 1; num \>1; fact--) { fact \*= num; }

One-line statement blocks do not need curly braces, as in:

int num = 345; 
for(int fact = 1; num \>1; fact--) fact \*= num;

If you have no command block, you must use a semicolon so that the following command will not be interpreted as part of it. For example,

int num = 345; 
for(int fact = 1; num \>1; fact \*= num--);

Built-in functions in DialogOS

DialogOS contains the following built-in functions for use in user-defined functions as well as script nodes.

int abs(int i)
Returns the absolute value of the integer i

struct addDate(struct date, struct addition)
Calculates the sum of data and addition. data must be a full data structure {day:int, month:int, year:int}; addition may contain only some of the date fields. Years are added first, then month and then days.

Examples:

{ day=10, month=6, year=2003 } + { day=25 } = { day=5, month=7, year=2003 }

{ day=10, month=6, year=2003 } + { day=25, month=1 } = { day=4, month=8, year=2003 }

list append(list l1, list l2)
Returns a new list consisting of the concatenation of l1 and l2.

string charAt(string s, int index)
Returns the nth character of s as a string.

list concat(list lists)
Returns a new list consisting of the concatenation of all lists in lists.

list cons('a v, list l)
Returns a new list consisting of v prepended to l.

bool contains(list list, 'a v)
Returns true if l contains v, or false otherwise.

bool contains(string s, string infix)
Tests whether s contains infix.

bool contains(struct str, string key)
Returns true if str contains a label with the name key.

struct currentDate()
Returns the current day as a structure { day:int, month:int, year:int }.

struct currentTime()
Returns the current time as a structure { h:int, m:int }.

int currentTimeMillis()
Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

struct currentWeekDay()
Returns the current weekday and week of the year as a structure { day:int, week:int }. Weekdays start at 0: 0 = Sunday, 1 = Monday, ...

bool empty(list l)
Returns true if the list l is empty, false otherwise.

bool endsWith(string s, string postfix)
Returns true if s ends with postfix.

list enumerate(int i, int j, int k)
Returns a list of numbers between i and j with an interval of k in between.

void error(string e)
Throws an error message with the error text e.

real exp(real r)
Returns Euler's number e raised to the power of r.

'a get(list l, int index)
Returns the nth element of l.

'a get(struct str, string key)
Returns the element of str assigned to the label key.

'a head(list l)
Returns the first (head) element of list l.

int indexOf(list list, 'a v)
Returns the position of v in list or -1 if list does not contain v.

int indexOf(string s, string infix)
Returns the position of infix within s. If s does not infix, return -1.

bool isInt(string s)
Tests whether s can be converted to an int.

bool isReal(string s)
Tests whether s can be converted to a real.

list keys(struct str)
Returns a list of all keys in str.

int length(list l)
Returns the length of the list l.

int length(string s)
Returns the length of string s.

struct loadProperties(string directory, string filename)
Reads a file named filename from directory and returns its contents as a struct.

real log(real r)
Returns the natural logarithm of r.

struct member(list list, 'a v)
Equivalent to contains(list, v).

struct merge(struct str1, struct str2)
Returns the merger of str1 and str2.

Note that source structures are not modified. Instead, a new struct will be created and returned. If str1 and str2 both contain the same label, the result will depend on the type of its subvalues. If the label is mapped to a substructure in both str1 and str2 then these substructures are merged recursively. Otherwise the value from str2 is taken.

Examples:

merge({ x=3, y=4 }, { x=4, z=5 }) = { x=4, y=4, z=5 }

merge({ x={x=3}, y={a=4} }, { x={y=4}, y=5 }) = { x={x=3, y=4}, y=5 }

struct mergeDefined(struct str1, struct str2)
Like merge, but only overwrites the values in str1 if the value in str2 is not undefined.

int parseInt(string s)
Converts s to an int. Returns undefined if conversion fails.

real parseReal(string s)
Converts s to a real. Returns undefined if conversion fails.

print('a v)
Prints a string representation of v to stdout.

printf(string a, ...)
Prints all following parameters in the format a.

struct put(struct str, string a, 'a x)
The counterpart to get(struct, string).

int random(int min, int max)
Returns a random int between min and max inclusively.

list remove(list list, list remove)
Returns a new list consisting of all elements of list minus the elements of remove.

string replace(string s, string a, string b)
Returns a copy of s with all occurences of a replaced by b.

list reverse(list list)
Returns a reversed copy of list.

int round(real r)
Rounds r to the nearest int.

list set(list l, int index, a element) Sets the value of the list l at index index to a and yields the resulting list (the original list is overwritten).

void showDialog(string s)
Show a small window with the String s as content. The dialog continues once the user has clicked OK.

void sleep(int millis) Interrupts the script for millis milliseconds just like a separate "wait" node.

list sort(list list)
Sorts a list according to the natural order of its element. All elements must have the same type.

bool startsWith(string s, string prefix)
Tests whether s starts with prefix.

string str('a s)
Converts s to a string.

list stripSpecialCharacters(list list)
Takes a list of strings as input and returns the same list but with characters that are neither letters nor digits removed.

list sublist(list list, int offset)
Returns the sublist of list starting at offset.

list sublist(list list, int offset, int length)
Returns the sublist of list starting at offset with length length.

string substring(string s, int offset)
Returns the substring of s starting at offset.

string substring(string s, int offset, int length)
Return the substring of s starting at offset with length length.

list tail(list l)
Returns the tail of the list l, i.e. all elements except for the first.

string toLowerCase(string s)
Returns a copy of s with all characters converted to lowercase.

string toUpperCase(string s)
Returns a copy of s with all characters converted to uppercase.

list values(struct str)
Returns a list of all values in str.

Next page: Advanced Features