solstice/docs
2
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Maxwell
2026-05-09 21:06:07 +10:00
commit 6e6be47891
24 changed files with 6416 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
src/SUMMARY.md Normal file
View File

@@ -0,0 +1,14 @@
# Summary
[Introduction](introduction.md)
# Specification
- [Reserved Words](reserved_words.md)
- [Comments](comments.md)
- [Expressions](expressions.md)
- [Types](types.md)
- [Variables](variables.md)
- [Scoping](scoping.md)
- [Operators](operators.md)
- [Function Definition](function_definition.md)
- [Struct Definition](struct_definition.md)

41
src/comments.md Normal file
View File

@@ -0,0 +1,41 @@
# Comments
Comments in Solstice can be done in 3 ways:
## `//` (Single-Line Comment)
Use `//` to tell Solstice to ignore text until the end of the line.
This kind of comment should be used inside code to explain how parts of code work.
## `/* */` (Multiline Comment)
Use `/*` and `*/` to tell Solstice to ignore text in between the two markers.
This kind of comment should be used for explainations of how functions and structs work, placed above the definition.
## `#` (Shebang Comment)
Use `#` to tell Solstice to ignore text until the end of the line.
This kind of comment should be used in a shebang (writing `#!/usr/bin/env solstice` at the top of your entry point source file), not in the middle.
## Example
```solstice
#!/usr/bin/env solstice
/*
This function does something.
Input:
funnyNumber: A funny number
Returns: Another funny number
*/
def doSomething(int funnyNumber) int {
// Tell the user the number is funny
puts "The number" funnyNumber "is very funny"
// Now give them another funny number
return 532
}
```

147
src/expressions.md Normal file
View File

