BPL (Best Programming Language) v3

BPL is a statically-typed, compiled programming language that transpiles to LLVM IR. It combines the performance and control of systems languages with modern language features, making it ideal for performance-critical applications, systems programming, and educational purposes.

import [IO] from "std/io.bpl";

struct Point {
    x: int,
    y: int
}

frame main() ret int {
    local p: Point;
    p.x = 10;
    p.y = 20;
    IO.log("Hello from BPL!");
    return 0;
}

✨ Features

🚀 Performance First

• LLVM Backend: Leverages LLVM's world-class optimization and code generation
• Zero-Cost Abstractions: High-level features without runtime overhead
• Manual Memory Management: Direct control over allocations for predictable performance
• Native Compilation: Produces optimized machine code for your platform

🔒 Type Safety

• Strong Static Typing: Catch errors at compile-time before they become runtime bugs
• Generics: Write reusable, type-safe code with full monomorphization
• No Null Dereferences: Explicit null handling patterns
• Type Inference: Less verbose where it matters, explicit where it helps

🏗️ Modern Language Features

• Object-Oriented: Structs with methods, single and multiple inheritance
• Module System: Organize code with imports and exports
• Exception Handling: Try/catch blocks for robust error management
• Pattern Matching: Type-safe conditional logic
• Process execution: Execute shell commands, check status, and capture output with automatic injection protection
• String Interpolation: Embed expressions in strings with `Hello ${name}`
• Tuples: Multi-value types for clean APIs
• Function Pointers: First-class functions

🛠️ Developer Experience

• Clear Error Messages: Helpful compiler diagnostics with location information
• Built-in Formatter: Automatic code formatting for consistent style
• Watch Mode: Automatic recompilation on file changes for rapid development
• Package Manager: Easy dependency management with bpl install
• Cross-Platform: Compile for Linux, macOS, Windows, ARM, and more
• VS Code Extension: Full language server with IntelliSense, go-to-definition, hover tooltips, and smart completions
• Incremental Compilation: Fast rebuilds with module caching

📦 Installation

Build from Source

git clone https://github.com/pr0h0/bpl3.git
cd bpl3
./init.sh
bpl --version

Prerequisites

You'll need:

1. Clang/LLVM (13+) - for compiling LLVM IR to native code
2. Bun - for running the compiler

Linux (Ubuntu/Debian):

sudo apt-get install clang llvm
curl -fsSL https://bun.sh/install | bash

macOS:

brew install llvm
curl -fsSL https://bun.sh/install | bash

Windows: Download LLVM from releases.llvm.org or use WSL.

Verify Installation

bpl --version
echo 'extern printf(fmt: string, ...); frame main() ret int { printf("It works!\n"); return 0; }' > test.bpl
bpl test.bpl --run

For detailed installation instructions, see the Installation Guide.

🚀 Quick Start

Hello World

Create hello.bpl:

extern printf(fmt: string, ...);

frame main() ret int {
    printf("Hello, World!\n");
    return 0;
}

Compile and run:

bpl run hello.bpl

Or just compile:

bpl hello.bpl -o hello

Run code without a file

You can execute snippets or piped input directly:

• Evaluate a snippet from the command line:

  bpl -e 'frame main() ret int { return 0; }'

• Compile from stdin (helpful with cat/pipes):

  cat examples/hello-world/main.bpl | bpl --stdin

--emit tokens|ast|formatted|llvm works with both -e and --stdin; diagnostics show <eval>/<stdin> in locations.

More Examples

Variables and Types:

extern printf(fmt: string, ...);

frame main() ret int {
    local x: int = 42;
    local name: string = "BPL";
    local pi: float = 3.14159;

    printf("%s: x = %d, pi = %f\n", name, x, pi);
    return 0;
}

Functions:

extern printf(fmt: string, ...);

frame add(a: int, b: int) ret int {
    return a + b;
}

frame main() ret int {
    local result: int = add(5, 3);
    printf("5 + 3 = %d\n", result);
    return 0;
}

Structs and Methods:

extern printf(fmt: string, ...);

struct Point {
    x: int,
    y: int,

    frame new(x: int, y: int) ret Point {
        local p: Point;
        p.x = x;
        p.y = y;
        return p;
    }

