Variables

Variables are declared with the special keyword @var. The variable name must start with a $, and can only have the characters a-z, A-Z and 0-9 in the name. Special characters are not allowed.

@var $v1;

Multiple variables can be declared on the same line.

@var $v1, $v2, $v3;

Variables can also be assigned a value when declaring them, either from a constant value or from a function call.

@var $v1 = 0;
@var $v2 = MyFunc();

Declaring a variable with a name that already exists is allowed as long as the variable exists in a different scope.

@var $v1 = 0;
if( $v1 == 0 )
{
 @var $v1;

 // $v1 outside the if statement is not changed
 $v1 = 20;
}

You can force a variable to be declared in the global scope by using @gvar instead of @var.

@var $v1 = 0;
if( $v1 == 0 )
{
 @gvar $v2;
 
}

$v2 = 20;

Variable v2 is declared in the global scope. So it is available outside the if statement.

Arrays must be declared with a size, although you can manipulate the size later.

@var $arr[2];

Arrays can also be declared with values. In this case the size is implicit.

@var $arrStr[] = {"String1", "String2", "String3"};
@var $arrNum[] = {1, 2, 3};

Constants

Variables can be declared using number and string constants. Functions can also return constant arrays. 

@var $v1 = 2;
@var $v2 = "string";
if($v2 == "string")
{ 
...

}

Escape Sequences

To be able to type constant strings containing special characters such as the newline character, double quotation mark, tab, etc., they need to be written in a special way, using an escape sequence.

An escape sequence consists of a backslash (\) followed by a letter. Each escape sequence is regarded as a single character.

If you want an actual backslash in your constant string you need to write "\\". This will translate into "\".

$var = "C:\\Temp\\MyFolder\\File.txt";

Escape sequences are only translated inside string constants enclosed in double quotes. Using single quoted strings will not translate escape sequences. Using single quoted strings may make the code more readable, but some characters like newline and single (or double) quotes cannot be used inside these strings.

$var = 'C:\Temp\MyFolder\File.txt';

Arrays

Arrays can hold multiple values. The values can be Strings, Numbers, Handles or other arrays.

The index operator ( [ ] ) is used to access array items. It can be used to get or to set values.
If using it to set a value you must be sure that you are not trying to set an item outside the bounds of the array.

When accessing array items the index value is 0-based. Thus the first item is index 0, the second is index 1. and so forth.

@var $arr[3];
$arr[0] = 2;
$arr[1] = 6;
$arr[2] = 8;

//This will fail (out-of-bounds).
$arr[4] = 10;

When assigning one array to another, a copy of each item in the original array is created.

@var $arr[3];
$arr[0] = 2;
$arr[1] = 6;
$arr[2] = 8;

@var $arr2;
$arr2 = $arr;

Array Functions

There are several built-in array functions.
Read more about array functions

@var $arr = $arr[2] = {"item0", "item1"};
@var $count = arrayCount($arr);
// $count is 2

// Replace item 0 and 1
$arr[0] = "item1";
$arr[1] = "item2";

@var $str = $arr[1];
// $str is now "item2";

// Add and increase size of array
arrayAdd($arr, "item3");
$count = arrayCount($arr);
// $count is now 3

@var $idx = arrayFind($arr, "item3");
// $idx is 2

arrayRemove($arr, 0);
$count = arrayCount($arr);
// $count is now 2 and item "item1" has been removed

Operators

The usual arithmetic operators (+, -, *, /) are supported.

@var $v1, $v2;
$v1 = 5 + 2;
$v1 = $v1 - 1;
$v2 = $v1 * 2;
$v1 = $v2 / $v1;

Since the script engine does not do any operator prioritization, parentheses must be used if multiple operators are used on one line to guarantee that they are evaluated correctly. On number values, mathematical operations are used. The + operator for two strings will concatenate the right string with the left.

@var $result;

$result = 5 + 4 * 2;
// $result is now 18

$result = 5 + (4 * 2);
// $result is now 13

$result = "StringA" + " " + "String B";
// $result "StringA StringB";

Index Operators

The index operator ( [ ] ) is supported for both Arrays and strings. On Arrays it is used to get/set an array item. On strings it is used to get/set a character in the string.

@var $str = "MyString";
$str[0] = "Z";
// $str is now "ZyString";

$str = "abcdef";
@var $str2 = "12345";
$str[1] = $str2[3];
// $str is now "a4cdef";

Assignment Operators

The assignment operators (=, +=, -=) are used to assign the left side from the result of the expression to the right side.

@var $val = 1;
$val = 5;

// += is increment
$val += 2;
// $val is now 7

// -= is decrement
$val -= 2;
// $val is now 5

Comparison Operators

Comparison operators are used to compare two values. The result of a comparison operator is 0 for false or 1 for true. The following comparison operators are supported: == (equal), > (greater than), < (less than), >= (greater than or equal), <= (less than or equal)

