PGF2JSON

A Rust library for parsing Portable Grammar Format (PGF) files and converting them to JSON.

What is pgf2json • Features • How To Use • Documentation • License

🛎 Important Notices

• PGF Version Support: Stable for PGF 1.0, experimental support for version 2.1
• There seems to be a minor format difference between PGF 1.0 and 2.1 that needs addressing, but the core parser architecture is solid

📌 Table of Contents

🤔 What is pgf2json

pgf2json is a comprehensive Rust library that provides an API to load and interpret grammars compiled in Portable Grammar Format (PGF), which is the final output format from the Grammatical Framework (GF) compiler.

The library enables embedding GF grammars in Rust programs and converting them to structured JSON format for further processing or analysis.

Use Cases

• Grammar Analysis: Extract functions, categories, and language-specific concrete syntaxes
• Natural Language Processing: Parse sentences using loaded grammars
• Data Conversion: Convert binary PGF files to human-readable JSON format
• Research Tools: Analyze and experiment with GF grammars
• Integration: Embed GF functionality in Rust applications

🔋 Health Status

• ✅ All 11/11 tests passing (100% success rate)
• ✅ Synthetic PGF creation and JSON conversion working
• ✅ Error handling tests passing
• ✅ Parse sentence functionality working
• ✅ UTF-8 decoding issues resolved
• ✅ All PGF parsing functionality working correctly

📷 Features

pgf2json contains a complete PGF binary parser, covering all of the PGF v1.0 format specifications. The library's strengths include:

🔧 Core Functionality

• PGF Parsing: Read binary PGF files into Rust data structures
• JSON Conversion: Convert PGF grammars to structured JSON format
• Grammar Analysis: Extract functions, categories, and language-specific concrete syntaxes
• Sentence Parsing: Parse sentences using loaded grammars

🛠 Parser Capabilities

• Error Handling: Comprehensive error reporting for invalid files and parsing failures
• Version Support: Handles both PGF 1.0 and experimental PGF 2.1 formats
• Robust Parsing: Graceful handling of parsing errors to extract maximum information

📊 JSON Conversion

• Structured Output: Well-formatted JSON representation of PGF grammars
• Complete Coverage: All PGF components converted to JSON format
• Data Integrity: Maintains semantic accuracy during conversion

🔤 String Encoding

• UTF-8 Support: Handles UTF-8 encoded strings properly
• Latin-1 Fallback: Provides fallback mechanisms for Latin-1 encoded data
• Binary Data: Graceful handling of binary string data
• Version-Aware: Uses version-specific parsing strategies

🚙 How to Use

Installation

Add pgf2json to your Cargo.toml:

[dependencies]
pgf2json = "0.1"

Or install with cargo:

cargo add pgf2json

Basic Example

use pgf2json::{read_pgf, pgf_to_json, parse, language, types};

// Load a PGF file
let pgf = read_pgf("./grammars/Food.pgf")?;

// Convert to JSON
let json = pgf_to_json(&pgf)?;

// Parse a sentence
let lang = language::read_language("FoodEng").unwrap();
let typ = types::start_cat(&pgf);
let trees = parse(&pgf, &lang, &typ, "this pizza is delicious")?;

Advanced Usage

use pgf2json::*;

// Error handling with detailed reporting
match read_pgf("grammar.pgf") {
    Ok(pgf) => {
        println!("Successfully loaded PGF with {} languages", pgf.languages.len());
        
        // Convert to JSON with pretty printing
        match pgf_to_json(&pgf) {
            Ok(json) => println!("{}", serde_json::to_string_pretty(&json)?),
            Err(e) => eprintln!("JSON conversion failed: {}", e),
        }
    },
    Err(e) => eprintln!("Failed to load PGF: {}", e),
}

🧪 Testing

The test suite includes parsing real PGF files and validating JSON output structure with comprehensive coverage (~75% of functionality tested).

# Run all tests
cargo test

# Run specific test
cargo test test_real_pgf_parsing

# Run with debug output
DEBUG=1 cargo test test_real_pgf_parsing -- --nocapture

📚 Documentation

Comprehensive documentation is available at docs.rs/pgf2json, including:

• API reference for all public types and functions
• Tutorial on parsing PGF files and converting to JSON
• Examples of grammar analysis and sentence parsing
• Performance considerations and best practices

🖊 Author

CryptoPatrick

Keybase Verification:
https://keybase.io/cryptopatrick/sigs/8epNh5h2FtIX1UNNmf8YQ-k33M8J-Md4LnAN

🐣 Support

Leave a ⭐ if you think this project is cool.

🗄 License

This project is licensed under MIT. See LICENSE for details.