forked from ground/ground
300 lines
6.8 KiB
Markdown
300 lines
6.8 KiB
Markdown
## 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`
|
|
|
|
#### gettype
|
|
|
|
Gets the type of a variable. Outputs a string which can be "int", "double", "bool", "string", "char".
|
|
|
|
Usage: `gettype $value &var`
|
|
|
|
#### 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. 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 (Experimental, please report bugs!)
|
|
|
|
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`
|