hwpers

A Rust library for parsing Korean Hangul Word Processor (HWP) files with full layout rendering support.

Features

Parser (Reading HWP files)

Complete HWP 5.0 Format Support: Parse all document components including text, formatting, tables, and embedded objects
Visual Layout Rendering: Reconstruct documents with pixel-perfect accuracy when layout data is available
Font and Style Preservation: Extract and apply original fonts, sizes, colors, and text formatting
Advanced Layout Engine: Support for multi-column layouts, line-by-line positioning, and character-level formatting
SVG Export: Render documents to scalable vector graphics
Zero-copy Parsing: Efficient parsing with minimal memory allocation
Safe Rust: Memory-safe implementation with comprehensive error handling

Writer (Creating HWP files) - v0.3.0+

Document Creation: Full HWP document writing support
Rich Text Formatting: Bold, italic, colors, fonts, sizes
Tables: Creation, styling, cell merging
Lists: Bullets, numbering, Korean/alphabetic/roman formats
Images: PNG/JPEG/BMP/GIF with captions
Text Boxes: Positioned and styled text boxes
Hyperlinks: URL, email, file, and bookmark links
Headers/Footers: Page numbers and custom content
Page Layout: Sizes, margins, orientation, columns, backgrounds

Quick Start

Add this to your Cargo.toml:

[dependencies]
hwpers = "0.3"

Basic Usage

use hwpers::HwpReader;

// Parse an HWP file
let document = HwpReader::from_file("document.hwp")?;

// Extract text content
let text = document.extract_text();
println!("{}", text);

// Access document properties
if let Some(props) = document.get_properties() {
    println!("Pages: {}", props.total_page_count);
}

// Iterate through sections and paragraphs
for (i, section) in document.sections().enumerate() {
    println!("Section {}: {} paragraphs", i, section.paragraphs.len());
    
    for paragraph in &section.paragraphs {
        if let Some(text) = &paragraph.text {
            println!("  {}", text.content);
        }
    }
}

Visual Layout Rendering

use hwpers::{HwpReader, render::{HwpRenderer, RenderOptions}};

let document = HwpReader::from_file("document.hwp")?;

// Create renderer with custom options
let options = RenderOptions {
    dpi: 96,
    scale: 1.0,
    show_margins: false,
    show_baselines: false,
};

let renderer = HwpRenderer::new(&document, options);
let result = renderer.render();

// Export first page to SVG
if let Some(svg) = result.to_svg(0) {
    std::fs::write("page1.svg", svg)?;
}

println!("Rendered {} pages", result.pages.len());

Creating Documents (v0.3.0+)

use hwpers::writer::HwpWriter;
use hwpers::model::hyperlink::Hyperlink;

// Create a new document
let mut writer = HwpWriter::new();

// Add formatted text
writer.add_aligned_paragraph(
    "제목",
    hwpers::writer::style::ParagraphAlignment::Center
)?;

// Add hyperlinks
let link = Hyperlink::new_url("Rust", "https://rust-lang.org");
writer.add_paragraph_with_hyperlinks(
    "Visit Rust website",
    vec![link]
)?;

// Configure page layout
writer.set_custom_page_size(210.0, 297.0, // A4 size
    hwpers::model::page_layout::PageOrientation::Portrait)?;
writer.set_page_margins_mm(20.0, 20.0, 20.0, 20.0);

// Add header and footer
writer.add_header("Document Header");
writer.add_footer_with_page_number("Page ", 
    hwpers::model::header_footer::PageNumberFormat::Numeric);

// Save the document
writer.save_to_file("output.hwp")?;

Advanced Formatting Access

// Access character and paragraph formatting
for section in document.sections() {
    for paragraph in &section.paragraphs {
        // Get paragraph formatting
        if let Some(para_shape) = document.get_para_shape(paragraph.para_shape_id as usize) {
            println!("Indent: {}, Alignment: {}", 
                para_shape.indent, 
                para_shape.get_alignment()
            );
        }
        
        // Get character formatting runs
        if let Some(char_shapes) = &paragraph.char_shapes {
            for pos_shape in &char_shapes.char_positions {
                if let Some(char_shape) = document.get_char_shape(pos_shape.char_shape_id as usize) {
                    println!("Position {}: Size {}, Bold: {}", 
                        pos_shape.position,
                        char_shape.base_size / 100,
                        char_shape.is_bold()
                    );
                }
            }
        }
    }
}

