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

#### stdin

Allows input from the console.

Usage: `stdin &var`

#### stdout

Allows output to the console.

Usage: `stdout $value`

#### stdlnout

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

Usage: `stdlnout $value`

### Variables and Lists

#### set

Allows you to set a variable to a value.

Usage: `set &var $value`

#### 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"

#### 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

### Interacting with Libraries

#### use (Experimental, please report bugs!)

Attempts to import another Ground program. Gets inserted wherever the use statement is. Any code (including code outside function declarations) will be executed. 

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 (WORK IN PROGRESS)

Attempts to import a shared object library written for Ground. All functions in the external library will be usable with `call`.

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

Usage: `extern $stringvalue`