puz

A Rust library for parsing .puz crossword puzzle files.

This library provides functionality to parse the binary .puz file format used by crossword puzzle applications like AcrossLite. It extracts puzzle metadata, grids, clues, and advanced features like rebus squares and circled squares.

Features

Complete .puz parsing - Extracts all puzzle data including metadata, grids, and clues
Rebus support - Handles puzzles with multi-character cell entries
Circled squares - Supports puzzles with circled cells
Checksum validation - Verifies file integrity during parsing
Rich metadata - Extracts title, author, copyright, notes, and more
Pure Rust - Memory-safe with zero-copy optimizations where possible
JSON ready - Optional serde support for serialization

Installation

Add this to your Cargo.toml:

[dependencies]
puz-parse = "0.1.0"

# For JSON serialization support:
puz-parse = { version = "0.1.0", features = ["json"] }

Quick Start

use puz_parse::parse_file;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse a .puz file
    let puzzle = parse_file("puzzle.puz")?;
    
    // Access puzzle information
    println!("Title: {}", puzzle.info.title);
    println!("Author: {}", puzzle.info.author);
    println!("Size: {}x{}", puzzle.info.width, puzzle.info.height);
    
    // Access clues
    for (num, clue) in &puzzle.clues.across {
        println!("{} Across: {}", num, clue);
    }

    Ok(())
}

Advanced Usage

For more control over parsing and error handling:

use std::fs::File;
use puz_parse::parse;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let file = File::open("puzzle.puz")?;
    let result = parse(file)?;
    let puzzle = result.result;
    
    // Handle any warnings that occurred during parsing
    for warning in &result.warnings {
        eprintln!("Warning: {}", warning);
    }

    Ok(())
}

Data Structure

The parsed puzzle contains:

info - Metadata (title, author, dimensions, etc.)
grid - Solution and blank grids
clues - Across and down clues by number
extensions - Advanced features (rebus, circles, given squares)

Examples

See the examples directory for more detailed usage examples.

File Format Support

This library supports the complete .puz file format specification, including:

Standard puzzles - Basic crossword grids with clues
Rebus squares - Cells containing multiple characters
Circled squares - Visual indicators for themed entries
Puzzle extensions - GRBS, RTBL, and GEXT sections
Checksum validation - File integrity verification
Scrambled puzzles - Puzzles with encoded solutions (read-only)

Error Handling

The library provides detailed error information:

use puz_parse::parse_file;

match parse_file("puzzle.puz") {
    Ok(puzzle) => {
        println!("Successfully parsed: {}", puzzle.info.title);
    }
    Err(e) => {
        eprintln!("Parse error: {}", e);
    }
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

puz-parse 0.1.2

puz