ground_fork/docs/syntax.md

## Ground Syntax Guide

## General syntax

Ground uses simple instructions and arguments to run code.

```
  instruction arg1 arg2 arg3
```

As an example:

```
  stdout "Hello, World!"
```

Reference a variable's value (a value reference) with a dollar sign:

```
  stdout $myVar
```

Reference a variable itself (a direct reference) with an and sign:

```
  stdin &myVar
```

Reference a line (a line reference) with a percent symbol before a line number:

```
  jump %10
```

Alternatively, set a label:

```
  @myLabel   # The '@' symbol denotes setting a label
```

and jump to that (setting labels will be discussed below):

```
  jump %myLabel
```

Reference a list (a list reference) with an asterisk:

```
  setlist *myList $value1 $value2 # and so on
```

Add comments with a `#`:

```
  # This is a comment
```

## Keywords

Note: &var can be replaced with any direct reference. $value can be replaced with a literal value or a value reference. %1 can be replaced with a line reference.

Note: In most of these functions, if a direct reference is used, the value outputted by that function will be avaliable at that variable. Any existing value inside that variable will be overwritten.

### Control Flow

#### if

Make a decision based on a boolean. If the boolean is true, jumps to the line referenced.

Usage: `if $value %1`

#### jump

Jumps to the line referenced.

Usage: `jump %1`

#### end

Ends the program. Requires an integer for a status code.

Usage: `end $intvalue`

### I/O

#### input (or stdin)

Allows input from the console.

Usage: `input &var`

#### print (or stdout)

Allows output to the console.

Usage: `print $value`

#### println (or stdlnout)

Allows output to the console, appending a new line at the end.

Usage: `println $value`

### Variables and Lists

#### set

Allows you to set a variable to a value.

Usage: `set &var $value`

#### gettype

Gets the type of a variable. Outputs a string which can be "int", "double", "bool", "string", "char".

Usage: `gettype $value &var`

#### exists

Checks if a variable exists with a direct reference. If the variable exists, outputs true. Otherwise outputs false.

Usage `exists &var1 &var2`

Note: You can also replace &var1 with a list or line reference to check if it also exists

#### setlist

Allows you to initialize a list.

Usage: `setlist *list $value1 $value2 $value3...`

#### setlistat

Sets a list item at an index. The item at the index must already exist. Lists are index 0.

Usage: `setlistat *list $intvalue $value`

#### getlistat

Gets a list item at an index, and puts it in the variable provided. The item at the index must already exist. Lists are index 0.

Usage: `getlistat *list $intvalue &var`

#### getlistsize

Gets the size of a list and puts it in the variable provided.

Usage: `getlistsize *list &var`

#### listappend

Appends an item to a list.

Usage: `listappend *list $var`

### String Operations

#### getstrsize

Gets the size of a string and puts it in the variable provided.

Usage: `getstrsize $stringvalue &var`

#### getstrcharat

Gets a character at a certain position in a string and saves it to a variable.

Usage: `getstrcharat $stringvalue $intvalue &var`

### Maths

#### add

Adds two numbers. Numbers mean an integer or a double. Outputs to a direct reference.

Usage: `add $value $value &var`

#### subtract

Subtracts two numbers. Numbers mean an integer or a double. Outputs to a direct reference.

Usage: `subtract $value $value &var`

#### multiply

Multiplies two numbers. Numbers mean an integer or a double. Outputs to a direct reference.

Usage: `multiply $value $value &var`

#### divide

Divides two numbers. Numbers mean an integer or a double. Outputs to a direct reference.

Usage: `divide $value $value &var`

### Comparisons

#### equal

Checks if two values are equal. Outputs a boolean to a direct reference.

Usage: `equal $value $value &var`

#### inequal

Checks if two values are not equal. Outputs a boolean to a direct reference.

Usage: `inequal $value $value &var`

#### not

Negates a boolean.

Usage: `not $value &var`

#### greater

Checks if the left value is greater than the right value. Outputs a boolean to a direct reference.

Usage: `greater $value $value &var`

#### lesser

Checks if the left value is lesser than the right value. Outputs a boolean to a direct reference.

Usage: `lesser $value $value &var`

### Type Conversions

#### stoi

Converts a string to an integer. Throws an error if the string cannot be turned into an integer.

Usage: `stoi $stringvalue &var`

#### stod

Converts a string to a double. Throws an error if the string cannot be turned into a double.

Usage: `stod $stringvalue &var`

#### tostring

Converts any type to a string.

Usage: `tostring $value &var`

### Functions and function specific features (Experimental, please report bugs!)

Some symbols specific to this category:

* `!function`: A function reference

* `-type`: A type reference. Can be one of the following: "-string", "-char", "-int", "-double", "-bool", or a custom struct (see "Custom data structures" below)

#### fun

Defines a function. All code between `fun` and `endfun` will be included in the function.

Usage: `fun -type !functionname -type &var -type &var -type &var   # and so on...`

Usage note: The first type specified before the function name must be the return type. The type displayed before all vars shows what type that variable must be.

#### return

Returns back to the main program (or other function that called this function). Also returns a value, which must be of the type defined when defining the function.

Usage: `return $value`

#### endfun

Ends a function definition. When a function reaches the end the argument list will be cleared.

Usage: `endfun`

#### pusharg

Adds a value to the argument list which will be passed to the function when it is called.

Usage: `pusharg $value`

#### call

Calls a function, with all the arguments in the argument list. The return value will be put in the specified variable.

Usage: `call !function &var

### Custom Data Structures

#### struct

Begins creation of a custom data structure, which can contain values and functions. Similar to a class or struct in other programming languages.

In between the `struct` and `endstruct` lines, you can insert the following:

* `init` statements, to initialize values
* `fun`/`endfun` statements, to add member functions to the struct

When calling a function from inside a struct, all members of the struct are avaliable to read from and write to.

Usage: `struct -structName`

#### endstruct

Ends creation of a custom data structure.

Usage: `endstruct`

#### init

Initialises a variable with the default value of a type.

Usage: `init &var -type`

### Interacting with Libraries

#### use

Attempts to import another Ground program. Gets inserted wherever the use statement is. Any code (including code outside function declarations) will be executed. All functions from the library will be given a prefix, meaning functions will be registered as `!libName:functionName`.

Note: Ground will check the directory where the program is being run from when trying to find imported programs. If that fails, it will check the directory set in the $GROUND_LIBS environment variable set by your system. The '.grnd' extension is appended automatically.

Usage: `use $stringvalue`

#### extern

Attempts to import a shared object library written for Ground. All functions in the external library will be usable with `call`. All functions from the library will be given a prefix, meaning functions will be registered as `!libName:functionName`.

Note: Ground will check the directory set in the $GROUND_LIBS environment variable set by your system. The '.so' (Linux), '.dylib' (macOS), or '.dll' (Windows) extension is appended automatically.

Documentation on how to do external libraries coming soon.

Usage: `extern $stringvalue`