Litchi

<p align="center"> <img src="media/litchi_logo.png" alt="Litchi Logo" width="200"/> </p>

A high-performance Rust library for parsing Microsoft Office file formats (OLE2 and OOXML), OpenDocument formats (ODF), and Apple iWork files. Supports .doc, .docx, .xls, .xlsx, .ppt, .pptx, .odt, .ods, .odp, .pages, .numbers, and .key files.

[!WARNING] ⚠️ Active Development: This library is under active development. The API may change without notice. Not recommended for production use yet.

[!NOTE] The current logo is generated by AI, we need someone to design a better logo. If you are interested, please contact me via email.

Features

• Complete CRUD Operations - Create, read, update, and save Office documents (.docx, .xlsx, .pptx)
• Unified API - Same interface for legacy and modern formats with automatic format detection
• Microsoft Office - Full support for .doc, .docx, .xls, .xlsx, .xlsb, .ppt, .pptx files
• OpenDocument - Parse .odt, .ods, .odp files (ODF format)
• Apple iWork - Parse .pages, .numbers, .key files (IWA format)
• Formula Conversion - Parse MathType and Office MathML equations and convert to LaTeX
• Markdown Conversion - Convert documents and presentations to Markdown format
• Memory Efficient - Direct byte buffer support with zero-copy parsing where possible
• High Performance - SIMD optimizations, minimal allocations, efficient memory layout

Quick Start

Reading Documents

use litchi::{Document, Presentation};

// Microsoft Office formats - format auto-detected
let doc = Document::open("document.doc")?;  // .doc or .docx
let text = doc.text()?;

let pres = Presentation::open("slides.ppt")?;  // .ppt or .pptx
let slide_count = pres.slide_count()?;

// Excel spreadsheets
use litchi::sheet::open_xls_workbook;
let workbook = open_xls_workbook("spreadsheet.xls")?;
let worksheet = workbook.worksheet_by_name("Sheet1")?;

Creating and Writing Documents

use litchi::ooxml::docx::Package;
use litchi::ooxml::xlsx::Workbook;
use litchi::ooxml::pptx::Package as PptxPackage;

// Create Word document
let mut pkg = Package::new()?;
let doc = pkg.document_mut()?;
doc.add_heading("My Document", 1)?;
doc.add_paragraph_with_text("Hello, World!");
pkg.save("output.docx")?;

// Create Excel workbook
let mut wb = Workbook::create()?;
let ws = wb.worksheet_mut(0)?;
ws.set_cell_value(1, 1, "Hello");
ws.set_cell_value(1, 2, "World");
wb.save("output.xlsx")?;

// Create PowerPoint presentation
let mut pkg = PptxPackage::new()?;
let pres = pkg.presentation_mut()?;
let slide = pres.add_slide()?;
slide.set_title("My Presentation");
pkg.save("output.pptx")?;

Additional Format Support

// OpenDocument formats (requires "odf" feature)
#[cfg(feature = "odf")]
{
    use litchi::odf;
    let odt = odf::Document::open("document.odt")?;
    let text = odt.text()?;
}

// Apple iWork formats (requires "iwa" feature)
#[cfg(feature = "iwa")]
{
    use litchi::iwa;
    let pages = iwa::Document::open("document.pages")?;
    let text = pages.text()?;
}

// Formula conversion (requires "formula" feature)
#[cfg(feature = "formula")]
{
    use litchi::formula;
    let latex = formula::mathml_to_latex("<math>...</math>")?;
}

Installation

[!NOTE] The library on the crates.io is just a placeholder right now (contains only read-only functionalities), if you want to use it, please use the development version.

Add to your Cargo.toml:

[dependencies]
litchi = "0.0.1"

# Or use the development version
litchi = { git = "https://github.com/DevExzh/litchi.git" }

Optional Features

By default, Microsoft Office format support is enabled (ole, ooxml), along with ooxml_encryption and eval_engine. Enable additional features as needed:

[dependencies]
# Enable all features
litchi = { version = "0.0.1", features = ["full"] }

