Declarations

Declarations and Variables

Before variables can be used in the code, they must be declared. Variable declarations can be written using the following syntax:

declare{(1)!}var{(2)!}: int{(3)!}

The declare keyword is used to declare variables.
The name of the variable is written after the declare keyword. The variable name must start with a letter and can contain letters, numbers, underscores and dots. Variable names are case-sensitive.
The type of the variable is written after a colon. The type can be int, real, string, bool, or an object type.

Type Annotations

The type of the variable is written after a colon. However, this type annotation is optional, and the compiler will attempt to infer the type if it's not provided. Variables can be declared either individually or together. However, when declaring variables, the declare keyword must be placed at the beginning of each line.

declare var1: int, var2: real, var3: string
declare var4: int
declare var5: bool

Type-Neutral Initialization

When variables are declared without being assigned a value, they are always initialized with their type-neutral values. This means that integers are initialized to 0, strings to "", real variables to 0.0, boolean variables to false and object pointers to nil.

Variables can also have an optional inline assignment. In this case, the value is specified after the assignment operator (:=). Just as multiple variables can be declared in one line, multiple variables can also be initialized in one line. In the example below, the highlighted line initializes var2 to 3.14 and var3 to "pi".

declare var1: int := 5
declare var2: real, var3: string := 3.14, "pi"

If more variables are referenced on the left side of a declaration than there are assignment values on the right side, the compiler will attempt to initialize the remaining variables or arrays with the last provided assignment value.

declare a, b, c := 0            // All variables are initialized to 0
declare a, b, c, d := 0, 1      // Only 'a' is initialized to 0, the others to 1

Constant Variables

To declare constants, i.e., variables that cannot be changed after their declaration, the const keyword can be used. Constants must be declared inline with an assignment, meaning both the declare keyword and an assignment are required.

declare const NUM_VARS: int := 3

Constant Naming Convention

Constants are typically written in uppercase letters with underscores separating words. This is a common naming convention in programming languages.

Declarations and Arrays

Arrays allow grouping individual values into a data structure. Arrays can be declared for any of the three basic types. For brevity, here are some one-line declarations. As with variables, type annotations are optional:

declare array_i[5]: int[], array_r[5]: real[], array_s[5]: string[]

The size of the arrays must be defined at declaration and specified by an integer literal or a constant. However, if the array is initialized in the same line as it is declared, the size can be omitted.

declare array[] := [1,2,3,4,5]
message(num_elements(array))        // Will print "5"

Since the array is initialized with an initializer list, the compiler automatically sets the array size to 5 and allocates an array with the values [1,2,3,4,5]. The size constant of any array can always be retrieved later using the num_elements function.

If all indices of an array need to be set to the same value, the array can be declared as follows:

declare array[100]: int[] := [-1]

If there are fewer elements in the initializer list than the size of the array, the last value of the initializer list will be used to initialize the remaining indices of the array.

Initializer Lists in KSP

KSP also offers the option to use initializer lists for arrays. However, those can only be used for numbers, have to be given in the same line as the declaration and use parentheses instead of square brackets. To offer better compatibility with old codebases, cksp allows KSP initializer lists with parentheses when declaring arrays.

declare array[] := (1,2,3,4,5)

In all other contexts, the new syntax with square brackets has to be used.

Declarations and Multidimensional Arrays

To represent matrices or larger datasets more easily, multidimensional arrays can be used. The size of each dimension is specified by comma-separated constants or integer literals within the brackets during the declaration. In the optional type annotation, the number of opening and closing brackets represents the number of dimensions. As with one-dimensional arrays, multidimensional arrays can be declared for any of the basic types.

declare matrix[3,3]: int[][] :=  [[1,2,3],      
                                  [4,5,6],   
                                  [7,8,9]]

The extra parentheses around the groups of three values in each dimension are optional. Otherwise, multidimensional arrays behave similarly to one-dimensional arrays when declared.

message(matrix[0,0])

In the above example, message will output the value 1. As with one-dimensional arrays, the sizes of the individual dimensions can be accessed by the num_elements function as explained and an extra parameter can be passed to specify the dimension.

Persistent Declarations

To make variables and arrays persistent, vanilla KSP provides built-in functions such as make_instr_persistent(), make_persistent(), and read_persistent_var(). As a shorthand for these functions, the keywords read, pers, or instpers can be used directly within a declaration. Here, read is a shortcut for calling the latter two functions.

declare read var: real := 0.69

When multiple declarations are made in one line, all additional declaration keywords, except for declare, must precede each variable.

declare read var1, pers var2, instpers var3, const NUM_VARS := 1, 0.69, "var3", 3

Of course, array and variable declarations can be mixed together in one-line syntax without being separated, as shown in the following declaration chain:

declare read matrix[2,2], x: int, y: int := [[1,2],[3,4]], 1, 2