# CGround Syntax

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.

Return type must match the function return type.

#### endfun

Ends function definition.

#### call !function $arg1 $arg2 $arg3... &variable

Calls a function. After the function reference, a variable amount of value references may be provided to pass to the function.

The last argument must be a direct reference which symbolises where to store the function's return value.


### Libraries

#### use $libraryName

Attempts to import a library written in Ground for usage within the current program.

Looks in the path $GROUND_LIBS/`$libraryName`.grnd for the library. ($GROUND_LIBS is a system environment variable.)

#### extern $libraryName

Attempts to import a shared library written in a compiled language like C or C++ for usage within the current program.

Looks in the path $GROUND_LIBS/`$libraryName`.so for the library. ($GROUND_LIBS is a system environment variable.)