    frame print(this: Point) ret void {
        printf("Point(%d, %d)\n", this.x, this.y);
    }
}

frame main() ret int {
    local p: Point = Point.new(10, 20);
    p.print();
    return 0;
}

Generics:

extern printf(fmt: string, ...);

struct Box<T> {
    value: T,

    frame new(val: T) ret Box<T> {
        local b: Box<T>;
        b.value = val;
        return b;
    }
}

frame main() ret int {
    local intBox: Box<int> = Box<int>.new(42);
    local floatBox: Box<float> = Box<float>.new(3.14);

    printf("Int: %d, Float: %f\n", intBox.value, floatBox.value);
    return 0;
}

Using Standard Library:

import [Vec] from "std/vec.bpl";
import [IO] from "std/io.bpl";

frame main() ret int {
    local numbers: Vec<int> = Vec<int>.new(5);
    numbers.push(10);
    numbers.push(20);
    numbers.push(30);

    IO.log("Vector contents:");
    local i: int = 0;
    loop (i < numbers.len()) {
        IO.printInt(numbers.get(i));
        i = i + 1;
    }

    return 0;
}

For more examples, check out the examples directory or the Quick Start Guide.

📖 Documentation

Comprehensive documentation is available in the docs/ directory:

Getting Started

• Introduction - What is BPL and why use it?
• Installation - Setup guide for all platforms
• Quick Start - Write your first program in 5 minutes

Core Concepts

• Syntax and Comments - Basic syntax rules
• Types and Variables - Type system and declarations
• Operators - All operators explained
• Control Flow - If, loop, switch statements
• Functions - Declaring and calling functions
• Structs - Custom data types
• Generics - Generic programming

Advanced Topics

• Pointers - Memory manipulation
• Arrays and Tuples - Collections
• Inheritance - OOP in BPL
• Module System - Organizing code
• Error Handling - Exception handling
• Standard Library - Built-in functionality

Reference

• Language Specification - Formal specification
• CLI Reference - All command-line options
• Standard Library API - Complete API reference

💻 Command Line Interface

Quick Reference

# Compile and run a program
bpl run main.bpl

# Development mode with watch and auto-run
bpl dev main.bpl

# Build an executable
bpl build main.bpl -o myprogram

# Type check without code generation (fast)
bpl check main.bpl

# Create a new project
bpl new my-project

# Format code
bpl format main.bpl -w

# Clean build artifacts
bpl clean

Core Commands

bpl run <file> [args...]

Compile and execute a BPL program in one step:

# Run a program
bpl run main.bpl

# Pass arguments to the program
bpl run main.bpl arg1 arg2

# Run with optimization
bpl run main.bpl -O 2

# Run with timing statistics
bpl run main.bpl --time

bpl dev <file> [args...]

Development mode with automatic recompilation and execution:

# Watch and run on changes
bpl dev main.bpl

# Clear screen on each recompile
bpl dev main.bpl --clear

# Watch but only compile (don't run)
bpl dev main.bpl --no-run

bpl build <file>

Explicitly compile a program:

# Basic compilation (generates LLVM IR)
bpl build main.bpl

# Specify output filename
bpl build main.bpl -o myprogram

# Verbose output
bpl build main.bpl -v

# Enable incremental compilation
bpl build main.bpl --cache

bpl check <files...>

Fast type checking without code generation:

# Check a single file
bpl check main.bpl

