diff --git a/README.md b/README.md index 5b8cf48..c7c01fc 100644 --- a/README.md +++ b/README.md @@ -1,290 +1,222 @@

- poo-banner-transparent + PooLang banner

PooLang

- Rust + Rust stable - - PRs Welcome + + Release v0.1.11 - License MIT + MIT License

-

- Features • - Get Started • - Installation • - Usage • - Syntax • - Example • - Dev -

-

-A Tiny Interpreted language written in Rust, featuring variable declarations, arithmetic operations, conditional statements, and control flow. The name Poo originates from Guinea Pig translated from Burmese. + English | + မြန်မာ

-## Features +PooLang is being designed as a simple, compiled language for web backends and +infrastructure. Its direction combines Go-like deployment, approachable syntax, +and Rust-inspired explicitness without exposing ownership or lifetime syntax. +The name **Poo (ပူး)** comes from the Burmese word for guinea pig. + +> [!IMPORTANT] +> The current release, **v0.1.11**, is a legacy tree-walking interpreter. +> The compiled backend platform described in the roadmap is planned for v0.2 +> and is not implemented yet. + +## Project Status -- **Arithmetic Expressions**: Supports addition, subtraction, multiplication, and division with correct operator precedence. -- **Variable Declarations**: Uses `poo` keyword for variable declarations. -- **Mutable Variables**: Like in Rust, all variables are immutable by default. Uses `mut` for mutable variables. -- **Conditional Statements**: Includes `if`, `else`, and `elif` for branching. -- **Control Flow**: Supports `while` and `for in` loops and `return` statements. -- **Custom Operators**: - - Assignment operator: `<<` - - Arrow operator: `>>` -- **Lexer, Parser, and Interpreter**: A full pipeline from tokenizing source code to executing it. +| Track | Availability | Purpose | +| --- | --- | --- | +| v0.1.11 | Available | Legacy Rust interpreter, executable examples, and checked library APIs | +| v0.2 | Planned | Clean-break LLVM compiler, native runtime, package tooling, async HTTP/JSON, analyzer, and editor support | +| v0.3 | Planned | Opinionated web application platform with data, auth, cache, queues, and framework tooling | +| v0.4 | Planned | Protobuf/gRPC, microservices, resilience, discovery, and OpenTelemetry | -## Get Started +There is no compatibility promise between the legacy syntax below and v0.2. +See [TODO.md](https://github.com/shayyz-code/poolang/blob/main/TODO.md) for the decision record, milestones, and implementation +gates. -For instructions on installing PooLang on your platform, visit our project site via [https://shayyz-code.github.io/poolang](https://shayyz-code.github.io/poolang/). We provide automated installers for all platforms. +## Current v0.1.11 Features -### Quick Install +- Integer, float, Boolean, character, string, vector, and map values. +- Immutable inferred or typed declarations and mutable bindings. +- Arithmetic, comparison, `and`, `or`, `not`, and `otherwise` expressions. +- `if`/`elif`/`else`, `while`, range/vector `for`, `step`, and `return`. +- Typed functions, structs, instance methods, and legacy struct inheritance. +- Built-in `std`, `math`, and `time` modules. +- Checked source/file APIs with `Io`, `Parse`, and `Runtime` errors. +- A Rust lexer, parser, type-inference pass, and AST-walking interpreter. -Recommended: +Traits are tokenized but are not a complete supported feature. PooLang does not +currently provide native compilation, HTTP, JSON, databases, packages, gRPC, or +an editor analyzer. + +## Installation + +Current v0.1.11 packages and installers are published for macOS, Linux, and +Windows. + +### Homebrew ```bash brew install shayyz-code/tap/poo ``` -or +### npm ```bash -npm install @shayyz-code/poo@latest +npm install --global @shayyz-code/poo@latest ``` -**Linux / macOS** +### Linux or macOS installer ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shayyz-code/poolang/releases/latest/download/poo-installer.sh | sh ``` -**Windows** +### Windows PowerShell installer ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/shayyz-code/poolang/releases/latest/download/poo-installer.ps1 | iex" ``` -### Verify Installation +### Build from source + +Install a stable Rust toolchain, then run: ```bash -poo --help +git clone https://github.com/shayyz-code/poolang.git +cd poolang +cargo install --path . ``` -## Build from Source - -### Prerequisites - -- Rust and Cargo installed. If you don't have them installed, follow the [Rust installation guide](https://www.rust-lang.org/tools/install). - -### Steps - -1. Clone the repository: - - ```bash - git clone https://github.com/shayyz-code/poolang.git - cd poolang - ``` - -2. Install with cargo: - - ```bash - cargo install --path . - ``` +## Running Programs -## Usage - -You can use the interpreter to run files containing your custom language code. - -### Running the Interpreter - -To run the interpreter on a source file: +The v0.1 CLI accepts a Poo source file path: ```bash -cargo run +poo path/to/program.poo ``` -Example: +From a repository checkout: ```bash -cargo run app.poo +cargo run -- examples/app.poo ``` -The CLI uses typed checked execution (`run_file_checked`) and prints structured error kinds (`Io`, `Parse`, `Runtime`) with a non-zero exit code on failure. - -## Release - -Releases are automated with GitHub Actions + [cargo-dist](https://opensource.axo.dev/cargo-dist/) and publish: - -- Multi-platform binaries (Linux, macOS, Windows) -- Optimized installers (Shell, PowerShell) -- Homebrew formula updates to `shayyz-code/tap` (`shayyz-code/homebrew-tap`) -- Scoop manifest updates to `shayyz-code/scoop-bucket` - -Release flow: - -1. Update version in `Cargo.toml`. -2. Create and push a version tag (example: `v0.1.5`). -3. The `Release` workflow builds all artifacts, creates a GitHub Release, and handles downstream publishing. +Append `--speed` after the source path to print interpreter timing: -CI checks: - -- Pull requests and pushes to `main` run build + tests on Linux, macOS, and Windows. -- Unix runners also validate installer script syntax (`sh -n install.sh`). - -## Syntax Overview - -The language features basic syntax for arithmetic, variable declarations, and control flow: - -### **Variable Declarations** - -```poo -poo x << 10; -poo mut y << 5 + 2 * 3; -``` - -### **Arithmetic Operations** - -```poo -poo result << x + y * 2 - 10 / 2; +```bash +poo path/to/program.poo --speed ``` -### **Conditional Statements** +Successful top-level returns are printed as `Result: `. File, parse, and +runtime failures are written to stderr with a non-zero exit status. The legacy +CLI does not currently implement `--help` or `--version`. -```poo -if x > y { - return x; -} else { - return y; -} -``` +## Legacy v0.1.11 Syntax -### **Loops** +This example is executable with the current interpreter: ```poo -use std::pout; +use std::poutln; -poo mut count << 0; +poo message str = "ready"; +mut total <: 0; -while count < 10 { - count << count + 1; +for i in 0..5 { + total = total + i; } -for i in 0..3 { - pout("Hello, World ", i); +poof double(value int) >> int { + return value * 2; } -``` -### **Functions** - -```poo -use std::pout; - -poof getName () >> string { - poo name << "Shayy"; - return name; +if (not false and total > 5) or message == "never" { + poutln(double(total)); } -pout(getName()); +return total; ``` -## Example Code +Expected output: -Here is a sample program in my PooLang: +```text +20 +Result: Int(10) +``` -```poo -use std::pout; +Legacy declarations use `<:` for inferred types or `name type = value` for +explicit types. Mutable declarations begin with `mut`; reassignment uses +standard `=`. Functions use `poof`, typed parameters such as `value int`, +and `>>` for return types. -poo a << 5.0 * 1.0 - 1.0 * 3.0; -poo b << 2 / 2; -poo mut d << true; -d << false; +## Examples -poof getHelloWorld () >> string { - return "Hello, World!"; -} +`examples/app.poo` exercises collections, control flow, functions, structs, +methods, modules, and inheritance: -for i in 0..2 { - pout("Hello, Poo!", i); -} - -pout(getHelloWorld()); +```bash +cargo run -- examples/app.poo ``` -Expected Output: +`examples/donut.poo` renders a continuously animated terminal donut. Run it +in a terminal and stop it with Ctrl+C: -```poo -Hello, Poo!0 -Hello, Poo!1 -Hello, World! +```bash +cargo run --release -- examples/donut.poo ``` -## Development - -### TDD Specs - -Current executable specs live in `tests/language_specs.rs`: +Both examples target the legacy v0.1.11 interpreter. -- `spec_lexer_skips_inline_comment_block` -- `spec_parser_respects_multiplication_precedence` -- `spec_interpreter_executes_program_to_return_value` -- `spec_checked_api_returns_typed_error_on_parse_failure` -- `spec_checked_api_returns_typed_error_on_runtime_failure` -- `spec_checked_file_api_returns_io_error_for_missing_file` -- `spec_checked_file_api_executes_valid_file` -- loop coverage (`for` range, `for` range with `step`, `for` vector, `while`) -- control-flow coverage (`if` / `elif` / `else`) -- struct coverage (instance methods, inheritance method lookup) +## Releases and CI -Run them with: +SemVer tags drive the cargo-dist `Release` workflow. The current configuration +produces checksummed archives for Apple Silicon and Intel macOS, ARM64 and +x86-64 Linux, and x86-64 Windows, plus shell, PowerShell, npm, Homebrew, and MSI +installers. Stable releases publish npm packages and Homebrew formula updates. -```bash -cargo test -``` +Pull requests currently run: -### Refactor TODOs +- The issue-link policy check. +- Rustfmt, Cargo check, strict Clippy, and the complete Cargo test suite on Ubuntu. +- The Oranda/mdBook site build and internal-link check. +- A cargo-dist release-plan validation. -- [x] Expose core modules as a reusable library API (`src/lib.rs`). -- [x] Keep CLI thin by delegating execution to library entrypoints. -- [x] Upgrade crate to Rust Edition 2024. -- [x] Introduce checked execution APIs with typed error kinds (`Io`, `Parse`, `Runtime`). -- [ ] Replace panic-driven parser/interpreter internals with native `Result` propagation. -- [ ] Split large parser and interpreter files into focused submodules. -- [x] Add integration specs for structs, methods, inheritance, and loops. +Pushes to `main` rebuild and deploy the project site. Platform release builds +run for version tags, not for every pull request. -### Project Structure +## Development -``` -. -├── src -│ ├── lib.rs # Reusable library API -│ ├── lexer.rs # Lexical analysis (tokenizer) -│ ├── parser.rs # Parsing logic -│ ├── interpreter.rs # Interpreter for executing code -│ ├── ast.rs # Abstract Syntax Tree (AST) definitions -│ ├── errors.rs # Typed error definitions -│ └── main.rs # Entry point -├── examples # Sample code -│ ├── donut.poo -│ └── app.poo -├── tests -│ └── language_specs.rs # TDD integration specs -└── Cargo.toml # Project configuration +```bash +cargo build +cargo fmt --all -- --check +cargo check --all-targets +cargo clippy --all-targets --all-features -- -D warnings +cargo test +mdbook build docs +mdbook test docs ``` -## Contributing +Core Rust code lives in `src/`, executable language specifications in +`tests/language_specs.rs`, sample programs in `examples/`, and documentation +sources in `docs/src/`. Generated `docs/book/` and `public/` output is not +tracked. -Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +Every change starts with a GitHub issue and a branch from `main`. Pull requests +must remain small, contain exactly one closing issue reference, use Conventional +Commits, and are squash-merged only. See [CONTRIBUTING.md](CONTRIBUTING.md). ## License -PooLang is licensed under the MIT License. See [LICENSE](LICENSE) for details. +PooLang is licensed under the [MIT License](LICENSE). -

