7.5 KiB
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.)