Scripting:Syntax

From STNE Wiki

Revision as of 19:13, 4 November 2010

This page describes the syntax of the STNE scripting engine.

As with C style languages, function calls, variable declarations and assignments have to be terminated by a semicolon.

Variable declaration

Variables are declared using the syntax Var [VarName] As [VarType]. This is best illustrated with a small example:

Var WelcomeMessage As String; // Declares a variable named 'WelcomeMessage' of type String
Var DataTable As CTable;      // Declares a variable named 'DataTable' of type CTable


/* It is also possible to immediately assign a value when declaring variables */

Var WelcomeMessage As String = "Hello galaxy!"; // Declares a string and assigns it a value
Var DataTable      As CTable = New CTable();    // Declares a variable and assigns a newly created CTable to it
Var InfoTable      As New CTable();             // Also declares a variable and assigns a newly created CTable to it, but with less code

Conditional statements

It is possible to wrap code in conditional code blocks by using If, Else and ElseIf statements. If and ElseIf statements are followed by a boolean expression between round brackets. Code blocks following the If/Else/ElseIf statements have to be wrapped in curly brackets.

An example:

If (x <= 5) {
  WriteLine("Five or less.");
}
ElseIf (x <= 10) {
  WriteLine("More than five.");
  WriteLine("Ten or less.");
}
Else {
  WriteLine("More than ten.");
}

Loops

There are a few kind of loop types: For, For Each, While and Do...While loops. They work similar to the equally named loops in other programming languages.

The For loop will increment a specified counter by a given step until a given limit is reached. The initial value, limit and step can be negative and they can be floating point values. If a step is omitted, the default value of 1 will be used.

The For Each loop iterates all elements of a class implementing the interface ICollection. You can recognize classes implementing this interface by the few methods in the interface. Note that using For Each on dictionaries and hash tables will loop the DictionaryEntry structs in the dictionary and not the keys or values. You can however loop Dictionary.Keys or Dictionary.Values if you are only interested in either the keys or the values. If you need both the keys and values, it is recommended to loop the DictionaryEntry structs.

The While and Do...While loops continue to loop while a boolean expression evaluates to True. The difference between the While and Do...While loops is when the boolean expression is evaluated. While loops check the expression at the beginning of each iteration, Do...While loops check the expression at the end of each iteration. As a result, Do...While loops are always executed at least once.

An example:

/* This will print each number from 0 to 10. 0 and 10 included. */
Var i As Integer;
For (i = 0 To 10) {
  WriteLine(i);
}

/* This will print all even numbers from 10 to 0. 10 and 0 included, in reverse order. */
Var i As Integer;
For (i = 10 To 0 Step -2) {
  WriteLine(i);
}

/* This will print the name of each ship in the SRS report of the ship with NCC 123456 */
Var MyShip As New CMyShip(123456);
Var Current As CShip;
For (Each Current In MyShip.SRS) {
  WriteLine(Current.Name);
}

/* This will print each number from 0 to 10. 0 and 10 included. */
i = 0;
While (i <= 10) {
 WriteLine(i++);    // i++ increases i by one and returns the old value, see Operators for details.
}

/* This will print each number from 0 to 11. 0 and 11 included! */
i = 0;
Do {
 WriteLine(i++);
}
While(i <= 10)

Breaking from loops

Sometimes you may want to exit a loop early. This can be done using Exit For, Exit Do and Exit While. The example below should illustrate this.

// This prints 0 to 5
Var I As Integer = 0;
While(I < 10) {
  WriteLine(I);
  If (I = 5) {
    Exit While;
  }
  I = I + 1;
}


// This prints 0 to 5
I = 0;
Do {
  WriteLine(I);
  If (I = 5) {
    Exit Do;
  }
  I = I + 1;
} While (I < 10)


// This prints 0 to 5, exactly once and NOT ten times.
// The inner loop breaks from the outer loop, in effect breaking from both the inner and outer loop.
Var J As Integer = 0;
For (J = 1 To 10) {
  I = 0;
  While(I < 10) {
    WriteLine(I);
    If (I = 5) {
      Exit For;
    }
    I = I + 1;
  }
}

Functions (user defined)

You may define your own functions using the following syntax: Function [Name]([Param1Name] As [Param1Type], ...) As [ReturnType] followed by a code block wrapped in curly braces. Functions can have zero or more parameters. The return type is optional. You can define multiple functions with the same name, as long as they have a different amount of parameters. Different types of parameters is not enough for user defined functions. Functions can return a value with the keyword Return [value];. If a function has no return type, Return; will exit the function.

A few examples:

/* This function simply prints "Hello" */
Function WriteHello() {
  WriteLine("Hello");
}

/* It is possible to defined multiple functions with the same name, if they have a different amount of parameters.
   Functions without return type can use Return to quickly exit the function. */
Function WriteHello(DoSomething As Boolean) {
  If (NOT DoSomething) {
    Return;
  }
  WriteLine("Hello");
}

/* This function prints the message passed to it as the first parameter */
Function WriteMsg(Msg As String) {
  WriteLine(Msg);
}

/* This function returns True if A is higher than B, False otherwise */
Function isHigher(A As Integer, B As Integer) As Boolean {
  Return A > B;
}

WriteHello();               // This will now print "Hello";
WriteHello(True);           // This also prints "Hello"
WriteHello(False);          // This will not do anything;
WriteMsg("Hello");          // This also prints "Hello"
WriteLine(isHigher(10, 5)); // This will print "True" (the Boolean return value is implicitly cast to a String)