# CGround Syntax This document details syntax for CGround's textual representation. Lines with a comment start with `#`. ## References Working with variables in CGround requires the use of sigils to determine how the variable is being used. ### Value Reference (`$`) Prefixing a variable name with a `$` (dollar sign) inserts that value into the current instruction. Usually this means access to a variable. Example: ``` set &x 5 # Equivalent to println 5 println $x ``` ### Direct Reference (`&`) Prefixing a variable name with a `&` (ampersand) references a variable. Usually this means a new value is being inserted into a variable. Example: ``` set &x 5 ``` ### Line Reference (`%`) Prefixing a variable name with a `%` (percentage) references a line. Example: ``` @myLabel jump %myLabel ``` ### Label (`@`) Prefixing a variable name with a `@` (at symbol) creates a label. Example: ``` @myLabel jump %myLabel ``` ### Function Reference (`!`) Prefixing a variable name with a `!` (exclamation mark) indicates definition or usage of a function. Example: ``` fun !myFunction -int return 0 endfun call !myFunction &returnVal ``` ### Type Reference (`-`) Prefixing a variable name with a `-` (dash) indicates usage of a type. Example: ``` fun !myFunction -int return 0 endfun ``` ## Types ### String A string of characters. Equivalent to C `char*`. Example: ``` set &x "this is a string" ``` ### Int A 64 bit signed integer. Equivalent to C `int64_t`. Example: ``` set &x 32 ``` ### Double A double-prescision floating point number. Equivalent to C `double`. Example: ``` set &x 3.141 ``` ### Char A one-byte ASCII character. Equivalent to C `char`. Example: ``` set &x 'a' ``` ### Bool Either true or false. Example: ``` set &x true set &x false ``` ## Instructions ### Control Flow #### if $condition %label Conditional jump to the specified label. If `$condition` is a boolean and is true, jumps to the specified label. Otherwise, nothing happens and execution continues. #### jump %label Jump to the specified label. #### end $status Exits the program with an integer status code. ### I/O #### input &variable Takes input from the stdin until a new line. Writes the input to the provided variable. #### print $value Prints the provided value to the stdout. #### println $value Prints the provided value to the stdout. Appends a new line. ### Variables and Lists #### set &variable $value Sets a variable to a value. #### init &var -type Initialises a variable with the default (or zero) value of the provided type. #### gettype $value &variable Gets the type of a variable and outputs it as a string to a variable. #### exists &variable &output Checks whether the variable exists. If so, outputs true to the output. If not, outputs false to the output. #### setlist &varname $val1 $val2 $val3... Initialises a list with the provided values. Any amount of values can be appended after the direct reference, which will be added to the list. Lists are zero-indexed. #### setlistat &listname $index $value Sets the list at the provided index to the provided value. Lists are zero-indexed. #### getlistat &list $index &variable Retrieves an element from the list at the provided index. Outputs to a variable. #### getlistsize &list &variable Gets the size of a list, and puts it in the variable. #### listappend $value &list Appends the provided value to the list. ### String Operations #### getstrsize $string &variable Gets the size of a string and outputs it to the provided variable. #### getstrcharat $string $index &variable Gets a character from the string at the provided index and outputs it to the variable. ### Maths #### add $value $value &variable Adds two values and outputs to a variable. The two values can be: * string and string (concatenates) * int and int * double and double * int and double (In this case, the int will be promoted to a double.) #### subtract $value $value &variable Subtracts the RHS value from the LHS value and outputs to a variable. The two values can be: * int and int * double and double * int and double (In this case, the int will be promoted to a double.) #### multiply $value $value &variable Multiplies two values and outputs to a variable. The two values can be: * int and int * double and double * int and double (In this case, the int will be promoted to a double.) #### divide $value $value &variable Divides the LHS by the RHS and outputs to a variable. The two values can be: * int and int * double and double * int and double (In this case, the int will be promoted to a double.) ### Comparisons #### equal $value $value &variable If the two provided values are the same, outputs true to the variable. Otherwise, outputs false. Note: If provided values are of different types, outputs false by default. If comparing an int and double, the int will be promoted to a double. #### inequal $value $value &variable If the two provided values are not the same, outputs true to the variable. Otherwise, outputs false. Note: If provided values are of different types, outputs true by default. If comparing an int and double, the int will be promoted to a double. #### not $value &variable Outputs to the variable the opposite of the provided boolean (true becomes false, false becomes true). #### greater $value $value &variable If the LHS is greater than the RHS, outputs true to the variable. Otherwise, outputs false. The two values can be: * int and int * double and double * int and double (In this case, the int will be promoted to a double.) #### lesser $value $value &variable If the LHS is lesser than the RHS, outputs true to the variable. Otherwise, outputs false. The two values can be: * int and int * double and double * int and double (In this case, the int will be promoted to a double.) ### Type Conversions Notice: Most instructions in this section are currently unstable. Please report any bugs in this Git repository. #### stoi $value &variable Converts a string to an integer. Outputs to a variable. #### stod $value &variable Converts a string to a double. Outputs to a variable. #### tostring $value &variable Converts any type to a string. ### Functions #### fun !functionName -returnType -argType &arg1 -argType &arg2... Creates a function with the name `functionName`, and return type `returnType`. Arguments are defined with the type reference, then the direct reference symbolising the name of the argument. Any Ground instructions between this instruction and the concluding `endfun` instruction will be added to the function and not run immediately. #### return $value Returns a value from a function. If not inside a function, acts like the exit instruction. Return type must match the function return type. #### endfun Ends function definition. #### call !function $arg1 $arg2 $arg3... &variable Calls a function. After the function reference, a variable amount of value references may be provided to pass to the function. The last argument must be a direct reference which symbolises where to store the function's return value. ### Libraries #### use $libraryName Attempts to import a library written in Ground for usage within the current program. Looks in the path $GROUND_LIBS/`$libraryName`.grnd for the library. ($GROUND_LIBS is a system environment variable.) #### extern $libraryName Attempts to import a shared library written in a compiled language like C or C++ for usage within the current program. Looks in the path $GROUND_LIBS/`$libraryName`.so for the library. ($GROUND_LIBS is a system environment variable.) ### Data Structures #### struct -structName Creates a new struct which can be initialised. Until the endstruct keyword, the only valid instructions are init, set, fun, endfun, struct, and endstruct. Any value created inside the struct will be added to the struct. #### endstruct Ends the creation of a struct. #### getfield $object &fieldName &outputVar Gets a field from an initialised object. fieldName must be a valid name of a field in the object. Errors if the field does not exist. #### setfield &object &fieldName $value Sets a field to a new value in the object. The value must be of the same type as the field's old value.