peon/README.md

# The peon programming language

Peon is a simple, functional, async-first programming language with a focus on correctness and speed.

[Go to the Manual](docs/manual.md)


## Project structure

- `src/` -> Contains the entirety of peon's toolchain
    - `src/memory/` -> Contains peon's memory allocator and GC (TODO)
    - `src/frontend/` -> Contains the tokenizer, parser and compiler
        - `src/frontend/meta/` -> Contains shared error definitions, AST node and token 
            declarations as well as the bytecode used by the compiler
    - `src/backend/` -> Contains the peon VM and type system
    - `src/util/` -> Contains utilities such as the bytecode debugger and serializer as well
        as procedures to handle multi-byte sequences
    - `src/config.nim` -> Contains compile-time configuration variables
    - `src/main.nim` -> Ties up the whole toolchain together by tokenizing,
        parsing, compiling, debugging, (de-)serializing and executing peon code
- `docs/` -> Contains documentation for various components of peon (bytecode, syntax, etc.)
- `tests/` -> Contains tests (both in peon and Nim) for the toolchain


## Credits

- Araq, for creating the amazing language that is [Nim](https://nim-lang.org) (as well as all of its contributors!)
- Guido Van Rossum, aka the chad who created [Python](https://python.org) and its awesome community and resources
- The Nim community and contributors, for making Nim what it is today
- Bob Nystrom, for his amazing [book](https://craftinginterpreters.com) that inspired me
    and taught me how to actually make a programming language (kinda, I'm still very dumb)
- [Njsmith](https://vorpus.org/), for his awesome articles on structured concurrency
- All the amazing people in the [r/ProgrammingLanguages](https://reddit.com/r/ProgrammingLanguages) subreddit and its [Discord](https://discord.gg/tuFCPmB7Un) server
- [Art](https://git.nocturn9x.space/art) <3
- Everyone to listened (and still listens to) me ramble about compilers, programming languages and the likes (and for giving me ideas and testing peon!)
- ... More? (I'd thank the contributors but it's just me :P)
- Me! I guess


## Project State

**Disclaimer**: The project is still in its very early days: lots of stuff is not implemented, a work in progress or 
otherwise outright broken. Feel free to report bugs!

Also, yes: peon is yet another programming language inspired by Bob's book, but it is also **very** 
different from Lox, which is an object-oriented, dynamically typed and very high level programming language, whereas
peon is a statically-typed, functional language which aims to allow low-level interfacing with C and Nim code while 
being a breeze to use. 

Also, peon will feature [structured concurrency](https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/) with coroutines (think Futures/Fibers but without 
callback hell). Since, unlike Lox, peon isn't a toy language, there's obviously plans to implement creature comforts 
like an import system, exception handling, a package manager, etc.


### TODO List

In no particular order, here's a list of stuff that's done/to do (might be incomplete/out of date):

Toolchain:

  - Tokenizer (with dynamic symbol table) [X]
  - Parser (with support for custom operators, even builtins) [X]
  - Compiler [ ]  -> Being written
  - VM [ ] -> Being written
  - Bytecode (de-)serializer [X]
  - Static code debugger [X]
  - Runtime debugger/inspection tool [ ]

Type system:

  - Custom types [ ]
  - Intrinsics [X]
  - Generics [ ] -> WIP
  - Functions [X]

Misc:

  - Pragmas [ ] -> WIP (Some pragmas implemented)
  - Attribute resolution [ ]
  - method-like call syntax without actual methods (dispatched at compile-time) [ ]
  - ... More?


## Features

Aside from the obvious basics like exceptions, a true import system with namespaces and a standard library (duh), here's a 
random list of high-level features I plan peon to have and that I think are kinda neat:
- References not being nullable by default (must use `#pragma[nullable]`)
- Easy C/Nim interop via FFI
- C/C++ backend
- Nim backend (maybe)
- Structured concurrency
- Capability-based programming (i.e. functions are passed objects to act on the real world)
- Parametric Polymorphism (with untagged typed unions and maybe interfaces)
- Simple OOP (with multiple dispatch!)
- RTTI, with methods that dispatch at runtime based on the true type of a value (maybe)
- Limited compile-time evaluation (embed the Peon VM in the C/C++/Nim backend and use that to execute peon code at compile time)


## The name

The name for peon comes from my and [Productive2's](https://git.nocturn9x.space/prod2) genius and is a result of shortening
the name of the fastest animal on earth: the **Pe**regrine Falc**on**. I guess I wanted this to mean peon will be blazing fast

# Peon needs you.

No, but really. I need help. This project is huge and (IMHO) awesome, but there's a lot of non-trivial work to do and doing
it with other people is just plain more fun and rewarding. If you want to get involved, definitely try [contacting](https://nocturn9x.space/contact) me
or open an issue/PR!