7.0 KiB
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
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"
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