Scripting:Syntax

[[Category:Scripting]]
{{ScriptingMenu}}
__TOC__

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 {{code|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 {{code|If}}, {{code|Else}} and {{code|ElseIf}} statements.
{{code|If}} and {{code|ElseIf}} statements are followed by a boolean expression between round brackets.
Code blocks following the {{code|If}}/{{code|Else}}/{{code|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: {{code|For}}, {{code|For Each}}, {{code|While}} and {{code|Do...While}} loops.
They work similar to the equally named loops in other programming languages.

The {{code|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 {{code|For Each}} loop iterates all elements of a class implementing the interface {{code|ICollection}}.
You can recognize classes implementing this interface by the few methods in the interface.
Note that using {{code|For Each}} on dictionaries and hash tables will loop the {{code|DictionaryEntry}} structs in the dictionary and not the keys or values.
You can however loop {{code|Dictionary.Keys}} or {{code|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 {{code|DictionaryEntry}} structs.

The {{code|While}} and {{code|Do...While}} loops continue to loop while a boolean expression evaluates to {{code|True}}.
The difference between the {{code|While}} and {{code|Do...While}} loops is when the boolean expression is evaluated.
{{code|While}} loops check the expression at the beginning of each iteration, {{code|Do...While}} loops check the expression at the end of each iteration.
As a result, {{code|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 [[Scripting:Operators#Increment and decrement operators|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 {{code|Exit For}}, {{code|Exit Do}} and {{code|Exit While}}. The example below should illustrate this. 

<pre>
// 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;
  }
}
</pre>

== Functions (user defined) ==

You may define your own functions using the following syntax: {{code|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 {{code|Return [value];}}.
If a function has no return type, {{code|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)

== Casting ==

On occasion, it might be required to cast an object to a different type, for example after retrieving it from a {{Code|CObjectHashTable}}. There are two ways to go about this: implicit and explicit casting. These two ways will be explained in more detail below. When casting objects to different types, it is important to remember that you can not simply cast an object to a random type. The compiler will not complain when you cast a CObjectHashTable to a CMyShip, but you will encounter a runtime exception if you try to execute the script. In general, you can always cast an object to any parent class and it's actual type. However, there are exceptions to this rule. For one, a lot of data types and classes can be cast to a String.


=== Implicit casting ===
Implicit casting is done by assigning an object to a variable of the desired type or passing it to a function that takes an argument of the desired type. Some examples:
<pre style="overflow:auto">
// Implicit casting by assignment
Var Obj As Object = "Hello world!"; // This is actually already an implicit cast from a String to an Object.
WriteLine(Obj.Length);              // this won't work because the class Object does not have a Length member
Var StringObject As String = Obj;   // Obj is implicitly cast to a String
WriteLine(StringObject.Length);     // Now we can access the Length member of the String class


// Implicit casting by function call
Function Print(Message As String) {
  WriteLine(Message);
}
Function PrintLength(Message As String) {
  WriteLine(Message.Length); // This implicitly casts Message.Length (an Integer) to a String. Note we also did this in the code above
}
Var Obj As Object = "Hello world!";
Print(Obj);                // Obj is implicitly cast to a String
WriteLine(Obj);            // Note that the Print function we defined is actually overkill here, this also implicitly casts Obj to a String.
WriteLine(Obj.Length);     // This won't work, Obj is of type Object, which does not have a Length member
PrintLength(Obj);          // This implicitly casts Obj to a String.
</pre>


=== Explicit casting ===
We can also explicitly cast an object to a different type. Sometimes this can save code, and sometimes it is required. Not all casts can be done implicitly. The general syntax is as follows: {{code|CType(Variable, [NewType])}}. There are also shorthand versions available convenience:

; {{code|CStr(Variable)}}
* {{code|CType(Variable, String)}}
; {{code|CInt(Variable)}}
* {{code|CType(Variable, Integer)}}
; {{code|CBool(Variable)}}
* {{code|CType(Variable, Boolean)}}
; {{code|CDbl(Variable)}}
* {{code|CType(Variable, Double)}}
; {{code|CDate(Variable)}}
* {{code|CType(Variable, Date)}}
; {{code|CByte(Variable)}}
* {{code|CType(Variable, Byte)}}
; {{code|CShort(Variable)}}
* {{code|CType(Variable, Short)}}
; {{code|CSng(Variable)}}
* {{code|CType(Variable, Single)}}


An example:
<pre style="overflow:auto">
// Explicit casting
Var HashTable As New CObjectHashTable();

HashTable.Add(EBeamResource.Deuterium,  "Basic fuel. Raises your voice pitch when inhaled.");  // EBeamResource.Deuterium is used as key in the hash table.
HashTable.Add(EBeamResource.AntiMatter, "Advanced fuel. Should NOT be inhaled.");
HashTable.Add(EBeamResource.Plasteel,   "Building material. Grows from trees until you reach level 8, when you're experienced enough
      to know it is actually a metal alloy combined with acrylic polymers."); 

WriteLine(HashTable.Item(EBeamResource.Plasteel).Length);                 // This won't work, CObjectHashTable.Item() returns an Object, not a String.
WriteLine(CType(HashTable.Item(EBeamResource.Plasteel), String).Length);  // We now explicitly cast the return value to a String, so we can access the String class members.
WriteLine(CStr(HashTable.Item(EBeamResource.Plasteel)).Length);           // Same as above, but less code
</pre>