Hand-Crafted by Shayy

+

Hand-crafted by Shayy

diff --git a/README.mm.md b/README.mm.md new file mode 100644 index 0000000..d06abd1 --- /dev/null +++ b/README.mm.md @@ -0,0 +1,232 @@ +

+ PooLang banner +

+ +

PooLang

+ +

+ + Rust stable + + + Release v0.1.11 + + + MIT License + +

+ +

+ English | + မြန်မာ +

+ +PooLang ကို web backend နှင့် infrastructure များအတွက် ရိုးရှင်းသော compiled +language တစ်ခုအဖြစ် တည်ဆောက်ရန် ရည်ရွယ်ထားသည်။ ၎င်း၏ ဦးတည်ချက်သည် Go ကဲ့သို့ +ဖြန့်ချိရလွယ်ကူမှု၊ နားလည်ရလွယ်သော syntax နှင့် ownership သို့မဟုတ် lifetime +syntax များကို အသုံးပြုသူထံ မဖော်ပြဘဲ Rust မှ အတုယူထားသော ရှင်းလင်းတိကျမှုတို့ကို +ပေါင်းစပ်ထားသည်။ **Poo (ပူး)** ဟူသောအမည်သည် မြန်မာဘာသာရှိ guinea pig ၏ +အမည်မှ ဆင်းသက်လာသည်။ + +> [!IMPORTANT] +> လက်ရှိ release ဖြစ်သော **v0.1.11** သည် ယခင် tree-walking interpreter +> ဖြစ်သည်။ Roadmap တွင် ဖော်ပြထားသော compiled backend platform ကို v0.2 +> အတွက် စီစဉ်ထားပြီး လက်ရှိတွင် မတည်ဆောက်ရသေးပါ။ + +## ပရောဂျက်အခြေအနေ + +| လမ်းကြောင်း | ရရှိနိုင်မှု | ရည်ရွယ်ချက် | +| --- | --- | --- | +| v0.1.11 | အသုံးပြုနိုင် | ယခင် Rust interpreter၊ အလုပ်လုပ်သော examples နှင့် checked library APIs | +| v0.2 | စီစဉ်ထား | Compatibility မယူသော LLVM compiler၊ native runtime၊ package tooling၊ async HTTP/JSON၊ analyzer နှင့် editor support | +| v0.3 | စီစဉ်ထား | Data၊ auth၊ cache၊ queue နှင့် framework tooling ပါဝင်သော opinionated web application platform | +| v0.4 | စီစဉ်ထား | Protobuf/gRPC၊ microservices၊ resilience၊ discovery နှင့် OpenTelemetry | + +အောက်တွင် ဖော်ပြထားသော legacy syntax နှင့် v0.2 အကြား compatibility +အာမခံချက် မရှိပါ။ ဆုံးဖြတ်ချက်များ၊ milestone များနှင့် implementation gate +များကို [TODO.md](https://github.com/shayyz-code/poolang/blob/main/TODO.md) တွင် ကြည့်နိုင်သည်။ + +## လက်ရှိ v0.1.11 စွမ်းဆောင်ချက်များ + +- Integer၊ float၊ Boolean၊ character၊ string၊ vector နှင့် map value များ။ +- Type inference သို့မဟုတ် type အတိအကျပါသော immutable declaration များနှင့် mutable binding များ။ +- Arithmetic၊ comparison၊ `and`၊ `or`၊ `not` နှင့် `otherwise` expression များ။ +- `if`/`elif`/`else`၊ `while`၊ range/vector `for`၊ `step` နှင့် `return`။ +- Typed function များ၊ struct များ၊ instance method များနှင့် legacy struct inheritance။ +- Built-in `std`၊ `math` နှင့် `time` module များ။ +- `Io`၊ `Parse` နှင့် `Runtime` error များပါသော checked source/file API များ။ +- Rust ဖြင့် ရေးသားထားသော lexer၊ parser၊ type-inference pass နှင့် AST-walking interpreter။ + +`trait` ကို token အဖြစ် သိရှိသော်လည်း ပြည့်စုံသော supported feature +မဟုတ်သေးပါ။ လက်ရှိ PooLang တွင် native compilation၊ HTTP၊ JSON၊ database၊ +package၊ gRPC သို့မဟုတ် editor analyzer မပါဝင်သေးပါ။ + +## ထည့်သွင်းခြင်း + +လက်ရှိ v0.1.11 package နှင့် installer များကို macOS၊ Linux နှင့် Windows +အတွက် ထုတ်ဝေထားသည်။ + +### Homebrew + +```bash +brew install shayyz-code/tap/poo +``` + +### npm + +```bash +npm install --global @shayyz-code/poo@latest +``` + +### Linux သို့မဟုတ် macOS installer + +```bash +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shayyz-code/poolang/releases/latest/download/poo-installer.sh | sh +``` + +### Windows PowerShell installer + +```powershell +powershell -ExecutionPolicy Bypass -c "irm https://github.com/shayyz-code/poolang/releases/latest/download/poo-installer.ps1 | iex" +``` + +### Source မှ build လုပ်ခြင်း + +Stable Rust toolchain ကို ထည့်သွင်းပြီးနောက် အောက်ပါ command များကို +အသုံးပြုပါ။ + +```bash +git clone https://github.com/shayyz-code/poolang.git +cd poolang +cargo install --path . +``` + +## Program များကို Run ခြင်း + +v0.1 CLI သည် Poo source file path တစ်ခုကို လက်ခံသည်။ + +```bash +poo path/to/program.poo +``` + +Repository checkout မှ run လိုပါက: + +```bash +cargo run -- examples/app.poo +``` + +Interpreter ကြာချိန်ကို ပြရန် source path နောက်တွင် `--speed` ထည့်ပါ။ + +```bash +poo path/to/program.poo --speed +``` + +Top-level return အောင်မြင်လျှင် `Result: ` ပုံစံဖြင့် ပြသသည်။ File၊ +parse နှင့် runtime failure များကို stderr သို့ ရေးပြီး non-zero exit status +ဖြင့် ထွက်သည်။ Legacy CLI တွင် `--help` နှင့် `--version` မပါဝင်သေးပါ။ + +## Legacy v0.1.11 Syntax + +ဤ example ကို လက်ရှိ interpreter ဖြင့် တိုက်ရိုက် run နိုင်သည်။ + +```poo +use std::poutln; + +poo message str = "ready"; +mut total <: 0; + +for i in 0..5 { + total = total + i; +} + +poof double(value int) >> int { + return value * 2; +} + +if (not false and total > 5) or message == "never" { + poutln(double(total)); +} + +return total; +``` + +မျှော်မှန်းထားသော output: + +```text +20 +Result: Int(10) +``` + +Legacy declaration တွင် inferred type အတွက် `<:` ကို အသုံးပြုပြီး explicit +type အတွက် `name type = value` ကို အသုံးပြုသည်။ Mutable declaration သည် +`mut` ဖြင့် စတင်ပြီး reassignment အတွက် ပုံမှန် `=` ကို အသုံးပြုသည်။ +Function များတွင် `poof`၊ `value int` ကဲ့သို့ typed parameter နှင့် return +type အတွက် `>>` ကို အသုံးပြုသည်။ + +## Examples + +`examples/app.poo` တွင် collection၊ control flow၊ function၊ struct၊ method၊ +module နှင့် inheritance များကို အသုံးပြုထားသည်။ + +```bash +cargo run -- examples/app.poo +``` + +`examples/donut.poo` သည် terminal တွင် ဆက်တိုက်လှုပ်ရှားသော donut ကို +ရေးဆွဲပြသသည်။ Terminal ထဲတွင် run ပြီး Ctrl+C ဖြင့် +ရပ်ပါ။ + +```bash +cargo run --release -- examples/donut.poo +``` + +Example နှစ်ခုလုံးသည် legacy v0.1.11 interpreter အတွက် ဖြစ်သည်။ + +## Release နှင့် CI + +SemVer tag များသည် cargo-dist `Release` workflow ကို စတင်ပေးသည်။ လက်ရှိ +configuration သည် Apple Silicon နှင့် Intel macOS၊ ARM64 နှင့် x86-64 Linux၊ +x86-64 Windows တို့အတွက် checksum ပါသော archive များအပြင် shell၊ +PowerShell၊ npm၊ Homebrew နှင့် MSI installer များကို ထုတ်ပေးသည်။ Stable +release များသည် npm package နှင့် Homebrew formula update များကို publish +လုပ်သည်။ + +Pull request များတွင် လက်ရှိ အောက်ပါ check များကို run သည်။ + +- Issue-link policy check။ +- Ubuntu ပေါ်ရှိ Rustfmt၊ Cargo check၊ strict Clippy နှင့် Cargo test suite အပြည့်အစုံ။ +- Oranda/mdBook site build နှင့် internal-link check။ +- cargo-dist release-plan validation။ + +`main` သို့ push လုပ်သောအခါ project site ကို ပြန်လည် build လုပ်ပြီး deploy +လုပ်သည်။ Platform release build များသည် pull request တိုင်းအတွက် မဟုတ်ဘဲ +version tag များအတွက်သာ run သည်။ + +## Development + +```bash +cargo build +cargo fmt --all -- --check +cargo check --all-targets +cargo clippy --all-targets --all-features -- -D warnings +cargo test +mdbook build docs +mdbook test docs +``` + +အဓိက Rust code များသည် `src/` တွင်၊ executable language specification +များသည် `tests/language_specs.rs` တွင်၊ sample program များသည် +`examples/` တွင်၊ documentation source များသည် `docs/src/` တွင် +ရှိသည်။ Generate လုပ်ထားသော `docs/book/` နှင့် `public/` output များကို +Git တွင် မထည့်ထားပါ။ + +Change တိုင်းအတွက် GitHub issue ကို အရင်ဖွင့်ပြီး `main` မှ branch ခွဲရသည်။ +Pull request များကို သေးငယ်စွာ ထားရမည်၊ closing issue reference တစ်ခုတည်း +ပါရမည်၊ Conventional Commits ကို အသုံးပြုရမည်၊ squash merge ဖြင့်သာ +ပေါင်းရမည်။ အသေးစိတ်ကို [CONTRIBUTING.md](CONTRIBUTING.md) တွင် ကြည့်ပါ။ + +## လိုင်စင် + +PooLang ကို [MIT License](LICENSE) ဖြင့် ထုတ်ဝေထားသည်။ + +

