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

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