The Scripting Language
Values¶
There are a couple of value types that may be manipulated by a script: Integers, Strings and null. GSL is not a strongly typed language, values need not be pre-declared. Literals, variables and constants can take any of the value types.
Integers¶
Integers represent numeric values with no fractions or decimal points. supported notations are listed below.
Integer | form | example |
---|---|---|
Hexadecimal | preceded by 0x | 0x2A , 0xFBFB |
Decimal | as usual | 42 , 64507 |
Binary | preceded by 0b | 0b00101010 , 0b1111101111111011 |
Strings¶
strings are used to represent text, a string consists of zero or more characters and can include numbers, letters, spaces and punctuation. An empty string ""
contains no characters. A string is surrounded by double quotes.
String | Represented text |
---|---|
"Hello World" | Hello World |
"200" | 200 - note this is not the integer 200 but the characters 2, 0 and 0 |
"January 12, 2021" | January 12, 2021 |
Literals¶
Literals are data that remain unchanged when the program is compiled. Literals are a way of expressing hard-coded data in a script.
Variables¶
Variables are used to store data that can be modified. A Variable has a name and holds a Value. Variable names can contain only alphanumeric characters, underscores (_) or periods(.). Starting with a number is not allowed, some examples;
X
_NewName
variableName
A variable is created with the var
keyword. Values are assigned using the assignment operator ( = ). The name of the variable goes on the left side of the operator, and the value goes on the right
var X = 10
var _NewName = X
var variableName = 100
There are two types of variables: global and local. A variable is considered Global
if it is declared outside the scope of a function or statement. Variables that are instantiated within the scope of a function or statement with the var
keyword are local
and will be available until the next end
statement.
Local variables are also created by the function's parameters list
var thisIsAGlobal
function example(Parameter)
var thisIsALocal
end
This will result in the global variable thisIsAGlobal
and the local variables Parameter
and thisIsALocal
are available within the scope of example
Expressions¶
An expression is a statement that calculates a value. In it simplest for an assignment;
x = 2
it calculates 2 as the value for x
all expressions contain operators they indicate how the expression should be evaluated in order to arrive at its value. for example x + 2
tells to add 2 to x to find the value of the expression. x > 2
indicates that x is greater than 2, this Boolean expression will evaluate to true or false. Therefore if x = 3 it will evaluate to true.
Operators¶
An operator is a symbol that represents a action that can be preformed on data, for example addition or subtraction. Operators are used to manipulate data, the data being manipulated are called operands. Literals, function calls, constants and variables can all serve as operands. In the Example x + 2
both the variable x
and the integer 2
are operands and the the +
is the operator.
Mathematical Operator | Description | Operand Types | Result type | Example |
---|---|---|---|---|
( ) | Associative | Any | Any | (2 + 4) * 3 = 18 |
* | Multiplication | Int-Int | Int | 3 * 4 = 12 |
/ | Division | Int-Int | Int | 16 / 4 = 4 |
+ | Addition | Int-Int | Int | 4 + 3 = 7 |
- | Subtraction | Int-Int | Int | 6 - 2 = 4 |
Equality Operator | Description | Operand Types | Result type | Example |
---|---|---|---|---|
== | Equal | any | Bool | 2 == 2 |
!= | Not Equal | any | Bool | 2 != 3 |
Relational Operator | Description | Operand Types | Result type | Example |
---|---|---|---|---|
< | Less than | any | Bool | |
> | Greater than | any | Bool | |
<= | Less or equal | any | Bool | |
>= | Greater or Equal | any | Bool |
Logic Operator | Description | Operand Types | Result type | Example |
---|---|---|---|---|
! | Negation | expression or Int | Int | 1 == !0 evaluates true |
& | Logic AND | expression or Int | Int | |
| | Logic OR | expression or Int | Int |
Assignment Operator | Description | Operand Types | Result type | Example |
---|---|---|---|---|
= | Assignment | Int | Int | A = 1 |
Operator precedence¶
the basic mathematic precedence of operators is used to evaluate an expression from left to right. the associative operator ()
can be used to group parts of an expression to force the groups to be evaluated first and thereby overwrite the basic precedence of operators.
5 + 6 * 4
The *
operator has the highest precedence so the multiplication is preformed first before the addition, causing the statement to evaluate to 29
( 5 + 6 ) * 4
The associative operator forces the addition to be preformed first an then multiply the result, this will evaluate the statement to 44 instead.
Comments¶
Comments may be inserted into scripts as a way to document what part of the script does or how. this can be helpfully as a way to understand how a part of the script works. additional it can be used to comment out parts of a script to alter behavior or help debugging.
Single line comment¶
A single line comment in GSL begins with a double forward slash //
everything between the double backslash and the first newline will be ignored.
// X = 2
is not considered part of the script. the comment can also start after a line of code:
X = 2 // this text is ignored, the expression is not
Multi line comment¶
GSL does support multi line comments, it will ignore ALL text between /*
and */
/*
A multi line comment will therefore look
like this.
Every thing in this part will be ignored in the actual script
*/
Keywords¶
Keyword | description |
---|---|
define | set Constant |
cancel | cancel a set event |
end | close a scope |
event | set an event |
for | for statement |
function | declare a function |
if | if statement |
var | define a (global) variable |
while | while statement |
define
keyword¶
The define
keyword allows the definition of constants in the code. these constants are not variables and cannot be changed through the script. names can contain only alphanumeric characters, underscores (_) or periods(.). starting with a number is not allowed.
Constants are declared with the define
keyword. and can only contain integers or other defines.
define nameForTen 10
define numberOfChannels 32
define bpxButton1 ui.bpx.1
end
keyword¶
The end
keyword closes the current scope, either returning to the function call or ending a loop and continue procedural code.
var x = 0
for index = 1 to 10
x = x + 1
end
x = x + 5
where the x = x + 1
statement is within the scope of the for loop while the x = x + 5
statement is not.
Statements¶
Statements are building blocks of a script, a script is made up of a list of statements. There are x
kind of statements in GSL.
- expression statements
- if statements
- if else statements
- for statements
expression
statement¶
an expression statement represents a value, variable or function, the general form is
<expression>
the different kind of expression statements can be
- Value:
x + 5
- Variable:
x = 10
- Function:
set_talk(channel_number)
The Variable expression is also called assignment statement, it assigns a value to a variable
if
statement¶
an if statement follows the following general form
if <expression>
<statement(s)>
end
for example
if 1 + 1 == 2
functionIfTrue()
end
this if
statement will evaluate the expression 1 + 1 == 2
as true and therefore execute the statement functionIfTrue()
another example
if channel.talk[1]
channel.talk[1] = channel.talk.off
end
this example will give channel one the useless machine function when executed. the expression channel.talk[1]
will evaluate true if the channel talk is enabled and execute the statement channel.talk[1] = channel.talk.off
- set talk disabled for channel one
if else
statement¶
an if statement follows the following general form
if <expression>
<statement1>
else
<statement2>
end
the <expression>
is evaluated. when true, <statement1>
is executed, when false <statement2>
is executed.
the script snippet:
if channel.talk[1]
channel.level[1] = channel.level.0db
else
channel.level[1] = -12
end
will set the level according to the talk state of channel 1, the expression channel.talk[1]
will evaluate true if the channel talk is enabled and execute the statement channel.level[1] = channel.level.0db
setting the level of the channel to 0dB. when the talk is not enabled the expression will evaluate false, therefore execute the statement channel.level[1] = -12
setting the level of the channel to -12dB.
for
statement¶
an for statement follows the following general form
for <start_expression> to <end_integer>
<statement>
end
where <start_expression>
needs to be a variable assignment whit the start value of the for loop, note that the a variable is instantiated here within the context of the for statement but the var
keyword is not used. the <end_integer>
defines te end value of the defined index variable.
the <start_expression>
is executed, after that the <statement>
s are executed, then 1 is added tot the index variable and tested against the <end_integer>
the <statement>
is repeated over and over until the the value of the <end_integer>
is reached.
the snippet;
for index = 1 to 32
channel.talk[index] = channel.talk.off
end
will iterate over all 32 channels and set its the talk state to off.
while
statement¶
a while statement follows the following general form
while
When the while <expression>
is evaluated true the <statement>
is executed. After which the <expression>
is evaluated again until it evaluates false in which case the while loop is ended. with this statement more complicated loops can be created then the basic for loop.
the snippet;
var index = 32
while index > 0
channel.talk[index] = channel.talk.off
index = index -1
end
will do exactly the same as the for loop example but in reverse order starting at channel 32.
Context¶
Functions¶
A function is a named statement or group of statements. it can be called anywhere in a script as one block or unit. A function has a name which can consist of alphanumeric characters, underscores (_) and periods(.). And can not start with a number. A function can have zero or more parameters. these parameters can be used to pass values to statements within the function. These parameters are also known as arguments. These named arguments are local variables within the scope of the function.
the syntax for a function declaration is:
name(<parameter1>,<parameter2>,...)
<statements>
end
To call a function:
name(<parameter1>,<parameter2>,...)
for example
var result
function multiply (a,b)
result = a * b
end
it would be called like this:
multiply (2,4)
the value of result
will be 8
after this call
functions calls are not checked for valid number of arguments and their value's. this means that a function call with to much arguments will ignore the arguments that are supplied to much. to less arguments will be handled as if the value 0
was passed.
multiply (2) // will set a to 2 and b to 0; as 2 * 0 = 0 the value of result will be set to 0
multiply (2,4,5) // will set a to 2, b to 4 and ignore 5; as 2 * 4 = 8 the value of result will be set to 8
Events¶
an Event is a block or unit that is executed when a specific event is triggered. All defined properties can be set to trigger the Event.
the syntax for an event declaration is:
event <property name>
<statement>
end