This document details syntax for CGround's textual representation.
Lines with a comment start with `#`.
## References
Working with variables in CGround requires the use of sigils to determine how the variable is being used.
### Value Reference (`$`)
Prefixing a variable name with a `$` (dollar sign) inserts that value into the current instruction. Usually this means access to a variable.
Example:
```
set &x 5
# Equivalent to println 5
println $x
```
### Direct Reference (`&`)
Prefixing a variable name with a `&` (ampersand) references a variable. Usually this means a new value is being inserted into a variable.
Example:
```
set &x 5
```
### Line Reference (`%`)
Prefixing a variable name with a `%` (percentage) references a line.
Example:
```
@myLabel
jump %myLabel
```
### Label (`@`)
Prefixing a variable name with a `@` (at symbol) creates a label.
Example:
```
@myLabel
jump %myLabel
```
### Function Reference (`!`)
Prefixing a variable name with a `!` (exclamation mark) indicates definition or usage of a function.
Example:
```
fun !myFunction -int
return 0
endfun
call !myFunction &returnVal
```
### Type Reference (`-`)
Prefixing a variable name with a `-` (dash) indicates usage of a type.
Example:
```
fun !myFunction -int
return 0
endfun
```
## Types
### String
A string of characters. Equivalent to C `char*`.
Example:
```
set &x "this is a string"
```
### Int
A 64 bit signed integer. Equivalent to C `int64_t`.
Example:
```
set &x 32
```
### Double
A double-prescision floating point number. Equivalent to C `double`.
Example:
```
set &x 3.141
```
### Char
A one-byte ASCII character. Equivalent to C `char`.
Example:
```
set &x 'a'
```
### Bool
Either true or false.
Example:
```
set &x true
set &x false
```
## Instructions
### Control Flow
#### if $condition %label
Conditional jump to the specified label. If `$condition` is a boolean and is true, jumps to the specified label. Otherwise, nothing happens and execution continues.
#### jump %label
Jump to the specified label.
#### end $status
Exits the program with an integer status code.
### I/O
#### input &variable
Takes input from the stdin until a new line. Writes the input to the provided variable.
#### print $value
Prints the provided value to the stdout.
#### println $value
Prints the provided value to the stdout. Appends a new line.
### Variables and Lists
#### set &variable $value
Sets a variable to a value.
#### init &var -type
Initialises a variable with the default (or zero) value of the provided type.
#### gettype $value &variable
Gets the type of a variable and outputs it as a string to a variable.
#### exists &variable &output
Checks whether the variable exists. If so, outputs true to the output. If not, outputs false to the output.
#### setlist &varname $val1 $val2 $val3...
Initialises a list with the provided values. Any amount of values can be appended after the direct reference, which will be added to the list.
Lists are zero-indexed.
#### setlistat &listname $index $value
Sets the list at the provided index to the provided value.
Lists are zero-indexed.
#### getlistat &list $index &variable
Retrieves an element from the list at the provided index. Outputs to a variable.
#### getlistsize &list &variable
Gets the size of a list, and puts it in the variable.
#### listappend $value &list
Appends the provided value to the list.
### String Operations
#### getstrsize $string &variable
Gets the size of a string and outputs it to the provided variable.
#### getstrcharat $string $index &variable
Gets a character from the string at the provided index and outputs it to the variable.
### Maths
#### add $value $value &variable
Adds two values and outputs to a variable.
The two values can be:
* string and string (concatenates)
* int and int
* double and double
* int and double (In this case, the int will be promoted to a double.)
#### subtract $value $value &variable
Subtracts the RHS value from the LHS value and outputs to a variable.
The two values can be:
* int and int
* double and double
* int and double (In this case, the int will be promoted to a double.)
#### multiply $value $value &variable
Multiplies two values and outputs to a variable.
The two values can be:
* int and int
* double and double
* int and double (In this case, the int will be promoted to a double.)
#### divide $value $value &variable
Divides the LHS by the RHS and outputs to a variable.
The two values can be:
* int and int
* double and double
* int and double (In this case, the int will be promoted to a double.)
### Comparisons
#### equal $value $value &variable
If the two provided values are the same, outputs true to the variable. Otherwise, outputs false.
Note: If provided values are of different types, outputs false by default.
If comparing an int and double, the int will be promoted to a double.
#### inequal $value $value &variable
If the two provided values are not the same, outputs true to the variable. Otherwise, outputs false.
Note: If provided values are of different types, outputs true by default.
If comparing an int and double, the int will be promoted to a double.
#### not $value &variable
Outputs to the variable the opposite of the provided boolean (true becomes false, false becomes true).
#### greater $value $value &variable
If the LHS is greater than the RHS, outputs true to the variable. Otherwise, outputs false.
The two values can be:
* int and int
* double and double
* int and double (In this case, the int will be promoted to a double.)
#### lesser $value $value &variable
If the LHS is lesser than the RHS, outputs true to the variable. Otherwise, outputs false.
The two values can be:
* int and int
* double and double
* int and double (In this case, the int will be promoted to a double.)
### Type Conversions
Notice: Most instructions in this section are currently unstable. Please report any bugs in this Git repository.
#### stoi $value &variable
Converts a string to an integer. Outputs to a variable.
#### stod $value &variable
Converts a string to a double. Outputs to a variable.
#### tostring $value &variable
Converts any type to a string.
### Functions
#### fun !functionName -returnType -argType &arg1 -argType &arg2...
Creates a function with the name `functionName`, and return type `returnType`.
Arguments are defined with the type reference, then the direct reference symbolising the name of the argument.
Any Ground instructions between this instruction and the concluding `endfun` instruction will be added to the function and not run immediately.
#### return $value
Returns a value from a function. If not inside a function, acts like the exit instruction.
Creates a new struct which can be initialised. Until the endstruct keyword, the only valid instructions are init, set, fun, endfun, struct, and endstruct.
Any value created inside the struct will be added to the struct.
#### endstruct
Ends the creation of a struct.
#### getfield $object &fieldName &outputVar
Gets a field from an initialised object. fieldName must be a valid name of a field in the object. Errors if the field does not exist.
#### setfield &object &fieldName $value
Sets a field to a new value in the object. The value must be of the same type as the field's old value.