# Check multiple files
bpl check src/*.bpl

# JSON output for tooling
bpl check main.bpl --json

bpl new <name>

Create a new BPL project with standard structure:

# Create new project
bpl new my-project
cd my-project
bpl run main.bpl

This creates:

• bpl.json - Package manifest
• main.bpl - Entry point with Hello World
• lib/ - Local library directory
• README.md - Project documentation
• .gitignore - Git ignore rules

bpl clean

Remove build artifacts:

# Remove all build artifacts
bpl clean

# Dry run (show what would be deleted)
bpl clean --dry-run

# Verbose output
bpl clean -v

Compilation Options

Global Flags

These work with any command:

-v, --verbose          Enable verbose output
-q, --quiet            Suppress non-error output
-O <level>             Optimization level: 0, 1, 2, or 3
--debug, -d            Generate DWARF debug information
--time                 Show compilation time statistics
--cache                Enable incremental compilation
--color/--no-color     Force/disable colored output
--json                 Output in JSON format (for check command)

Emit Options

Control what the compiler outputs:

# Emit LLVM IR (default)
bpl build main.bpl --emit llvm

# Emit AST as JSON
bpl build main.bpl --emit ast

# Emit tokens
bpl build main.bpl --emit tokens

# Format source code
bpl format main.bpl

Cross-Compilation

Compile for different platforms and architectures:

# Cross-compile for ARM64 Linux
bpl build main.bpl --target aarch64-unknown-linux-gnu --march=armv8-a

# Cross-compile for Windows x64
bpl build main.bpl --target x86_64-pc-windows-gnu

# Cross-compile for macOS ARM64
bpl build main.bpl --target arm64-apple-darwin

# Specify sysroot for cross-compilation
bpl build main.bpl --target aarch64-unknown-linux-gnu --sysroot /opt/sysroots/aarch64

# Pass additional flags to clang
bpl build main.bpl --clang-flag=-O3 --clang-flag=-static

Supported target triples:

• x86_64-pc-linux-gnu (Linux x64)
• aarch64-unknown-linux-gnu (Linux ARM64)
• arm64-apple-darwin (macOS ARM64)
• x86_64-apple-darwin (macOS x64)
• x86_64-pc-windows-gnu (Windows x64)

Code Formatting

# Format and print to stdout
bpl format main.bpl

# Format and write back to file
bpl format -w main.bpl

# Format multiple files
bpl format -w src/**/*.bpl

Package Management

# Initialize a new project
bpl init my-project

# Create a package tarball
bpl pack

# Install a package
bpl install package-name-1.0.0.tgz

# Install all dependencies from bpl.json
bpl install

# List installed packages
bpl list

# Uninstall a package
bpl uninstall package-name

See the Package Management Guide for details.

Shell Completion

BPL provides command-line completion for Bash and Zsh shells:

# Generate Bash completion script
bpl completion bash > ~/.local/share/bash-completion/completions/bpl

# Or add to your ~/.bashrc:
source <(bpl completion bash)

# Generate Zsh completion script
mkdir -p ~/.local/share/zsh/completions
bpl completion zsh > ~/.local/share/zsh/completions/_bpl

# Add to ~/.zshrc:
fpath=(~/.local/share/zsh/completions $fpath)

# Reload completions
rm -f ~/.zcompdump; compinit

After installation, you can use Tab to complete commands, flags, and file paths!

🌟 Language Highlights

Type System

BPL features a rich, safe type system:

• Primitive types: int, float, bool, char
• Composite types: pointers, arrays, tuples
• User-defined types: structs with fields and methods
• Generics: Type parameters for functions and structs
• Type aliases: Create meaningful names for complex types

type UserID = int;
type Callback = Func<void>(int);
type Point3D = (float, float, float);

struct Result<T, E> {
    ok: T,
    err: E,
    is_ok: bool
}

Memory Management

Manual memory management with safety helpers:

extern malloc(size: i64) ret *void;
extern free(ptr: *void);

frame main() ret int {
    # Allocate
    local ptr: *int = cast<*int>(malloc(sizeof(int) * 10));

    # Use
    ptr[0] = 42;

    # Free
    free(cast<*void>(ptr));

    return 0;
}

Inheritance

Single and multiple inheritance supported:

struct Animal {
    name: string,
    frame speak() { printf("...\n"); }
}

struct Dog : Animal {
    breed: string,
    frame speak() { printf("Woof!\n"); }  # Override
}

struct Bird : Animal {
    wingspan: float
}

# Multiple inheritance
struct Platypus : Animal, Swimmer {
    # ...
}

Module System

Organize code across files:

# math.bpl
export add, multiply;

frame add(a: int, b: int) ret int {
    return a + b;
}

frame multiply(a: int, b: int) ret int {
    return a * b;
}

# main.bpl
import add, multiply from "./math.bpl";

frame main() ret int {
    local sum: int = add(5, 3);
    local product: int = multiply(5, 3);
    return 0;
}

