Syntax docs

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