Supported Features

Document Structure

✅ File header and version detection
✅ Document properties and metadata
✅ Section definitions and page layout
✅ Paragraph and character formatting
✅ Font definitions (FaceName)
✅ Styles and templates

Content Types

✅ Text content with full Unicode support
✅ Tables and structured data
✅ Control objects (images, OLE objects)
✅ Numbering and bullet lists
✅ Tab stops and alignment

Layout and Rendering

✅ Page dimensions and margins
✅ Multi-column layouts
✅ Line-by-line positioning (when available)
✅ Character-level positioning (when available)
✅ Borders and fill patterns
✅ SVG export with accurate positioning

Advanced Features

✅ Compressed document support
✅ CFB (Compound File Binary) format handling
✅ Multiple encoding support (UTF-16LE)
✅ Error recovery and partial parsing

Command Line Tool

The library includes a command-line tool for inspecting HWP files:

# Install the tool
cargo install hwpers

# Inspect an HWP file
hwp_info document.hwp

Format Support

This library supports HWP 5.0 format files. For older HWP formats, consider using format conversion tools first.

Writer Features (v0.3.0+)

The HWP writer functionality has been significantly improved with comprehensive feature support:

✅ Fully Implemented

Hyperlinks: Complete hyperlink support with proper serialization
- URL links, email links, file links, bookmarks
- Multiple hyperlinks per paragraph
- Custom styling (colors, underline, visited state)
Header/Footer: Full header and footer implementation
- Custom header/footer text
- Page numbering with multiple formats (numeric, roman, etc.)
- Multiple headers/footers per document
Page Layout: Comprehensive page layout control
- Custom page sizes and standard sizes (A4, Letter, etc.)
- Portrait/landscape orientation
- Custom margins (narrow, normal, wide, custom)
- Multi-column layouts with adjustable spacing
- Page background colors
Tables: Full table creation and formatting
- Cell borders and styling
- Cell merging (horizontal and vertical)
- Custom cell content
Lists/Numbering: Complete list support
- Bullet lists with different symbols per level
- Numbered lists (1., 2., 3., ...)
- Alphabetic lists (a), b), c), ...)
- Roman numeral lists (i., ii., iii., ...)
- Korean lists (가., 나., 다., ...)
- Nested lists with proper indentation
Text Boxes: Full text box implementation
- Positioned text boxes
- Styled text boxes (highlight, warning, info, etc.)
- Custom styling (borders, backgrounds, alignment)
- Floating text boxes with rotation and transparency
Images: Complete image insertion
- PNG, JPEG, BMP, GIF support
- Custom dimensions and positioning
- Image captions
- Proper BinData integration
Styled Text: Rich text formatting
- Bold, italic, underline, strikethrough
- Custom fonts and sizes
- Text colors and background colors
- Multiple styles in single paragraph
Advanced Formatting:
- Paragraph alignment (left, center, right, justify)
- Line spacing control
- Paragraph spacing (before/after)
- Headings with automatic sizing
- Character and paragraph styles
Document Properties: Full metadata support
- Title, author, subject, keywords
- Document statistics (character count, word count, etc.)
- Automatic statistics updates

❌ Not Yet Implemented

Shapes/Drawing: Geometric shapes and drawing objects
- Rectangles, circles, ellipses
- Lines, arrows, polygons
- Custom shapes with styling
- Shapes with text content
- Shape grouping
- (See examples/shape_document.rs.disabled for usage examples)
Charts/Graphs: Data visualization objects
Mathematical Equations: MathML support
Forms: Input fields and form controls
Comments/Annotations: Review and comment features
Track Changes: Revision history
Mail Merge: Variable field insertion

🔧 Known Issues

No compression support for writer (reader supports both compressed and uncompressed)
Some advanced table features may have compatibility issues with older Hanword versions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

HWP file format specification by Hancom Inc.
Korean text processing community
Rust parsing and document processing ecosystem

hwpers 0.5.0