@var $val = 3;
$val = $val > 2;
// $val is now 1
$val = 4;
if( $val >= 4 )
{
 ...
}

Negation Operators

The negation operator (!) is used to negate a true/false value. The result of a negation is either 0 or 1.

@var $val = 1;
if( !$val )
{
 // if $val is false
 ...
}

Special Path Operator

"^" is used as a special path operator. It will assume that both the left and right side are path items, and will insert a path separator (\) if needed.

@var $path;
$path = "C:\\Path";
$path = $path + "MyFile.txt";
// $Path is now "C:\PathMyFile.txt"

$path = "C:\\Path";
$path = $path ^ "MyFile.txt";
// $Path is now "C:\Path\MyFile.txt"

$path = "C:\\Path\\";
$path = $path ^ "\\MyFile.txt";
// $Path is now "C:\Path\MyFile.txt"

IF - Condition

The IF condition will evaluate its test expression. If the expression is greater than or equal to 1 (true) then it will execute the scope after the if statement. If it is less then 1 (false) it it will jump over the scope or go to the else statement if present.

New variables created inside the IF scope will only exist within that scope. New scope variables can be named the same as variables in the outer scope (but this is not best practice).
 

@var $v = 2;
@var $s = 1;
if($v == 2)
{
 // Local scope variable
 @var $s = 10; 
 $v = 1;
}
else if( $v >= 3)
{
 $v = 3;
}
else
{
 $v = 4;
}

if( MyFync($v) )
{
 $v = 6;
}

FOR - Loops

A FOR loop statement has 3 expressions that are evaluated.

for( <init expression>; <condition expression>; <loop expression>)
{
  <statement>
}

The Init Expression is evaluated once, before any other element of the for loop.

The condition expression is evaluated and tested each time it is about to enter the for scope.

The loop expression is evaluated each time it has ended a scope execution of the for loop.

The Initialization variable in the init-expression must be declared outside the for loop.

// Valid for expression
@var $n;
for( $n = 0; $n < 5; $n++ )
{
  ...
}

// Invalid for expression
for( @var $n = 0; $n < 5; $n++ )
{
 ...
}

A for loop terminates when the condition expression evaluates to 0 (false), or a break or return statement is executed within the loop. A continue statement in a for loop terminates only the current iteration.

@var $n;
for( $n = 0; $n < 5; $n++ )
{
  if($n == 2)
  {
   continue;
  }
  
  if($n == 4)
  {
   // break out of the loop
   break;
  }
}

WHILE - Loops

A While loop has 1 expression that is evaluated every time through the loop until it is 0 (false).

while( <expression> )
{
  <statement> 
}

A while loop can terminate when a break, or return within the statement body is executed. Use continue to terminate the current iteration without exiting the while loop. Continue passes control to the next iteration of the while loop.

@var $n = 10;
while( $n > 0 )
{
  $n--;
}

@var $success = 1;
while( $success )
{
  $success = MyFunc_DoWork();
}

Functions

With the function keyword it is possible to define a function that is called by the script.
The function must be defined before it is called. Therefore it is recommended to define all the script functions first in the script.

Functions support arguments. Parameters sent to a function will be passed by value, meaning they are passed as copies. If a variable passed as a parameter to a function is changed within the function, the original variable is not changed.

The function will return when it reaches the end of the function definition. It will by default always return 1 in this case. If some other return value from the function is wanted then a return statement must be used.

function MyFunc( $a1, $a2 )
{
 @var $result = $a1 + $a2;
 $result = $result * 2;
 return $result;
}

@var $n = 0;
$n = MyFunc( 2, 6 );

The return statement can also be used to exit from the function before it reaches the end.

function MyFunc( $a1, $a2 )
{
 @var $result = $a1 + $a2;
 if( $result > 10 )
 {
   return $result;
 }
 $result = $result * 2

 return $result;
}

@var $n = 0;
$n = MyFunc( 4, 8 );

Classes

With the class keyword it is possible to define a class. A class is a group of variables and functions that are collected together within an object. Objects in MultiScript are very simple variations of the "object" you find in languages like C++, but without the support for public/private. Everything is public here.

A class is created from a definition using the new keyword. This will create a new instance of a class.

It is not possible to delete objects while running the script.

To access a function or variable in an object a dot (".") is used to as separator between the object variable and the class variable name or function name.

When referring to a variable in an object variable the $ of the class variable is not written.

// INCORRECT
@var $n = $obj.$a;

// CORRECT
@var $n = $obj.a;

class MyClass
{
  @var $a = 0;
  @var $b = 1;
 
  function( $v1, $v2 )
  {
    $b = $v1 + $v2;
    return $b;
  }
}

@var $obj = new MyClass;
@var $result = $obj.MyFunc( 2, 5 );
@var $n = $obj.a;