@@ -0,0 +1,147 @@
# Expressions
An expression in Solstice is a combination of operators and values (whether literal or stored in a variable).;
## Expression Types
"Precedence" is a number which dictates the order of execution. The higher the precedence, the sooner an expression will be evaluated.
### Binary Mathematical
* `+`: Adds two numbers on either side, or concatenates two strings
* Accepts:
* Two integers either side
* Two doubles either side
* Two strings either side
* An integer and a double on either side (order not significant)
* Returns:
* The sum of both values as an integer if both values are integers
* The sum of both values as a double if one value is a double and the other is an int, or both values are doubles
* The concatenated string when both values are strings
* Precedence: 5
* `-`: Subtracts two numbers on either side
* Accepts:
* Two integers either side
* Two doubles either side
* An integer and a double on either side (order not significant)
* Returns:
* The difference of both values as an integer if both values are integers
* The difference of both values as a double if one value is a double and the other is an int, or both values are doubles
* Precedence: 5
* `*`: Multiplies two numbers on either side
* Accepts:
* Two integers either side
* Two doubles either side
* An integer and a double on either side (order not significant)
* Returns:
* The product of both values as an integer if both values are integers
* The product of both values as a double if one value is a double and the other is an int, or both values are doubles
* Precedence: 6
* `/`: Divides two numbers on either side
* Accepts:
* Two integers either side
* Two doubles either side
* An integer and a double on either side (order not significant)
* Returns:
* The quotient of both values as an integer if both values are integers
* The quotient of both values as a double if one value is a double and the other is an int, or both values are doubles
* Precedence: 6
### Binary Comparative
* `==`: Checks two values to determine if they are equal
* Accepts:
* Any two values either side which are of the same type
* An integer and a double on either side (order not significant)
* Returns:
* `true` if both provided values are exactly the same. 
* `false` otherwise.
* Precedence: 2
* `!=`: Checks two values to determine if they are not equal
* Accepts:
* Any two values either side which are of the same type
* An integer and a double on either side (order not significant)
* Returns:
* `true` if both provided values are not exactly the same. 
* `false` otherwise.
* Precedence: 2
* `>`: Checks two numbers to determine which is greater
* Accepts:
* Any two numbers (int or double) either side
* Returns:
* `true` if the number provided on the left is greater than the number provided on the right.
* `false` otherwise.
* Precedence: 2
* `<`: Checks two numbers to determine which is lesser
* Accepts:
* Any two numbers (int or double) either side
* Returns:
* `true` if the number provided on the left is lesser than the number provided on the right.
* `false` otherwise.
* Precedence: 2
* `>=`: Checks two numbers to determine which is greater, or whether both are equal
* Accepts:
* Any two numbers (int or double) either side
* Returns:
* `true` if the number provided on the left is greater than the number provided on the right, or if both numbers are equal.
* `false` otherwise.
* Precedence: 2
* `<=`: Checks two numbers to determine which is lesser, or whether both are equal
* Accepts:
* Any two numbers (int or double) either side
* Returns:
* `true` if the number provided on the left is lesser than the number provided on the right, or if both numbers are equal.
* `false` otherwise.
* Precedence: 2
### Binary Misc
* `as`: Converts between types.
* Accepts:
* Any object on the left, and a type which has an applicable conversion defined by the object on the right
* Returns:
* The object turned into the type on the right, in the way defined by the as-method
* `.`: Accesses object fields
* Accepts:
* An object on the left, and an identifier on the right which corresponds to a field or method in the object
* Returns:
* The object field or method the identifier corresponds to
### Brackets
* `(...)`: Evaluates an expression inside the brackets before outside expressions.
* Accepts:
* Any expression inside the brackets (in place of `...`)
* Returns:
* The result of the expression in the brackets
* Precedence: 7
### Function Call
* `(...)`: Calls the specified function.
* Accepts:
* An identifier for the function before the brackets, then comma-seperated expressions corresponding to the function type signature (see [Types -> Combined Types -> fun](types.md#fun)) inside the brackets (in place of `...`)
* Returns:
* The function's return type as specified by the function type signature (see [Types -> Combined Types -> fun](types.md#fun))
### Unary Misc
* `new`: Creates a new object from a template.
* Accepts:
* A template after the `new` keyword.
* A core type identifier
* Returns:
* An object based on the provided template, if provided with a template.
* The empty version of the core type, if provided with a core type, which is:
* `int`: `0`
* `double`: `0.0`
* `string`: `""`
* `char`: `'\0'`
* `bool`: `false`
* `sizeof`: Gets the size of something.
* Accepts:
* A string
* An object with an `int size` field
* Returns:
* The string length if provided a string
* The `int size` field of the object if provided an object

61
src/function_definition.md Normal file
View File

@@ -0,0 +1,61 @@
# Function Definition
## Named Functions
Define a named function with the following syntax:
```solstice
def functionName(args) type {
...
}
```
where:
* `functionName` is the name of the function.
* If `functionName` is already defined as a function or other value, it will only be overwritten if the type does not change.
* `args` is multiple comma-seperated pairs of:
* a type identifier for the parameter, and
* an identifier (representing the parameter name)
* `type` is the type of value which the function will return
* `...` is the code inside the function (the function body).
* The function body will have access to previously set variables through a closure. The closure is a copy of all variables in their current state at function definition time.
* The function body will also have access to the parameters defined in `args`.
Example:
```solstice
def add(int a, int b) int {
return a + b
}
```
## Anonymous/Lambda functions
Define a lambda function with the following syntax:
```solstice
lambda(args) type {
...
}
```
where:
* `args` is multiple comma-seperated pairs of:
* a type identifier for the parameter, and
* an identifier (representing the parameter name)
* `type` is the type of value which the function will return
* `...` is the code inside the function (the function body).
* The function body will have access to previously set variables through a closure. The closure is a copy of all variables in their current state at function definition time.
* The function body will also have access to the parameters defined in `args`.
Example:
```solstice
add = lambda(int a, int b) int {
return a + b
}
```
Lambda functions are most useful when passed as arguments to other functions.

5
src/introduction.md Normal file
View File

@@ -0,0 +1,5 @@
# Introduction
Welcome to the Solstice docs! For now, the documentation is in the format of a specification, which instructs you on how Solstice should behave. In future, a tutorial (similar to the Rust book) will be written which shows you each part of the language, instead of declaring it like the spec.
Docs generated by mdBook.

123
src/operators.md Normal file
View File

@@ -0,0 +1,123 @@
# Operators
Operators are bits of code intended to control how the program runs.
## `puts`
Stands for "put something". Prints debug info to the console, followed by a new line.
### Formatting
* int: The literal number, as formatted by C `printf("%" PRId64)`.
* double: The literal number, as formatted by C `printf("%f")`.
* string: All characters in the string, as formatted by C `printf("%s")`.
* char: The ASCII character corresponding to the number held, as formatted by C `printf("%c")`.
* bool: If `true` or `1`, print `true`. Otherwise, print `false`.
* fun: Print `<function>`.
* template: Print `<struct fields: { ... }>`, where:
* `...` is a comma-seperated sequence of `key: value`, where:
* `key` is the identifier of the field.
* `value` is the properly formatted value in the field.
* object: Print `<object fields: { ... }>`, where:
* `...` is a comma-seperated sequence of `key: value`, where:
* `key` is the identifier of the field.
* `value` is the properly formatted value in the field.
## `if`
Runs a block of code only if the provided condition is true.
Syntax:
```solstice
if condition {
...
}
```
where:
* `condition` is an expression which evaluates to a boolean.
* If this expression evaluates to `true`, the code block will be run.
* Brackets surrounding the condition are optional.
* `...` is the code to run if the condition is true.
Example:
```solstice
if 2 + 2 == 4 {
puts "phew!"
}
```
## `while`
Runs a block of code until the provided condition is false.
Syntax:
```solstice
while condition {
...
}
```
where:
* `condition` is an expression which evaluates to a boolean.
* If this expression evaluates to `false`, the code block will not be run anymore.
* Brackets surrounding the condition are optional.
* `...` is the code to run while the condition is true.
Example:
```solstice
while true {
puts "To infinity and beyond!"
}
```
## `return`
Returns a value from a function.
Syntax:
```solstice
return value
```
where `value` is a value with the same type as the function's return type.
## `ground`
**Inline Ground is potentially dangerous. Only use if you know what you're doing!**
Inserts inline Ground code into the generated program.
Syntax:
```solstice
ground {
...
}
```
where `...` is the Ground code to insert.
See [here](https://chookspace.com/ground/ground) for details about Ground.
Note: **Solstice cannot keep track of state inside `ground` blocks!** Ground will allow you to do things without the overhead of the Solstice type checker.
To extract a value from a Ground block, do something like this:
```solstice
x = 0
ground {
set &x 10
}
puts x
```
so the type checker can know what `x` is.

27
src/reserved_words.md Normal file
View File

@@ -0,0 +1,27 @@
# Reserved Words
This is a list of all reserved words in Solstice, seperated by new lines. These words may not be used as identifiers.
After `//`, notes may be provided which detail exceptions to the reserved word, however, the word should still be treated as reserved regardless.
```solstice
puts
if
while
def
lambda
return
use
struct
enum
constructor
destructor
duplicator
private
protected
ground // Only when targeting GroundVM
new
as
sizeof
pragma
```

43
src/scoping.md Normal file
View File

@@ -0,0 +1,43 @@
# Scoping and Lifetimes
## Subscoping
A "subscope" is a scope contained inside a function, created inside curly braces (`{}`).
Subscopes can view and modify variables avaliable in their parent scope.
Subscopes may also create their own variables, however these will be destroyed when the subscope ends.
## Function Scoping
A function scope is a scope created inside a function.
Function scopes are created from a function's attached closure, which is a snapshot of all variables at the time of function definition.
The function's attached closure cannot be modified.
Function scopes also contain all arguments provided to a function.
When the function finishes running (with a `return`), all variables are destroyed.
## Destructors
Objects (see [here](struct_definition.md)) can contain a destructor which specifies custom behaviour for destroying itself. This is useful for:
* Freeing heap-allocated memory
* Closing a connection
* Closing a file
The destructor will always be in the field `destructor` with type signature `fun() int`. It should be automatically called when the variable goes out of scope.
## Duplicators
Objects (see [here](struct_definition.md)) can contain a duplicator which specifies custom behaviour for copying itself. This is useful for:
* Duplicating heap-allocated memory
The duplicator will always be in the field `duplicator` with type signature `fun((self) old) (self)`. It should be automatically called when the variable is:
* Copied into a new variable
* Put inside a closure
* Passed to a function

191
src/struct_definition.md Normal file
View File

@@ -0,0 +1,191 @@
# Struct Definition
Define a struct with the `struct` keyword.
Syntax:
```
struct StructName {
...
}
```
where:
* `StructName` is the name of your struct
* `...` is the body of your struct
## Struct Body
Inside the struct body, you can:
* Define fields
* Define methods
* Define special methods (`constructor`, `destructor`, `duplicator`, `as`)
## Defining fields
A field in a struct is defined in the same way as a variable.
```
struct MyStruct {
x = 5
}
```
This creates a field named `x` with a default value of `5`.
## Defining methods
A method in a struct is defined in the same way as a named function.
```
struct MyStruct {
def myMethod() int {
return 0
}
}
```
Methods have access to the struct's members through the `self` object, which is implicitly passed.
```
struct MyStruct {
x = 10
def myMethod() int {
return self.x * 2
}
}
```
## Private and protected fields
A private field is a field which only methods inside the object can read and write.
A protected field is a field which only methods inside the object can write to, however anywhere else in the program the field can be read.
All other fields are public, meaning anywhere in the program can read or write these fields.
Methods and special methods are by default protected, however can be made private.
```
struct MyStruct {
private x = 10
protected y = "Hi"
private doSomething() int {
return 14
}
}
```
## Defining special methods
In Solstice, objects have some special methods which provide ease of use while handling these objects.
### Constructor
A constructor is used to initialize an object with user-provided fields.
Define a constructor like this:
```
struct MyStruct {
constructor(args) {
...
}
}
```
where:
* `args` is multiple comma-seperated pairs of:
* a type identifier for the parameter, and
* an identifier (representing the parameter name)
* `...` is the constructor body
* The constructor body has access to the `self` object, which is how it can modify the newly created object.
* The `self` object is automatically returned at the end of the constructor, however can be returned manually if required.
Use a constructor like this:
```
MyStruct(args)
```
where:
* args is many comma-seperated expressions corresponding to the signature of the defined constructor
### Destructor
A destructor is used to destroy an object once it goes out of scope.
Define a destructor like this:
```
struct MyStruct {
destructor {
...
}
}
```
where:
* `...` is the destructor body
* The destructor body has access to the `self` object, which is how it can access and modify the object which is being destroyed.
* There is no need to return a value from the destructor.
Note how the destructor does not take any arguments.
### Duplicator
A duplicator is used to copy an object when it is assigned to a new name, or passed to a function.
Define a duplicator like this:
```
struct MyStruct {
duplicator {
...
}
}
```
where:
* `...` is the duplicator body
* The destructor body has access to the `self` and `old` objects.
* The `self` object is the new duplication and will be automatically returned
* The `old` object is the old object and will not be copied out
Note how the duplicator does not take any arguments.
### As methods
As methods allow easy conversion between different types.
Define an as method like this:
```
struct MyStruct {
as type {
...
}
}
```
where:
* `type` is the type which the object will be converted to
* `...` is the as method body
* The `self` object is avaliable inside the as method
* You will need to initialize and return a new value with the specified type
Use an as method like this:
```
myobj as type
```
where:
* `myobj` is an object with an as method which provides a conversion to `type`
* `type` is the target type

108
src/types.md Normal file
View File

@@ -0,0 +1,108 @@
# Types
Solstice is statically typed, meaning all values must have a known type before any code can be executed.
## Core Types
These core types are automatically avaliable in Solstice. The words to identify them are reserved and cannot be reassigned.
### `int`
8-byte signed integer, equivalent to C `int64_t` or Ground `-int`.
Examples: `32`, `121`, `-5`
### `double`
8-byte double prescision floating point number, equivalent to C `double` or Ground `-double`.
Examples: `3.14`, `-2.7`
### `string`
C-style null-terminated array of characters. Equivalent to C `char*` or Ground `-string`.
### `char`
1-byte signed integer, usually used to store a character, however can also be used to store bytes. Equivalent to C `char` or Ground `-char`.
### `bool`
1-byte unsigned integer, either 1 or 0. Represented by the reserved words `true` and `false`. Equivalent to C `char` (no stdbool.h) or `bool` (with stdbool.h) or Ground `-bool`.
## Combined Types
These types utilise core types to create new combinations. They take type arguments.
### `fun`
Represents a function. Equivalent to Ground `-function`, or a C function pointer.
**Syntax**:
```solstice
fun(...) type
```
where:
* `type` is a type identifier, which will be the return type
* `...` is multiple type identifiers, seperated by commas, which are the argument types
**Example**:
```solstice
fun(int, string) bool
```
This represents a function which takes an `int` and `string` as arguments, and returns a `bool`.
### `template`
Represents an uninitialized object. Equivalent to Ground `-struct`.
**Syntax**:
```solstice
template(...)
```
where `...` is multiple pairs of:
* a type identifier for the field, and
* an identifier (representing the field name)
seperated by commas.
**Example**:
```solstice
template(int x, string y)
```
This represents a template which, when initialized, has fields x (with integer) and y (with string).
### `object`
Represents an initialized object.
**Syntax**:
```solstice
object(...)
```
where `...` is multiple pairs of:
* a type identifier for the field, and
* an identifier (representing the field name)
seperated by commas.
**Example**:
```solstice
object(int x, string y)
```
This represents a object which has fields x (with integer) and y (with string).

14
src/variables.md Normal file
View File

@@ -0,0 +1,14 @@
# Variables
Variables are defined and modified with the syntax:
```solstice
name = value
```
where:
* `name` is an identifier, and
* `value` is a literal, expression, or identifier previously assigned to a variable.
All variables must have a known type and value at definition time. When updating a variable, the type may not change.