🔧 Standard Library

BPL includes a comprehensive standard library:

Module	Description	Example
std/io.bpl	Input/output operations	IO.log("Hello")
std/string.bpl	String manipulation	String.concat(a, b)
std/array.bpl	Dynamic arrays	Array<int>.new(10)
std/vec.bpl	Growable vectors	Vec<int>.new(0)
std/map.bpl	Hash maps	Map<K, V>.new()
std/set.bpl	Hash sets	Set<T>.new()
std/fs.bpl	File system ops	FS.readFile(path)
std/math.bpl	Math functions	Math.sqrt(x)
std/time.bpl	Time operations	Time.now()
std/json.bpl	JSON parsing	JSON.parse(str)
std/option.bpl	Optional values	Option<T>.some(val)
std/result.bpl	Error handling	Result<T, E>

See the Standard Library documentation for complete API reference.

📁 Project Structure

bpl3/
├── compiler/           # Compiler implementation
│   ├── frontend/       # Lexer (Peggy) and parser
│   ├── middleend/      # Type checker, module resolver, linker
│   ├── backend/        # LLVM IR code generation
│   │   └── codegen/    # Generators for expressions, types, etc.
│   ├── formatter/      # Code formatter
│   ├── linter/         # Code linting
│   ├── docs/           # Documentation generator
│   └── common/         # Shared utilities
│       ├── AST.ts      # AST definitions
│       ├── CompilerError.ts # Error handling
│       ├── Config.ts   # Centralized configuration
│       ├── Logger.ts   # Structured logging
│       └── ...         # Path resolution, source management
├── cli/                # Command-line interface
│   ├── index.ts        # CLI entry point
│   ├── commands/       # Subcommand handlers
│   └── completions/    # Shell completions
├── docs/               # Comprehensive documentation
│   ├── 01-introduction.md
│   ├── 02-installation.md
│   ├── 03-quick-start.md
│   └── ...             # 50+ documentation files
├── examples/           # 70+ working examples
│   ├── hello-world/
│   ├── fibonacci/
│   ├── generics/
│   ├── stdlib_*/       # Standard library examples
│   └── ...
├── grammar/            # PEG grammar definitions
│   └── bpl.peggy       # Language grammar
├── lib/                # Standard library
│   ├── io.bpl          # Input/output
│   ├── array.bpl       # Dynamic arrays
│   ├── vec.bpl         # Vectors
│   ├── map.bpl         # Hash maps
│   ├── string.bpl      # String utilities
│   └── ...             # 20+ stdlib modules
├── tests/              # Comprehensive test suite
│   ├── Integration.test.ts
│   ├── Parser.test.ts
│   └── ...
├── benchmark/          # Performance benchmarks
├── vscode-ext/         # VS Code extension
├── playground/         # Web playground (optional)
├── index.ts            # Main entry point
├── LANGUAGE_SPEC.md    # Language specification
└── README.md           # This file

🧪 Examples

The examples/ directory contains 70+ working examples demonstrating every language feature:

Beginner Examples

• hello-world/ - Your first program
• variables/ - Variable declarations
• math/ - Arithmetic operations
• if-statements/ - Conditionals
• loops/ - Loop constructs

Intermediate Examples

• functions/ - Function definitions
• structs/ - Custom data types
• arrays/ - Array operations
• pointers/ - Pointer manipulation
• strings/ - String handling

Advanced Examples

• generics/ - Generic programming
• generics_advanced/ - Complex generics
• objects_inheritance/ - OOP patterns
• multi_inheritance/ - Multiple inheritance
• error_handling/ - Exception handling

Standard Library Examples

• stdlib_io/ - I/O operations
• stdlib_vec/ - Dynamic arrays
• stdlib_map_set/ - Hash maps and sets
• stdlib_json/ - JSON parsing
• stdlib_fs/ - File system
• stdlib_time/ - Time operations

Complete Applications

• fibonacci/ - Fibonacci sequence
• collatz/ - Collatz conjecture
• recursive_algorithms/ - Recursion examples

Each example includes:

• Source code (.bpl files)
• Expected output (in test configurations)
• Build and test scripts