Shayy မှ ဖန်တီးထားသည်

diff --git a/TODO.md b/TODO.md index b7792ce..0c7010e 100644 --- a/TODO.md +++ b/TODO.md @@ -13,6 +13,8 @@ Snapshot: 2026-07-29. - `cargo test` passes and is enforced for pull requests, including all 48 integration specifications and the library doctest. - `cargo clippy --all-targets --all-features -- -D warnings` passes and is enforced for pull requests. - `mdbook build docs` reproducibly generates ignored documentation output from `docs/src/`. +- English and Burmese READMEs distinguish the available v0.1.11 interpreter from the planned compiled backend platform. +- Both shipped examples execute against the v0.1.11 interpreter; the donut runs until interrupted. - The crate exposes checked file/source execution APIs and typed I/O, parse, and runtime error categories. - Lexer, parser, interpreter, type-inference, examples, mdBook documentation, and cargo-dist release assets exist. @@ -30,8 +32,6 @@ Snapshot: 2026-07-29. - Documentation uses `poo mut`, `string`, `&&`, `||`, `#` comments, `>=`, and `<=`; the lexer currently recognizes top-level `mut`, `str`, `and`, `or`, unusual `// ... //` comments, and no inclusive comparisons. - Function examples omit required parameter types or use return/type spelling that differs from the parser. - `trait` is tokenized but not supported as a complete tested language feature. -- Examples contain multiple syntax generations and unverified standard-library methods. -- README development/release claims do not fully match current checks and workflows. ### Missing platform capabilities @@ -75,7 +75,7 @@ Snapshot: 2026-07-29. - [x] Resolve the remaining strict Clippy findings in the lexer, parser, type inference, and symbol table. - [x] Require `cargo clippy --all-targets --all-features -- -D warnings` in pull-request CI. - [x] Separate generated mdBook output from sources and define one reproducible documentation build command. -- [ ] Reconcile README commands, branch names, CI claims, supported features, and examples with executable behavior. +- [x] Reconcile README commands, branch names, CI claims, supported features, and examples with executable behavior. - [ ] Add focused lexer/parser error tests for malformed strings, comments, UTF-8 input, and unexpected EOF. - [ ] Audit release workflow actions, permissions, secrets, installers, and generated cargo-dist configuration. - [ ] Add dependency, license, and supply-chain checks appropriate to Rust and future native runtime dependencies.