About PooLang

A Tiny Interpreted language written in Rust, featuring variable declarations, arithmetic operations, conditional statements, and control flow. This project includes a lexer, parser, and interpreter. The name Poo originates from Guinea Pig translated from Burmese.

Table of Contents

• Features
• Get Started
• Installation
• Release
• Usage
• Syntax Overview
• Example Code
• Development
• Contributing

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

Choose the fastest install path for your platform:

Linux / macOS (Universal Shell Installer)

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

Windows (PowerShell Installer)

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

macOS (Homebrew)

brew install shayyz-code/tap/poo

Windows (Scoop)

scoop bucket add shayyz-code https://github.com/shayyz-code/scoop-bucket
scoop install poo

Verify Installation

poo --help

Installation

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. Build the project:

   cargo build

3. Run tests:

   cargo test

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

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

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 feel free to submit a Pull Request or open an Issue if you find a bug or have a feature request.

Steps to Contribute

1. Fork the repository.

2. Create a new branch:

   git checkout -b feature/your-feature-name

3. Make your changes and commit them:

   feat: Allow provided config object to extend other configs by <your-username>
   
   BREAKING CHANGE: `extends` key in config file is now used for extending other config files.

4. Push to the branch:

   git push origin feature/your-feature-name

5. Open a Pull Request.

Feedback

If you have any questions or feedback, feel free to reach out or open an issue in the repository.