Updated documentation

This commit is contained in:
Eduard Urbach 2024-08-26 12:46:47 +02:00
parent b35b17bb32
commit 63d72c8d22
Signed by: akyoto
GPG Key ID: C874F672B1AF20C0
4 changed files with 138 additions and 135 deletions

39
docs/readme.md Normal file
View File

@ -0,0 +1,39 @@
# q
A programming language that compiles down to machine code.
## Features
- Fast compilation
- High performance
- Small executables
## Installation
```shell
git clone https://git.akyoto.dev/cli/q
cd q
go build
```
## Usage
```shell
./q run examples/hello
```
Builds an executable from `examples/hello` and runs it.
## Links
- [Chat](https://matrix.to/#/#community:akyoto.dev)
- [Donate](https://buy.stripe.com/4gw7vf5Jxflf83m7st)
- [Todo](/docs/todo.md)
## License
Please see the [license documentation](https://akyoto.dev/license).
## Copyright
© 2023 Eduard Urbach

80
docs/todo.md Normal file
View File

@ -0,0 +1,80 @@
## Todo
### Compiler
- [x] Tokenizer
- [x] Scanner
- [x] Functions
- [x] Variables
- [x] Error messages
- [x] Expression parser
- [x] Function calls
- [x] Parallel compilation
- [x] Syscalls
- [x] Variable lifetimes
- [x] Branches
- [x] Loops
- [x] Hexadecimal, octal and binary literals
- [x] Escape sequences
- [x] Multiple return values
- [ ] Type system
- [ ] Type operator `?`
- [ ] Data structures
- [ ] Slices
- [ ] Floating-point arithmetic
- [ ] Error handling
- [ ] Threading library
- [ ] Self-hosted compiler
### Keywords
- [x] `assert`
- [x] `else`
- [ ] `for`
- [x] `if`
- [x] `import`
- [x] `loop`
- [x] `return`
- [x] `switch`
### Optimizations
- [x] Exclude unused functions
- [x] Constant folding
- [ ] Constant propagation
- [ ] Function call inlining
- [ ] Loop unrolls
- [ ] Assembler optimization backend
### Linter
- [x] Unused variables
- [x] Unused parameters
- [x] Unused imports
- [ ] Unnecessary newlines
- [ ] Ineffective assignments
### Operators
- [x] `=`, `:=`
- [x] `+`, `-`, `*`, `/`, `%`
- [x] `+=`, `-=`, `*=`, `/=`, `%=`
- [x] `&`, `|`, `^`
- [x] `&=`, `|=`, `^=`
- [x] `<<`, `>>`
- [x] `<<=`, `>>=`
- [x] `==`, `!=`, `<`, `<=`, `>`, `>=`
- [x] `&&`, `||`
- [ ] `!`, `-`
### Architecture
- [ ] arm64
- [ ] riscv
- [x] x64
### Platform
- [x] Linux
- [x] Mac
- [ ] Windows

View File

@ -1,135 +1,16 @@
# q
A programming language for use in systems programming, game development and web servers.
## Features
* Fast compilation
* Small executables
* High performance
## Installation
```shell
git clone https://git.akyoto.dev/cli/q
cd q
go build
```
## Usage
Build an executable from `examples/hello` and run it:
```shell
./q run examples/hello
```
## Tests
```shell
go test ./... -v -cover
```
## Benchmarks
```shell
go test ./tests -run='^$' -bench=. -benchmem
```
## Todo
### Compiler
- [x] Tokenizer
- [x] Scanner
- [x] Functions
- [x] Variables
- [x] Error messages
- [x] Expression parser
- [x] Function calls
- [x] Parallel compilation
- [x] Syscalls
- [x] Variable lifetimes
- [x] Branches
- [x] Loops
- [x] Hexadecimal, octal and binary literals
- [x] Escape sequences
- [x] Multiple return values
- [ ] Type system
- [ ] Type operator `?`
- [ ] Data structures
- [ ] Slices
- [ ] Floating-point arithmetic
- [ ] Error handling
- [ ] Threading library
- [ ] Self-hosted compiler
### Keywords
- [x] `assert`
- [x] `else`
- [ ] `for`
- [x] `if`
- [x] `import`
- [x] `loop`
- [x] `return`
- [x] `switch`
### Optimizations
- [x] Exclude unused functions
- [x] Constant folding
- [ ] Constant propagation
- [ ] Function call inlining
- [ ] Loop unrolls
- [ ] Assembler optimization backend
### Linter
- [x] Unused variables
- [x] Unused parameters
- [x] Unused imports
- [ ] Unnecessary newlines
- [ ] Ineffective assignments
### Operators
- [x] `=`, `:=`
- [x] `+`, `-`, `*`, `/`, `%`
- [x] `+=`, `-=`, `*=`, `/=`, `%=`
- [x] `&`, `|`, `^`
- [x] `&=`, `|=`, `^=`
- [x] `<<`, `>>`
- [x] `<<=`, `>>=`
- [x] `==`, `!=`, `<`, `<=`, `>`, `>=`
- [x] `&&`, `||`
- [ ] `!`, `-`
### Architecture
- [ ] arm64
- [ ] riscv
- [x] x64
### Platform
- [x] Linux
- [x] Mac
- [ ] Windows
## Documentation ## Documentation
### [main.go](main.go) ### [main.go](/main.go)
Entry point. It simply calls `cli.Main` which we can use for testing. Entry point. It simply calls `cli.Main` which we can use for testing.
### [src/cli/Main.go](src/cli/Main.go) ### [src/cli/Main.go](/src/cli/Main.go)
The command line interface expects a command like `build` as the first argument. The command line interface expects a command like `build` as the first argument.
Commands are implemented as functions in the [src/cli](src/cli) directory. Commands are implemented as functions in the [src/cli](src/cli) directory.
Each command has its own set of parameters. Each command has its own set of parameters.
### [src/cli/Build.go](src/cli/Build.go) ### [src/cli/Build.go](/src/cli/Build.go)
The build command creates a new `Build` instance with the given directory and calls the `Run` method. The build command creates a new `Build` instance with the given directory and calls the `Run` method.
@ -156,7 +37,7 @@ Adding the `-v` or `--verbose` flag shows verbose compiler information:
q build examples/hello -v q build examples/hello -v
``` ```
### [src/build/Build.go](src/build/Build.go) ### [src/build/Build.go](/src/build/Build.go)
The `Build` type defines all the information needed to start building an executable file. The `Build` type defines all the information needed to start building an executable file.
The name of the executable will be equal to the name of the build directory. The name of the executable will be equal to the name of the build directory.
@ -176,24 +57,16 @@ Each function will then be translated to generic assembler instructions.
All the functions that are required to run the program will be added to the final assembler. All the functions that are required to run the program will be added to the final assembler.
The final assembler resolves label addresses, optimizes the performance and generates the specific x86-64 machine code from the generic instruction set. The final assembler resolves label addresses, optimizes the performance and generates the specific x86-64 machine code from the generic instruction set.
### [src/core/Function.go](src/core/Function.go) ### [src/core/Function.go](/src/core/Function.go)
This is the "heart" of the compiler. This is the "heart" of the compiler.
Each function runs `f.Compile` which organizes the source code into an abstract syntax tree that is then compiled via `f.CompileAST`. Each function runs `f.Compile` which organizes the source code into an abstract syntax tree that is then compiled via `f.CompileAST`.
You can think of AST nodes as the individual statements in your source code. You can think of AST nodes as the individual statements in your source code.
### [src/ast/Parse.go](src/ast/Parse.go) ### [src/ast/Parse.go](/src/ast/Parse.go)
This is what generates the AST from tokens. This is what generates the AST from tokens.
### [src/expression/Parse.go](src/expression/Parse.go) ### [src/expression/Parse.go](/src/expression/Parse.go)
This is what generates expressions from tokens. This is what generates expressions from tokens.
## License
Please see the [license documentation](https://akyoto.dev/license).
## Copyright
© 2023 Eduard Urbach

11
tests/readme.md Normal file
View File

@ -0,0 +1,11 @@
## Tests
```shell
go test ./... -v -cover
```
## Benchmarks
```shell
go test ./tests -run='^$' -bench=. -benchmem
```