forked from ground/cground
365 lines
7.5 KiB
Markdown
365 lines
7.5 KiB
Markdown
# 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.)
|