Run any example:

cd examples/fibonacci
bpl main.bpl --run

🧑‍💻 Development

Running Tests

# Run all tests
bun test

# Run specific test file
bun test tests/Integration.test.ts

# Run tests matching pattern
bun test -t "generics"

Type Checking

# Check TypeScript types
bun run check

Building the Compiler

# Build executable
bun run build

# Development mode (no build)
bun index.ts examples/hello-world/main.bpl --run

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (bun test)
5. Format code (bun run format)
6. Commit (git commit -m 'Add amazing feature')
7. Push (git push origin feature/amazing-feature)
8. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

🎓 Learning Resources

Documentation

• Start with the Quick Start Guide
• Read the Language Specification
• Explore example programs
• Check the Standard Library docs

Video Tutorials

Coming soon!

Community

• GitHub Discussions - Ask questions, share projects
• GitHub Issues - Report bugs, request features
• Discord - Real-time chat (link coming soon)

🚦 Roadmap

Current Status: Beta

BPL is under active development. The compiler is stable with 1,342 tests passing across 88 test files.

Build Status:

• ✅ 1,342 tests passing (100%)
• ✅ 0 ESLint errors/warnings
• ✅ 0 TypeScript errors
• ✅ 100+ working examples

Completed ✅

• Full LLVM IR backend
• Static type system with generics
• Structs with inheritance
• Module system with imports/exports
• Exception handling (try/catch)
• Package manager
• Code formatter
• Cross-compilation support
• Standard library (20+ modules)
• VS Code extension
• Comprehensive test suite (1,342 tests)
• Documentation (50+ pages)
• Enum types with pattern matching
• String interpolation
• Lambda expressions
• Tuple destructuring (including nested)
• Operator overloading (24 operators)
• Intrinsics (math, bit manipulation, memory)

In Progress 🚧

• IDE integrations (beyond VS Code)
• More stdlib modules (networking, threads)
• Optimization passes

Planned 📋

• Package registry
• Incremental compilation improvements
• Inline assembly improvements
• C++ interop improvements
• WebAssembly target
• Self-hosting compiler

See TODO.md for detailed task list.

📊 Benchmarks

BPL produces competitive performance with C/C++:

Benchmark	BPL	C (gcc -O2)	C++ (g++ -O2)
Fibonacci (recursive)	1.23s	1.19s	1.21s
Array sum	0.45s	0.43s	0.44s
Matrix multiply	2.10s	2.05s	2.08s

Note: Benchmarks run on AMD Ryzen 9 5900X, Linux 5.15

🔍 Comparison with Other Languages

Feature	BPL	C	C++	Rust	Go
Manual memory mgmt	✅	✅	✅	✅*	❌
Generics	✅	❌	✅	✅	✅
Inheritance	✅	❌	✅	❌	❌
Exceptions	✅	❌	✅	❌	✅
Module system	✅	❌	⚠️	✅	✅
Package manager	✅	❌	⚠️	✅	✅
Memory safety**	⚠️	❌	❌	✅	✅
Learning curve	⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐
Compile speed	⚡⚡	⚡⚡⚡	⚡	⚡	⚡⚡⚡
Runtime performance	⚡⚡⚡	⚡⚡⚡	⚡⚡⚡	⚡⚡⚡	⚡⚡

*Rust uses ownership/borrowing instead of GC
**Planned for BPL

📝 License

BPL is licensed under the Apache License 2.0.

See LICENSE for details.

👤 Author

pr0h0

• GitHub: @pr0h0
• Email: contact via GitHub

🙏 Acknowledgments

• LLVM Project - For the amazing compiler infrastructure
• Bun - For the fast JavaScript runtime
• Community Contributors - For bug reports and feature requests

📞 Support

Need help?

1. Documentation - Check the docs/ directory
2. Examples - Browse examples/
3. Issues - Search or create a GitHub Issue
4. Discussions - Join GitHub Discussions

🔗 Links

• GitHub Repository: https://github.com/pr0h0/bpl3
• Documentation: docs/
• Examples: examples/
• Language Spec: LANGUAGE_SPEC.md

---

Happy Coding! 🚀

BPL - Where performance meets modern language design