Oak Tcl Parser

A high-performance Tcl parser for Rust, built with the Oak parser combinator framework. Parse Tool Command Language scripts with comprehensive AST generation and error handling.

Overview

Oak Tcl provides robust parsing capabilities for Tcl script files, supporting commands, procedures, control structures, and all major Tcl constructs. Built on the Oak parser combinator framework, it delivers excellent performance and detailed error messages.

Features

• ✅ Complete Tcl Support: Parse commands, procedures, control structures, and variables
• ✅ Modern Rust API: Type-safe parsing with comprehensive error handling
• ✅ High Performance: Built on the efficient Oak parser combinator framework
• ✅ Rich AST: Detailed Abstract Syntax Tree with source location tracking
• ✅ Extensible: Easy to extend for custom Tcl dialects
• ✅ Well Tested: Comprehensive test suite with real-world examples

Quick Start

Parsing Examples

Basic Command Parsing

use oak_core::{Parser, SourceText, parser::session::ParseSession};
use oak_tcl::{TclParser, TclLanguage};

fn main() {
    let mut session = ParseSession::<TclLanguage>::default();
    let parser = TclParser::new();
    let source = SourceText::new(r#"
        set name "World"
        puts "Hello, $name!"
        
        set numbers {1 2 3 4 5}
        set sum 0
        foreach num $numbers {
            set sum [expr {$sum + $num}]
        }
        puts "Sum: $sum"
    "#);
    
    let result = parser.parse(&source, &[], &mut session);
}

Procedure Definition

use oak_core::{Parser, SourceText, parser::session::ParseSession};
use oak_tcl::{TclParser, TclLanguage};

fn main() {
    let mut session = ParseSession::<TclLanguage>::default();
    let parser = TclParser::new();
    let source = SourceText::new(r#"
        proc factorial {n} {
            if {$n <= 1} {
                return 1
            } else {
                return [expr {$n * [factorial [expr {$n - 1}]]}]
            }
        }
        
        proc greet {name {greeting "Hello"}} {
            return "$greeting, $name!"
        }
        
        puts [factorial 5]
        puts [greet "World"]
        puts [greet "World" "Hi"]
    "#);
    
    let result = parser.parse(&source, &[], &mut session);
}

Advanced Features

Lists and Arrays

Oak Tcl supports parsing complex list operations:

use oak_core::{Parser, SourceText, parser::session::ParseSession};
use oak_tcl::{TclParser, TclLanguage};

let mut session = ParseSession::<TclLanguage>::default();
let parser = TclParser::new();
let source = SourceText::new(r#"
    set my_list {apple banana cherry}
    set first [lindex $my_list 0]
    set last [lindex $my_list end]
    
    array set my_array {
        key1 value1
        key2 value2
    }
"#);

let result = parser.parse(&source, &[], &mut session);

Regular Expressions

Parse regexp operations:

let source = r#"
    set text "Hello World 123"
    set pattern {\d+}
    if {[regexp $pattern $text match]} {
        puts "Found number: $match"
    }
    
    set result [regsub $pattern $text "XXX"]
    puts "Modified: $result"
"#;

AST Structure

The parser generates a rich AST with the following main node types:

• TclFile - Root node containing the entire file
• Command - Tcl commands with arguments
• Procedure - Procedure definitions with parameters and body
• Variable - Variable references and assignments
• Expression - Expressions in square brackets
• List - List literals and operations
• ControlFlow - if, while, for, foreach statements
• String - String literals with interpolation

Performance

Oak Tcl is designed for high performance:

• Zero-copy parsing where possible
• Streaming support for large script files
• Efficient memory usage with minimal allocations
• Fast error recovery for better developer experience

Integration

Oak Tcl integrates seamlessly with the Oak ecosystem:

use oak::{Parser, Language};
use oak_tcl::TclLanguage;

// Use with other Oak parsers
let mut parser = Parser::<TclLanguage>::new();
let result = parser.parse(tcl_source);

Examples

More examples can be found in the examples directory:

• Basic commands
• Procedures
• Control structures
• Lists and arrays
• Error handling

Contributing

We welcome contributions! Please see our Contributing Guide for details.