Oak Protobuf Parser

A high-performance Protobuf parser for Rust, built with the Oak parser combinator framework. Parse Protocol Buffer definitions with comprehensive AST generation and error handling.

Overview

Oak Protobuf provides robust parsing capabilities for Protocol Buffer schema files, supporting messages, enums, services, fields, options, and all major Protobuf constructs. Built on the Oak parser combinator framework, it delivers excellent performance and detailed error messages.

Features

✅ Complete Protobuf Support: Parse messages, enums, services, fields, options, and imports
✅ 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 Protobuf dialects
✅ Well Tested: Comprehensive test suite with real-world examples

Quick Start

Parsing Examples

Basic Message Parsing

use oak::{Parser, Language};
use oak_protobuf::ProtobufLanguage;

fn main() {
    let source = r#"
        kind = "proto3";
        
        package example;
        
        message Person {
            string name = 1;
            int32 age = 2;
            repeated string emails = 3;
        }
    "#;
    
    let mut parser = Parser::<ProtobufLanguage>::new();
    match parser.parse(&source) {
        Ok(ast) => {
            println!("Parsed AST: {:#?}", ast);
        }
        Err(error) => {
            eprintln!("Parse error: {}", error);
        }
    }
}

Complex Schema with Services

use oak::{Parser, Language};
use oak_protobuf::ProtobufLanguage;

fn main() {
    let source = r#"
        kind = "proto3";
        
        package bookstore;
        
        import "google/protobuf/timestamp.proto";
        
        message Book {
            string isbn = 1;
            string title = 2;
            repeated string authors = 3;
            google.protobuf.Timestamp published_date = 4;
        }
        
        service BookService {
            rpc GetBook(GetBookRequest) returns (Book);
            rpc ListBooks(ListBooksRequest) returns (stream Book);
        }
        
        message GetBookRequest {
            string isbn = 1;
        }
        
        message ListBooksRequest {
            int32 page_size = 1;
            string page_token = 2;
        }
    "#;
    
    let mut parser = Parser::<ProtobufLanguage>::new();
    match parser.parse(&source) {
        Ok(ast) => {
            println!("Service definitions parsed successfully!");
        }
        Err(error) => {
            eprintln!("Parse error: {}", error);
        }
    }
}

Advanced Features

Custom Options

Oak Protobuf supports parsing custom options:

let source = r#"
    kind = "proto3";
    
    message MyMessage {
        string value = 1 [(custom_option) = "test"];
    }
"#;

Enum Definitions

Parse enum types with aliases and custom options:

let source = r#"
    enum Status {
        UNKNOWN = 0;
        ACTIVE = 1;
        INACTIVE = 2 [(custom_option) = "deprecated"];
    }
"#;

AST Structure

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

ProtobufFile - Root node containing the entire file
Syntax - Syntax version declaration
Package - Package declaration
Import - Import statements
Message - Message definitions with fields
Enum - Enum type definitions
Service - Service definitions with RPC methods
Field - Message fields with types and options
Option - Custom options for various elements

Performance

Oak Protobuf is designed for high performance:

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

Integration

Oak Protobuf integrates seamlessly with the Oak ecosystem:

use oak::{Parser, Language};
use oak_protobuf::ProtobufLanguage;

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

Examples

More examples can be found in the examples directory:

Contributing

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

oak-protobuf 0.0.0