Pebble Programming Language

A modern systems programming language compiler built in Rust, featuring LLVM-based code generation, static typing, and memory-aware constructs.

🚀 Features

• Fast Lexical Analysis: Token-based lexer using the Logos crate
• LALR(1) Parser: Grammar-driven parsing with LALRPOP
• Static Type System: Type inference with explicit type annotations
• LLVM Code Generation: Native binary compilation via Inkwell
• Semantic Analysis: Symbol table management and type checking
• Memory Management: Built-in memory allocation primitives (alloc, shared alloc, transfer)
• Cross-Platform: Automatic target detection for Linux, macOS, and Windows

🏗️ Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Source Code   │───▶│      Lexer      │───▶│     Parser      │
│   (*.pebble)    │     │   (tokens.rs)   │     │   (parse.rs)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Native Binary  │◀───│  LLVM Codegen   │◀───│       AST       │
│  (executable)   │     │  (codegen/)     │     │     (ast.rs)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                 ▲                       │
                         ┌─────────────────┐    ┌─────────────────┐
                         │  Target Machine │    │ Semantic Check  │
                         │   & Linker      │    │  (semantic/)    │
                         └─────────────────┘    └─────────────────┘

📋 Language Syntax

Variables and Types

let x = 42;           // Type inference
let name: String = "Pebble";  // Explicit typing

Functions

fn add(a: int, b: int) -> int {
    return a + b;
}

Built-in Operations

print(argc);          // Print command-line argument count
print(argv);          // Print command-line arguments array

Memory Management

let ptr = alloc(42);        // Allocate memory
let shared = shared alloc(data);  // Shared allocation
let moved = transfer(ptr);        // Transfer ownership

🛠️ Getting Started

Prerequisites

• Rust 1.70+ with Cargo
• LLVM 18.1 development libraries
• GCC or Clang (for linking)

Building the Compiler

git clone https://github.com/mro95/pebble-rs.git
cd pebble-rs
cargo build --release

Compiling Pebble Programs

# Create a Pebble source file
echo 'print("Hello, Pebble!");' > hello.pebble

# Compile and run
cargo run hello.pebble
./output_bin

🎯 Example

Input (example.pebble):

print(argv);
print(argc);

Compilation:

$ cargo run example.pebble
Detected target: x86_64-unknown-linux-gnu
LLVM IR written to output.ll
Object file written to output.o
Successfully linked executable with gcc
Binary written to output_bin

Execution:

$ ./output_bin hello world
["./output_bin", "hello", "world"]
3

🔧 Project Structure

src/
├── main.rs              # Compiler driver and CLI
├── lib.rs               # Library root and module declarations
├── lexer.rs             # Token stream processing
├── tokens.rs            # Token definitions and lexer rules
├── parse.rs             # Parser interface
├── ast.rs               # Abstract Syntax Tree definitions
├── codegen/             # LLVM code generation
│   ├── mod.rs           # Code generator core
│   ├── expressions.rs   # Expression compilation
│   ├── statements.rs    # Statement compilation
│   ├── functions.rs     # Function compilation
│   ├── printing.rs      # Print statement implementation
│   └── types.rs         # Type system integration
├── semantic/            # Static analysis
│   ├── mod.rs           # Semantic analyzer
│   ├── scope.rs         # Symbol table management
│   ├── expr.rs          # Expression type checking
│   ├── stmt.rs          # Statement analysis
│   └── type.rs          # Type system and error handling
└── grammar/
    ├── grammar.ebnf     # Language grammar specification
    └── parser.lalrpop   # LALRPOP parser definition

🧪 Testing

Run the test suite:

cargo test

The project includes comprehensive tests for:

• Parser functionality (tests/parser_test.rs)
• Type system validation
• Code generation accuracy

🎨 Language Features

Type System

• Primitive Types: int, String, void
• Type Inference: Automatic type deduction where possible
• Array Types: Array<T> with bounds checking
• Function Types: First-class function support

Built-in Variables

• argc: Command-line argument count (int)
• argv: Command-line arguments array (Array)

Control Flow

• Function declarations with parameters and return types
• Block scoping with proper variable shadowing
• Return statements with type validation

🔍 LLVM Integration

The compiler generates optimized LLVM IR and produces native executables:

• Target Detection: Automatic host architecture detection
• Cross-compilation: Support for multiple target architectures
• Optimization: LLVM optimization passes for performance
• Debug Info: Structured debug information generation (planned)

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🔗 Dependencies

• logos 0.15.1 - Fast lexical analysis
• lalrpop 0.22.2 - Parser generator
• inkwell 0.6.0 - LLVM bindings for Rust
• thiserror 2.0 - Error handling macros

---