onion-frontend 0.2.2

# 🧅 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


```rust
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


```rust
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.