ground/cground
3
2
Fork 1
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

Syntax docs

Browse Source
This commit is contained in:
Maxwell
2026-01-15 14:58:50 +11:00
parent d2bffb1405
commit 18579830ab
2 changed files with 364 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/extlibs.md Normal file
View File

@@ -0,0 +1,95 @@
# Ground Libraries
This repo folder details the process for creating libraries with Ground, as well as some core libraries that are preinstalled with Ground.
## Building Libraries
Ground comes with the `groundvm.h` and `groundext.h` header files for interfacing with Ground. If you're building something that wraps Ground, use `groundvm.h`. If you're building something that Ground itself uses (a library), use `groundext.h` (it includes `groundvm.h` but also has some extlib-specific things).
You can build your library in C or C++, or whichever language you can convince to interop with C code.
Note: C++ Ground extlibs and CGround extlibs are not compatible. Update your code for CGround.
### Making a Function for CGround
Create a function with the following signature:
```c
GroundValue myFn(GroundScope* scope, List args) {}
```
* `GroundScope* scope`: For now does nothing. Will do something when structs are added.
* `List args`: A list of args.
The `List` struct and associated structures look like this:
```c
typedef enum GroundValueType {
INT, DOUBLE, STRING, CHAR, BOOL, LIST, FUNCTION, CUSTOM, NONE
} GroundValueType;
typedef struct List {
size_t size;
struct GroundValue* values;
} List;
typedef struct GroundValue {
GroundValueType type;
union {
int64_t intVal;
double doubleVal;
char* stringVal;
char charVal;
bool boolVal;
List listVal;
struct GroundFunction* fnVal;
void* customVal;
} data;
} GroundValue;
```
Your function needs to return a `GroundValue`. This can easily be created with the `groundCreateValue()` function, used like this:
```c
// TYPE is one of the enum values from the GroundValueType enum.
// CONTENT is the associated data type (char* for string, int64_t for int, etc, etc)
groundCreateValue(TYPE, content);
// Real use:
groundCreateValue(STRING, "dingus");
groundCreateValue(INT, 32);
```
Once you've created your functions, you can create a `ground_init()` function to let Ground know about your functions. Use the `groundAddNativeFunction()` function to add your functions to Ground.
If your function fails, print some debug stuff to the console and return `groundCreateValue(NONE)`. Proper error handling will be added soon.
```c
GroundValue say_hi(GroundScope* scope, List args) {
char* greeting = "Hello, ";
if (list.size < 1) {
printf("Expecting an argument!");
return groundCreateValue(NONE);
}
if (list.values[0].type != STRING) {
printf("Expecting a string");
return groundCreateValue(NONE);
}
// Insert stupid memory stuff here
return groundCreateValue(STRING, greeting);
}
// ground_init takes a GroundScope* so it can add your functions to Ground
void ground_init(GroundScope* scope) {
// groundAddNativeFunction(scope, "namespace_FnName", name_of_function, RETURNTYPE,
// amountOfArgs, ARGTYPE, "argName", ARGTYPE, "argName", ...)
groundAddNativeFunction(scope, "utility_SayHi", say_hi, STRING, 1, STRING, "name");
}
```
### Notes
When naming your functions, give them a prefix namespace like in C. Use `camelCase` for the namespace and `CamelCase` for the function name.
Document your functions somewhere! We want to be able to use them!

364
docs/syntax.md Normal file
View File

@@ -0,0 +1,364 @@
# 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.)