🧅 Onion Frontend

The compilation frontend for the Onion programming language. This package handles lexical analysis, parsing, semantic analysis, and intermediate representation generation.

📚 Overview

The onion-frontend package is responsible for transforming Onion source code into intermediate representation (IR) that can be executed by the Onion Virtual Machine. It implements a complete compilation pipeline from source text to executable bytecode.

🏗️ Architecture

Source Code → Lexer → Parser → AST → Analyzer → IR Generator → IR/Bytecode

Components

• Lexer (parser/lexer.rs) - Tokenizes source code into a stream of tokens
• Parser (parser/ast.rs) - Builds Abstract Syntax Tree (AST) from tokens
• Analyzer (parser/analyzer.rs) - Performs semantic analysis and error checking
• IR Generator (ir_generator/) - Generates intermediate representation from AST
• Compiler (compile.rs) - Orchestrates the entire compilation process

✨ Features

• 🔍 Lexical Analysis - Complete tokenization with support for Unicode
• 🌳 AST Generation - Builds structured representation of source code
• 🔎 Semantic Analysis - Type checking and error detection
• 📦 IR Generation - Produces optimized intermediate representation
• 🚀 Bytecode Compilation - Generates executable bytecode for the VM
• 🔧 Error Reporting - Rich error messages with source location information

🚀 Usage

Basic Compilation

use onion_frontend::compile::{build_code, compile_to_bytecode};
use onion_frontend::dir_stack::DirectoryStack;

// Compile to IR
let mut dir_stack = DirectoryStack::new();
let source = r#"
    @required stdlib;
    main := () -> {
        stdlib.io.println("Hello, World!");
    };
    main();
"#;

let ir_package = build_code(source, &mut dir_stack)?;

// Compile to bytecode
let bytecode = compile_to_bytecode(source, &mut dir_stack)?;

Advanced Usage

use onion_frontend::parser::lexer;
use onion_frontend::parser::ast::{ast_token_stream, build_ast};
use onion_frontend::parser::analyzer::analyze_ast;

// Manual compilation pipeline
let tokens = lexer::tokenize(source);
let tokens = lexer::reject_comment(&tokens);
let gathered = ast_token_stream::from_stream(&tokens);
let ast = build_ast(gathered)?;
let analysis = analyze_ast(&ast, None, &mut dir_stack);

📋 API Reference

Main Functions

• build_code(code: &str, dir_stack: &mut DirectoryStack) -> Result<IRPackage, String>

  • Compiles source code to intermediate representation

• compile_to_bytecode(code: &str, dir_stack: &mut DirectoryStack) -> Result<VMInstructionPackage, String>

  • Compiles source code directly to bytecode

Key Types

• IRPackage - Contains intermediate representation and debug information
• VMInstructionPackage - Executable bytecode package
• DirectoryStack - Manages file paths and module resolution

🔧 Dependencies

• onion-vm - Virtual machine types and instruction definitions
• colored - Terminal color output for error messages
• regex - Regular expression support for lexical analysis
• unicode-segmentation - Unicode-aware string processing
• base64 - Encoding support for bytecode serialization

🏗️ Module Structure

onion-frontend/
├── src/
│   ├── lib.rs              # Public API exports
│   ├── compile.rs          # Main compilation orchestration
│   ├── dir_stack.rs        # Directory and path management
│   ├── parser/             # Lexical and syntactic analysis
│   │   ├── mod.rs
│   │   ├── lexer.rs        # Tokenization
│   │   ├── ast.rs          # AST construction
│   │   └── analyzer.rs     # Semantic analysis
│   └── ir_generator/       # Intermediate representation
│       ├── mod.rs
│       └── ir_generator.rs # IR generation logic
└── Cargo.toml

🎯 Design Goals

1. Correctness - Comprehensive error checking and validation
2. Performance - Efficient compilation with minimal overhead
3. Extensibility - Modular design for easy feature additions
4. Developer Experience - Clear error messages and debugging support

🤝 Integration

This package is designed to work seamlessly with:

• onion-vm - Executes the generated bytecode
• Language Server - Provides IDE support through compilation services
• CLI Tools - Powers the onion compile command

📄 License

This package is part of the Onion programming language project and is licensed under the MIT License.