# Or enable specific features
litchi = { version = "0.0.1", features = ["odf"] }  # OpenDocument support
litchi = { version = "0.0.1", features = ["iwa"] }  # Apple iWork support
litchi = { version = "0.0.1", features = ["rtf"] }  # RTF support
litchi = { version = "0.0.1", features = ["formula"] }  # Formula parsing and LaTeX conversion
litchi = { version = "0.0.1", features = ["imgconv"] }  # Image conversion support

Note about iwa: iWork files are essentially bundles of serialized Protocol Buffer messages, so enabling iwa requires a system protoc installation (used by prost-build).

• Linux (Debian/Ubuntu): install protobuf-compiler
• macOS: install protobuf (e.g. via Homebrew)
• Windows: install protobuf (e.g. via Winget)

Note about fonts: Font embedding depends on font-kit, so enabling it requires a system fontconfig installation (used by font-kit).

• Linux (Debian/Ubuntu): install pkg-config libfreetype6-dev libfontconfig1-dev

Available Features:

• full - Enable all supported formats and functionality
• ole (default) - Legacy Office formats (.doc, .xls, .ppt)
• ooxml (default) - Modern Office formats (.docx, .xlsx, .pptx)
• ooxml_encryption (default) - OOXML encryption/decryption support
• odf - OpenDocument formats (.odt, .ods, .odp)
• iwa - Apple iWork formats (.pages, .numbers, .key)
• rtf - Rich Text Format (.rtf)
• fonts - Font embedding support
• formula - MathType and Office MathML to LaTeX conversion
• imgconv - Image format conversion (EMF, WMF, PICT to PNG/JPEG/WebP)
• eval_engine (default) - Spreadsheet formula evaluation engine

Documentation

• API Reference - Complete API documentation
• OFFICE_API_GUIDE.md - Comprehensive guide with examples
• FEATURE_MATRIX.md - Feature comparison with Apache POI
• Examples - Working code examples:
  • office_crud_demo.rs - Complete CRUD operations demo

Current Status

Fully Implemented:

• ✅ CRUD Operations - Create, read, and update .docx, .xlsx, .pptx files
• ✅ Reading - Full support for .doc, .docx, .xls, .xlsx, .xlsb, .ppt, .pptx
• ✅ Writing - Document creation and modification for OOXML formats
• ✅ Text & Formatting - Paragraphs, runs, tables, cells, basic styling
• ✅ OpenDocument - Read .odt, .ods, .odp files
• ✅ Apple iWork - Read .pages, .numbers, .key files
• ✅ Formula Parsing - MathType and MathML to LaTeX conversion
• ✅ Markdown Export - Convert documents and presentations to Markdown

In Progress:

• 🟡 Advanced formatting (cell styles, conditional formatting)
• 🟡 Charts and embedded objects
• 🟡 Headers, footers, comments
• 🟡 Document protection and security features

See docs/FEATURE_MATRIX.md for a detailed feature comparison with Apache POI.

License

Licensed under the Apache License, Version 2.0.

Acknowledgments

This library is built upon the work of many open-source projects. We are grateful to the following projects for their research, documentation, and reference implementations:

Microsoft Office Formats:

• Apache POI - Java library for Microsoft Office formats
• python-docx - Python library for DOCX files
• python-pptx - Python library for PPTX files
• openpyxl - Python library for XLSX files
• calamine - Rust Excel/ODS reader
• pyxlsb2 - Python XLSB parser
• xlrd - Python library for reading Excel files

OpenDocument Formats:

• odfpy - Python API for OpenDocument files
• odfdo - Modern Python library for ODF

Apple iWork Formats:

• libetonyek - Library for Apple Keynote presentations
• iWorkFileFormat - iWork file format documentation
• pyiwa - Python iWork Archive parser

RTF Formats:

• rtf2latex2e - RTF to LaTeX converter
• RtfDomParser - RTF parser

Formula Conversion:

• plurimath - Multi-format mathematical formula converter

Image Conversion:

• libemf2svg - EMF/WMF to SVG conversion
• libwmf - Windows Metafile library
• pict2png - PICT to PNG conversion

Utilities:

• file - File type identification (libmagic)
• calibre - E-book management and format documentation

Specifications:

• Microsoft Office File Format Documentation

All projects retain their original licenses.