From 3ae2007bab91a0db7f8e32420e20d469b688ffed Mon Sep 17 00:00:00 2001 From: Luuk Verweij Date: Tue, 24 Oct 2023 20:12:34 +0200 Subject: [PATCH 1/7] add docs for direnv and move setup docs out of main README.md --- README.md | 38 +--------------------------------- docs/direnv.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/setup.md | 41 ++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 37 deletions(-) create mode 100644 docs/direnv.md create mode 100644 docs/setup.md diff --git a/README.md b/README.md index 5ee0daa5..735d9c32 100644 --- a/README.md +++ b/README.md @@ -47,43 +47,7 @@ pdm run pytest The name of this language is just the first letter of the Latin alphabet repeated three times. When code in this language doesn't work, its meaning becomes an [abbreviation](https://en.uncyclopedia.co/wiki/AAAAAAAAA!). ### Setup -All these commands should be run from the root of this repository. - -This project requires python 3.12.1 or newer. Consider using [pyenv](https://github.com/pyenv/pyenv). - -```sh -# Download python 3.12.1 -pyenv install 3.12.1 - -# Use it in this project -pyenv local 3.12.1 -``` - -This project also requires rust, see instructions [here](https://www.rust-lang.org/tools/install) on how to install. - -After you setup rust and python, run the following commands. - -```sh -# Install dependencies -pdm install - -# Tell Aaa where the standard library lives -export AAA_STDLIB_PATH=$(pwd)/stdlib - -# Run hello world program -pdm run ./manage.py run 'fn main { "Hello world\n" . }' - -# Run tests -pdm run pytest -pdm run ./manage.py test . - -# Setup pre-commit hooks -pdm run pre-commit install -``` - -Now you can start running code in Aaa or develop the language! - -To enable syntax highlighting for VS Code, enable the [Aaa language extension](./aaa-vscode-extension/README.md) +See the [setup page](./docs/setup.md). ### Aaa and porth diff --git a/docs/direnv.md b/docs/direnv.md new file mode 100644 index 00000000..f21ed2b8 --- /dev/null +++ b/docs/direnv.md @@ -0,0 +1,56 @@ + +### About `direnv` + +Direnv is a tool to load environments and settings per folder. This is saves time and sometimes makes commands more readable (example: omit `pdm run` prefix). + +Files used by `direnv`: +* `.envrc` in the root of your project, to setup environment variables and use shell functions. +* `.direnvrc` in your home folder, to define shell functions that can be used by `.envrc` in projects. + +For more details on `direnv`, see their [official site](https://direnv.net/). + +Note that the files below can also be found in a [howto section in my dotfiles](https://github.com/lk16/dotfiles/blob/master/howto/direnv.md). + +--- + +### Setup `direnv` + +* On debian-based linux, run `sudo apt-get install direnv`, for other systems see [this page](https://direnv.net/docs/installation.html). +* Follow [instructions](https://direnv.net/docs/hook.html) for your shell +* Be sure to reload your shell config (for bash run `. ~/.bashrc`) +* Save this bash script as `.direnvrc` in your home folder. It defines the `layout_pdm` function which we use below. + +```sh +layout_pdm() { + PYPROJECT_TOML="${PYPROJECT_TOML:-pyproject.toml}" + if [ ! -f "$PYPROJECT_TOML" ]; then + log_status "No pyproject.toml found. Executing \`pmd init\` to create a \`$PYPROJECT_TOML\` first." + pdm init --non-interactive --python "$(python3 --version 2>/dev/null | cut -d' ' -f2 | cut -d. -f1-2)" + fi + + VIRTUAL_ENV=$(pdm venv list | grep "^\*" | awk -F" " '{print $3}') + + if [ -z "$VIRTUAL_ENV" ] || [ ! -d "$VIRTUAL_ENV" ]; then + log_status "No virtual environment exists. Executing \`pdm info\` to create one." + pdm info + VIRTUAL_ENV=$(pdm venv list | grep "^\*" | awk -F" " '{print $3}') + fi + + PATH_add "$VIRTUAL_ENV/bin" + export PDM_ACTIVE=1 + export VIRTUAL_ENV +} +``` + +* Next: save this bash script as `.envrc` in the root of this project. It calls the `layout_pdm` function, to set relevant environment variables. It also sets `AAA_STDLIB_PATH`, which is used by this project. The `.envrc` file is not tracked by git, [it is](../.gitignore) in `.gitignore`. +```sh +layout_pdm +export AAA_STDLIB_PATH=$(pwd)/stdlib +``` +* Run `direnv allow` to tell `direnv` that this file is safe to run. +* You should be good to go. Try running this (note: no `pdm run` prefix): +```sh +./manage.py run 'fn main { "Hello world\n" . }' +``` +* You can now omit `pdm run` prefix for all commands. +* Happy coding! diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 00000000..19e4e0e2 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,41 @@ + +### How to setup this project + +All these commands should be run from the root of this repository. + +This project requires Python 3.12.1 or later, consider using [pyenv](https://github.com/pyenv/pyenv) to select a python version. + +```sh +# Download python 3.12.1 +pyenv install 3.12.1 + +# Use it in this project +pyenv local 3.12.1 +``` + +This project also requires Rust, see instructions [here](https://www.rust-lang.org/tools/install) on how to install. + +After you setup Rust and Python, run the following commands. + +```sh +# Install dependencies +pdm install + +# Tell Aaa where the standard library lives +export AAA_STDLIB_PATH=$(pwd)/stdlib + +# Run hello world program +pdm run ./manage.py run 'fn main { "Hello world\n" . }' + +# Run tests +pdm run pytest + +# Setup pre-commit hooks +pdm run pre-commit install +``` + +Now you can start running code in Aaa or develop the language! + +Tips to make your life better: +* Enable syntax highlighting for VS Code, enable the [Aaa language extension](./aaa-vscode-extension/README.md) +* Use `direnv` as described [here](./direnv.md) so you don't have to type `pdm run` all the time. From e67841e8f474a1b5077fb8d691b42a3e6cc4b9cf Mon Sep 17 00:00:00 2001 From: Luuk Verweij Date: Tue, 24 Oct 2023 21:24:51 +0200 Subject: [PATCH 2/7] add faq to docs --- LICENSE.md | 7 +++ README.md | 59 +++++------------------ docs/best_practices.md | 0 docs/examples.md | 27 +++++++++++ docs/faq.md | 105 +++++++++++++++++++++++++++++++++++++++++ docs/setup.md | 2 + docs/syntax.md | 4 ++ docs/the_stack.md | 4 ++ 8 files changed, 160 insertions(+), 48 deletions(-) create mode 100644 LICENSE.md create mode 100644 docs/best_practices.md create mode 100644 docs/examples.md create mode 100644 docs/faq.md create mode 100644 docs/syntax.md create mode 100644 docs/the_stack.md diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..a6e1330d --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,7 @@ +Copyright 2021 Luuk Verweij + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index 735d9c32..bb2bcecc 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,17 @@ # Aaa -Stack-based language, like forth. +A stack-based programming language. -### Contents -The following tools for the Aaa language can be found is this repo -* A [tokenizer](./aaa/tokenizer/) and [parser](./aaa/parser/) for Aaa. -* A [type checker](./aaa/type_checker/) -* A [transpiler to Rust](./aaa/transpiler/) -* A [VS Code extension](./aaa-vscode-extension/README.md) for the Aaa language. -* A lot of tests, written both in python and Aaa +### Language features and goals +This language was created with as main goals: +* Simplicity +* Type-safety +* Testability +* Being selfhosted (or using as few dependencies as possible) -### Examples -```sh -# Run the obligatory hello world example -pdm run ./manage.py run 'fn main { "Hello world\n" . }' +See also the [FAQ](./docs/faq.md) section. -# Run code from a file. Implements the famous fizzbuzz interview question. -pdm run ./manage.py run examples/fizzbuzz.aaa - -# Run bare-bones HTTP server in Aaa -pdm run ./manage.py run examples/http_server.aaa - -# Send request from different shell -curl http://localhost:8080 -``` - -### Running tests - -```sh -# Run tests written in Aaa -pdm run ./manage.py test . - -# Run tests written in Python -pdm run pytest -``` - - -### Aaa features -- elementary types (`int`, `bool`, `str`) -- container types (`vec`, `map`) -- type checking -- branching, loops (`if`, `else`, `while`, `foreach`) -- multi-file support (`import`) -- [upcoming](https://github.com/lk16/aaa/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) - -### Name -The name of this language is just the first letter of the Latin alphabet repeated three times. When code in this language doesn't work, its meaning becomes an [abbreviation](https://en.uncyclopedia.co/wiki/AAAAAAAAA!). - -### Setup +### Installation and setup See the [setup page](./docs/setup.md). - -### Aaa and porth -After watching part of the [Youtube series](https://www.youtube.com/playlist?list=PLpM-Dvs8t0VbMZA7wW9aR3EtBqe2kinu4) on [porth](https://gitlab.com/tsoding/porth), I wanted to make my own stack-based language. Aaa and porth have some similarities, but obviously are not compatible with each other. No code was copied over from the porth repo. +### Running examples and tests +See the [examples page](./docs/examples.md). diff --git a/docs/best_practices.md b/docs/best_practices.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 00000000..1cc1a882 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,27 @@ +### How to run examples + +```sh +# Run the obligatory hello world example +pdm run ./manage.py run 'fn main { "Hello world\n" . }' + +# Run code from a file. Implements the famous fizzbuzz interview question. +pdm run ./manage.py run examples/fizzbuzz.aaa + +# Run bare-bones HTTP server in Aaa +pdm run ./manage.py run examples/http_server.aaa + +# Send request from different shell +curl http://localhost:8080 +``` + +More examples can be found in the [examples folder](./../examples/) + +### How to run tests + +```sh +# Run tests written in Aaa +pdm run ./manage.py test . + +# Run tests written in Python +pdm run pytest +``` diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 00000000..3378ad8f --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,105 @@ + +### Frequently Asked Questions + +##### What does the name "Aaa" mean? +Naming things is notoriously hard and naming a made up programming language is no exception. The name of this language is just the first letter of the Latin alphabet repeated three times. When code in this language doesn't work, its meaning becomes an [abbreviation](https://en.uncyclopedia.co/wiki/AAAAAAAAA!). + +##### How did you get the idea to make a language? +After watching part of the [Youtube series](https://www.youtube.com/playlist?list=PLpM-Dvs8t0VbMZA7wW9aR3EtBqe2kinu4) on [porth](https://gitlab.com/tsoding/porth), I wanted to make my own stack-based language. Aaa and porth have some similarities, but obviously are not compatible with each other. No code was copied over from the porth repo. + +##### What are the key features of Aaa? +See [language features and goals](./../README.md#language-features-and-goals). + +##### How do I get started with Aaa? +See the [setup page](./setup.md). + +##### What are the system requirements for Aaa? +Any machine that runs Python 3.11.3 and Rust should be able to run Aaa. If you run into issues, be sure to [open a ticket](https://github.com/lk16/aaa/issues/new). + +##### Is Aaa open source or proprietary? +This project is open source and is distributed under the MIT license. This effectively means: do whatever you want with the code, but you can't sue me. + +##### How do I report bugs or request features? +Both bug reports and feature requests can be sent to developers by opening a ticket. +Please first check [existing tickets](https://github.com/lk16/aaa/issues), before opening a new one. + +##### What is the latest version of Aaa? +At time of writing there are no releases. Checking out the `main` branch and running `git pull` will get you the latest version. + +##### Can I use Aaa on different operating systems? +Yes, see `What are the system requirements` question above. + +##### What kind of applications can I build with Aaa? +Anything that: +* does not depend on other libraries (such as GUI's) +* is serious production / non-"pet project" software + +That being said, various tools have been written using Aaa: +* a [HTTP server](../examples/http_server.aaa) +* a [HTTP client](../examples/http_client.aaa) +* a [shell](../examples/shell.aaa) +* a [sudoku solver](../examples/sudoku_solver.aaa) +* a [game of life](../examples/game_of_life.aaa) implementation ([What is this?](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life)) + +##### Are there any code examples or tutorials available for Aaa? +Yes, see the [examples documentation](./examples.md) + +##### How do I create a new project or file in Aaa? +At this stage of the language: +* Create a new branch from `main` +* Create a new folder in `examples` +* Create a file `main.aaa` having a `main` function +* Start typing code + +##### What is the package manager for Aaa? +There is none. There is not even a well-implemented import-system at time of writing. + +##### How do I install and manage packages or dependencies? +Good one. + +##### How can I handle errors or exceptions in Aaa? +We don't have exceptions in this language. Functions can return an enum, with one or more error variants. + +##### What is the syntax for ... in Aaa? +See the [syntax documentation](./syntax.md) + +##### How do I work with classes and objects in Aaa? +It mostly revolves around [the stack](./the_stack.md). + +##### What are the available data structures and collections in Aaa? +At time of writing: +* `vec`, sometimes called "dynamic array" or "list" +* `map`, sometimes called "hash table", "hash map" or "dictionary" +* `set` + +##### How can I work with files and file I/O? +Use the [builtin](./../stdlib/builtins.aaa) system calls. + +##### Is there a standard coding style or best practices guide for Aaa? +Yes, see the [best practices](./best_practices.md) article. + +##### How do I optimize and debug code in Aaa? + + +##### Are there any known limitations or caveats in Aaa? +Well, this is an enormous "pet project", so nothing is considered stable or production-ready. That being said, a lot of tests are in place to prevent major issues. The main limitations have more to do with features that are not implemented, rather than existing bugs. + +Main things that are not implemented: +* interfaces (as in golang, [issue](https://github.com/lk16/aaa/issues/16)) +* dealing with concurrency +* having a standard library +* having a well-implemented import system +* having a package manager + +##### Can I contribute to the development of Aaa? +* Clone this repo and write some code in Aaa. +* Find bugs, suggest features on the [issues](https://github.com/lk16/aaa/issues) page. + +##### How do I secure my Aaa applications? +Please don't use Aaa applications with any sensitive data. Do NOT use Aaa applications in a production setting. + +##### What is the support and community around Aaa? +The [issues section](https://github.com/lk16/aaa/issues) on the GithHub repository. + +##### Was ChatGPT or other AI involved in the development? +ChatGPT was not used for writing code, but sometimes used to assist in refactoring. Generally speaking all code in this repo was written by humans. ChatGPT did help coming up with some of the questions on this page. diff --git a/docs/setup.md b/docs/setup.md index 19e4e0e2..be0add8c 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,6 +1,8 @@ ### How to setup this project +Start by cloning this repository. + All these commands should be run from the root of this repository. This project requires Python 3.12.1 or later, consider using [pyenv](https://github.com/pyenv/pyenv) to select a python version. diff --git a/docs/syntax.md b/docs/syntax.md new file mode 100644 index 00000000..b8d77809 --- /dev/null +++ b/docs/syntax.md @@ -0,0 +1,4 @@ + +### Syntax + +TODO diff --git a/docs/the_stack.md b/docs/the_stack.md new file mode 100644 index 00000000..44e27865 --- /dev/null +++ b/docs/the_stack.md @@ -0,0 +1,4 @@ + +### About "the stack" + +TODO From b370ecefdd888a61a7f38cbfca56c423e3c03b69 Mon Sep 17 00:00:00 2001 From: Luuk Verweij Date: Tue, 24 Oct 2023 22:10:41 +0200 Subject: [PATCH 3/7] extend stack docs --- docs/the_stack.md | 104 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/docs/the_stack.md b/docs/the_stack.md index 44e27865..8540b105 100644 --- a/docs/the_stack.md +++ b/docs/the_stack.md @@ -1,4 +1,106 @@ -### About "the stack" +### Intro to "the stack" + +Aaa is a stack-based language. ALL functions operate on the stack: +* Arguments are read from the top of the stack +* Returned values are put on top of the stack + +Here are some common expressions used when talking about stacks: +* "to push a value": adding a value on top of the stack +* "to pop a value": reading a value from the top of the stack, removing it +* "to drop a value": removing a value from the stack and discarding it + +### Syntax basics + +This section explains basic syntax to understand the rest of this article. For more details please check the [dedicated article](./syntax.md) on syntax. + +Consider this code: +```rs +fn main { + nop +} +``` + +It tells us: +* There is a function `main` +* It takes no arguments (there is no `args ...` section) +* It returns nothing (there is no `return ...` section) +* It does nothing (`nop` means do nothing) + +Note that we won't use `nop` below. We only use it here because the syntax requires it. + +### Pushing values and checking values + +TODO + +### Type checking rules TODO + +### Function argument order + +Function arguments get values by consuming items from the stack in the same order they were pushed on the stack. In reality that means we pop the right amount of items from the stack and reverse them. This is a design choice, which helps with readability. + +The below code example illustrates this: the function `show_argument_order` has arguments `a` and `b`. It is called after `1` and `2` are pushed on the stack. That means `a` gets assigned a value of `1` and `b` gets assigned a value of `2`. + +Note that just before we call `show_argument_order` in `main`, the stack has the value `2` on top of the stack, since it was pushed last. + +Also note that the function `show_argument_order` does not return any values, as it has no `return ...` section in its definition. Since function arguments are always consumed from the stack, it means it will just consume two (integer) values from the stack when called. + +```rs +fn main { + // stack: empty + 1 // stack: 1 + 2 // stack: 1 2 + show_argument_order // stack: empty +} + +fn show_argument_order args a as int, b as int { + // stack: empty + a 1 = assert // asserts `a` has value 1, stack: empty + b 2 = assert // asserts `b` has value 2, stack: empty + // stack: empty +} +``` + +### Function return value order + +Return values are pushed on the stack in the order specified in the `return ...` section of the function declaration. + +```rs +fn main { + // stack: empty + show_return_value_order // stack: 1 2 + 2 = assert // asserts top value is 2, stack: 1 + 1 = assert // asserts top value is 1, stack: empty +} + +fn show_return_value_order return int, int { + // stack: empty + 1 // stack: 1 + 2 // stack: 1 2 +} +``` + +Dealing with (many) return values can be confusing, so we can use a `use`-block to increase readability. + +Note the similarities between a function call and the `use`-block: +* Both consume arguments from the stack +* Both create variables, with values in order these values were pushed on the stack. + +```rs +fn main { + // stack: empty + show_return_value_order // stack: 1 2 + use a, b { + a 1 = assert // asserts `a` has value 1, stack: empty + b 2 = assert // asserts `b` has value 2, stack: empty + } +} + +fn show_return_value_order return int, int { + // stack: empty + 1 // stack: 1 + 2 // stack: 1 2 +} +``` From 10884741f3cb2a6a6484c32422d92b2e1cbd99f1 Mon Sep 17 00:00:00 2001 From: Luuk Verweij Date: Tue, 24 Oct 2023 22:44:53 +0200 Subject: [PATCH 4/7] add more details to the stack documentation --- README.md | 14 +++++++----- docs/faq.md | 2 +- docs/implementation.md | 6 ++++++ docs/{the_stack.md => stack.md} | 38 +++++++++++++++++++++++++++++---- docs/syntax.md | 10 ++++++++- docs/typing.md | 4 ++++ 6 files changed, 63 insertions(+), 11 deletions(-) create mode 100644 docs/implementation.md rename docs/{the_stack.md => stack.md} (67%) create mode 100644 docs/typing.md diff --git a/README.md b/README.md index bb2bcecc..5256b98f 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,16 @@ This language was created with as main goals: * Simplicity * Type-safety * Testability -* Being selfhosted (or using as few dependencies as possible) +* Becoming [selfhosted](https://en.wikipedia.org/wiki/Self-hosting_(compilers)) See also the [FAQ](./docs/faq.md) section. -### Installation and setup -See the [setup page](./docs/setup.md). +### How to get started +* Follow the [setup and installation](./docs/setup.md) guide. +* See [how to run tests and examples](./docs/examples.md). -### Running examples and tests -See the [examples page](./docs/examples.md). +### Documentation +* Find out about [the stack](./docs/stack.md). +* Learn about [how types work](./docs/typing.md). +* Read about [the Aaa implementation](./docs/implementation.md). +* Read the [FAQ](./docs/faq.md). diff --git a/docs/faq.md b/docs/faq.md index 3378ad8f..5545afb3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -64,7 +64,7 @@ We don't have exceptions in this language. Functions can return an enum, with on See the [syntax documentation](./syntax.md) ##### How do I work with classes and objects in Aaa? -It mostly revolves around [the stack](./the_stack.md). +It mostly revolves around [the stack](./stack.md). ##### What are the available data structures and collections in Aaa? At time of writing: diff --git a/docs/implementation.md b/docs/implementation.md new file mode 100644 index 00000000..93ff1eaf --- /dev/null +++ b/docs/implementation.md @@ -0,0 +1,6 @@ + +# Implementation of Aaa + +TODO talk about tokenizer, parser, cross-referencer, type checker, transpiler, compiler + +TODO link to this article diff --git a/docs/the_stack.md b/docs/stack.md similarity index 67% rename from docs/the_stack.md rename to docs/stack.md index 8540b105..46b258f8 100644 --- a/docs/the_stack.md +++ b/docs/stack.md @@ -2,8 +2,8 @@ ### Intro to "the stack" Aaa is a stack-based language. ALL functions operate on the stack: -* Arguments are read from the top of the stack -* Returned values are put on top of the stack +* Arguments are consumed ("popped") from the top of the stack +* Returned values are put ("pushed") on top of the stack Here are some common expressions used when talking about stacks: * "to push a value": adding a value on top of the stack @@ -31,11 +31,41 @@ Note that we won't use `nop` below. We only use it here because the syntax requi ### Pushing values and checking values -TODO +Every time we write an integer literal (such as `3`) in the code, it's means: push an integer with this value on the stack. Likewise with booleans (example: `false`), strings (example: `"hello"`). Other types don't have literals. + +Here is a program that asserts that 1 + 2 = 3, including some type annotations. + +Note that normally we would not write every literal and function call on its own line, but this way we can put comments in between. + +```rs +fn main { + // stack: empty + 1 // stack: 1 + 2 // stack: 1 2 + + // stack: 3 + 3 // stack: 3 3 + = // stack: true + assert // stack: empty +} +``` + +You can see that: +* Every integer literal pushes an integer +* the `+` function takes 2 integer arguments and returns 1 integer +* the `=` function takes 2 integer arguments and returns 1 boolean +* the `assert` function takes 1 boolean and returns nothing + +These 3 functions (and all other built-in functions) can be found in the [builtins](../stdlib/builtins.aaa) file. ### Type checking rules -TODO +This language comes with a type-checker. Code that breaks the typing rules will not compile (or run for that matter). + +The type checker enforces the following rules: +* When calling a function, the correct argument types must be on the top of on the stack +* When defining a function, the correct types must be returned on top of the stack + +How this works in detail with `if-else` and other constructs is described in detail in the [typing](./typing.md) article. ### Function argument order diff --git a/docs/syntax.md b/docs/syntax.md index b8d77809..0143530a 100644 --- a/docs/syntax.md +++ b/docs/syntax.md @@ -1,4 +1,12 @@ -### Syntax +### Syntax of the Aaa language + +TODO + +### Syntax of top-level items + +TODO + +### Syntax of functions TODO diff --git a/docs/typing.md b/docs/typing.md new file mode 100644 index 00000000..8c094c39 --- /dev/null +++ b/docs/typing.md @@ -0,0 +1,4 @@ + +### Typing in Aaa + +TODO From 831f8d1998b4da914a12872ed3a5c75cea037393 Mon Sep 17 00:00:00 2001 From: Luuk Verweij Date: Wed, 25 Oct 2023 23:20:36 +0200 Subject: [PATCH 5/7] wip --- docs/syntax.md | 27 ++++++++++++++++++++++++++- docs/typing.md | 16 ++++++++++++++++ 2 files changed, 42 insertions(+), 1 deletion(-) diff --git a/docs/syntax.md b/docs/syntax.md index 0143530a..d0c7bca9 100644 --- a/docs/syntax.md +++ b/docs/syntax.md @@ -7,6 +7,31 @@ TODO TODO -### Syntax of functions +### Syntax describing a function TODO +* name, args, return, never +* struct associated function +* type parameters + +### Syntax inside of functions + +TODO +| Name | Example(s) | +|---------------------------------|----------------------------------------------------------| +| assignment | `var <- { ... }` | +| boolean literal | either `false` or `true` | +| branch | either `if ... { ... }` or `if ... { ... } else { ... }` | +| call from function pointer | `call` | +| foreach loop | `foreach { ... }` | +| call a function | `my_function` | +| function pointer type literal | `fn[...][...]` | +| get pointer to function | `my_function fn` | +| integer literal | `69` or `-420` | +| match block | `match { case ... { ... } default { ... } }` | +| return | `return` | +| string literal | `"hello"` `"\r\n"` | +| get struct field | `"struct_field_name" ?` | +| set struct field | `"struct_field_name" { ... }` | +| use block | `use { ... }` | +| while loop | `while { ... }` | diff --git a/docs/typing.md b/docs/typing.md index 8c094c39..768c7d66 100644 --- a/docs/typing.md +++ b/docs/typing.md @@ -1,4 +1,20 @@ ### Typing in Aaa +Aaa is a typed language. Every stack value and every variable has a type. +The type checker makes sure that values of correct arguments are being passed to functions. + +Types in Aaa come in two flavours: +* `struct`'s: data structures +* `enum`'s: enumerables + +### Structs + +TODO + +### Enums + TODO + +--- + From 16f7d8d23f5b0ea14e52f2869a4cdb1abaf0dc94 Mon Sep 17 00:00:00 2001 From: Luuk Verweij Date: Fri, 27 Oct 2023 10:07:22 +0200 Subject: [PATCH 6/7] fix typo --- docs/syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax.md b/docs/syntax.md index d0c7bca9..55b88524 100644 --- a/docs/syntax.md +++ b/docs/syntax.md @@ -32,6 +32,6 @@ TODO | return | `return` | | string literal | `"hello"` `"\r\n"` | | get struct field | `"struct_field_name" ?` | -| set struct field | `"struct_field_name" { ... }` | +| set struct field | `"struct_field_name" { ... } !` | | use block | `use { ... }` | | while loop | `while { ... }` | From 1def1aac5b4f4f6d1ea65f9cbec973202e47d38c Mon Sep 17 00:00:00 2001 From: Luuk Verweij Date: Mon, 18 Dec 2023 22:38:05 +0100 Subject: [PATCH 7/7] wip --- docs/typing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/typing.md b/docs/typing.md index 768c7d66..04b3a6c3 100644 --- a/docs/typing.md +++ b/docs/typing.md @@ -17,4 +17,3 @@ TODO TODO --- -