Unhwp 0.18.0

Unhwp

High-performance .NET library for extracting HWP/HWPX Korean word processor documents to Markdown.

Installation

dotnet add package Unhwp

Or via NuGet Package Manager:

Install-Package Unhwp

Quick Start

using Unhwp;

// Parse a document
using var doc = UnhwpDocument.ParseFile("document.hwp");

// Convert to Markdown
string markdown = doc.ToMarkdown();
Console.WriteLine(markdown);

// Plain text and JSON
string text = doc.ToText();
string json = doc.ToJson();

Console.WriteLine($"Sections: {doc.SectionCount}");

With Markdown Options

using var doc = UnhwpDocument.ParseFile("document.hwpx");

var markdown = doc.ToMarkdown(new MarkdownOptions
{
    IncludeFrontmatter = true,
    Refine = true
});

Parse from Bytes

byte[] data = File.ReadAllBytes("document.hwp");
using var doc = UnhwpDocument.ParseBytes(data);

Tables as CSV

using var doc = UnhwpDocument.ParseFile("document.hwp");

foreach (var table in doc.GetTables())
{
    File.WriteAllText($"s{table.Section}-t{table.Index}.csv", table.Text);
}

Extract Images

using var doc = UnhwpDocument.ParseFile("document.hwp");

foreach (var id in doc.GetResourceIds())
{
    var data = doc.GetResourceData(id);
    if (data != null)
        File.WriteAllBytes(Path.Combine("output", id), data);
}

Handling Failures

UnhwpException.Kind says why a call failed, so you can react to the reason instead of matching on message text:

try
{
    using var doc = UnhwpDocument.ParseFile(path);
}
catch (UnhwpException ex)
{
    switch (ex.Kind)
    {
        case UnhwpErrorKind.OleContainer:
        case UnhwpErrorKind.ZipArchive:
            Console.Error.WriteLine("The file is damaged.");
            break;
        case UnhwpErrorKind.UnknownFormat:
        case UnhwpErrorKind.UnsupportedFormat:
            Console.Error.WriteLine("Not a supported HWP/HWPX document.");
            break;
        default:
            // Also the right branch for a reason this build has no name for.
            Console.Error.WriteLine($"Extraction failed ({ex.Kind}): {ex.Message}");
            break;
    }
}

The numbers behind UnhwpErrorKind are a stable ABI contract: a new reason takes the next free number and existing ones are never renumbered. Always keep a default branch so an unrecognised value degrades to a generic failure rather than going unhandled. Kind is Other for failures raised by the wrapper itself, and never None (which means success).

Features

• Fast: Native Rust library
• Complete: Extracts text, tables, images, and document structure
• Format Support: HWP 5.0, HWPX, and HWP 3.x (legacy)
• Trim and Native AOT compatible: no reflection-based serialization

API Reference

UnhwpDocument Class

Implements IDisposable; dispose it to release the native document.

Static Members

• ParseFile(string path) - Parse a document from a file path
• ParseBytes(byte[] data) - Parse a document from bytes
• Version - Library version

Instance Methods

• ToMarkdown(MarkdownOptions? options = null) - Convert to Markdown
• ToText() - Convert to plain text
• ToJson(bool compact = false) - Convert to JSON
• PlainText() - Get plain text (fast extraction)
• GetTables(bool tsv = false) - Every table as CSV (RFC 4180), or tab-separated, in reading order (IReadOnlyList<TableText>): Section, Index (its place in the section, from 1) and Text. A merged cell's text is in its top-left position and the positions it covers are empty, so every record has the same number of fields.
• GetResourceIds() - List of resource IDs
• GetResourceInfo(string id) - Resource metadata as JsonDocument, or null when absent
• GetResourceData(string id) - Resource binary data, or null when absent

Properties

• Title - Document title, or null
• Author - Document author, or null
• SectionCount - Number of sections
• ResourceCount - Number of resources

MarkdownOptions Class

• IncludeFrontmatter - Include YAML frontmatter with document metadata (default false)
• EscapeSpecialChars - Escape special Markdown characters (default true)
• ParagraphSpacing - Add extra spacing between paragraphs (default false)
• Refine - Apply the lossless Markdown shape-refinement pass after rendering (default false)

Platform Support

• Windows (x64)
• Linux (x64, glibc and musl)
• macOS (x64, ARM64)

Target Frameworks

• .NET 10.0

License

MIT License - see LICENSE for details.

Links

• GitHub Repository
• Rust Crate
• Python Package