diff --git a/libs/README.md b/docs/extlibs.md similarity index 100% rename from libs/README.md rename to docs/extlibs.md diff --git a/docs/syntax.md b/docs/syntax.md new file mode 100644 index 0000000..f236be6 --- /dev/null +++ b/docs/syntax.md @@ -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.)