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