PooLang

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.

Features

• 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.

Get Started

For instructions on installing PooLang on your platform, visit our project site via https://shayyz-code.github.io/poolang. We provide automated installers for all platforms.

Quick Install

Recommended:

brew install shayyz-code/tap/poo

or

npm install @shayyz-code/poo@latest

Linux / macOS

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shayyz-code/poolang/releases/latest/download/poo-installer.sh | sh

Windows

powershell -ExecutionPolicy Bypass -c "irm https://github.com/shayyz-code/poolang/releases/latest/download/poo-installer.ps1 | iex"

Verify Installation

poo --help

Build from Source

Prerequisites

• Rust and Cargo installed. If you don't have them installed, follow the Rust installation guide.

Steps

1. Clone the repository:

   git clone https://github.com/shayyz-code/poolang.git
   cd poolang

2. Install with cargo:

   cargo install --path .

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:

cargo run <path_to_your_source_file>

Example:

cargo run 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 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.

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 x << 10;
poo mut y << 5 + 2 * 3;

Arithmetic Operations

poo result << x + y * 2 - 10 / 2;

Conditional Statements

if x > y {
    return x;
} else {
    return y;
}

Loops

use std::pout;

poo mut count << 0;

while count < 10 {
    count << count + 1;
}

for i in 0..3 {
    pout("Hello, World ", i);
}

Functions

use std::pout;

poof getName () >> string {
    poo name << "Shayy";
    return name;
}

pout(getName());

Example Code

Here is a sample program in my PooLang:

use std::pout;

poo a << 5.0 * 1.0 - 1.0 * 3.0;
poo b << 2 / 2;
poo mut d << true;
d << false;

poof getHelloWorld () >> string {
    return "Hello, World!";
}

for i in 0..2 {
    pout("Hello, Poo!", i);
}

pout(getHelloWorld());

Expected Output:

Hello, Poo!0
Hello, Poo!1
Hello, World!

Development

TDD Specs

Current executable specs live in tests/language_specs.rs:

• 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)

Run them with:

cargo test

Refactor TODOs

• Expose core modules as a reusable library API (src/lib.rs).
• Keep CLI thin by delegating execution to library entrypoints.
• Upgrade crate to Rust Edition 2024.
• 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.
• Add integration specs for structs, methods, inheritance, and loops.

Project Structure

.
├── 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

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

PooLang is licensed under the MIT License. See LICENSE for details.

Hand-Crafted by Shayy