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

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

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

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

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 !functionname -type &var -type &var -type &var   # and so on...`

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

#### use

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 stored when trying to find imported programs. If that fails, it will check the directory set in the $GROUND_PATH 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`.

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

Usage: `extern $stringvalue`