# litchi

**Repository Path**: zh217/litchi

## Basic Information

- **Project Name**: litchi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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](mailto:ryker.zhu@outlook.com).

## 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

```rust
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

```rust
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

```rust
// 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`:

```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:

```toml
[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](https://docs.rs/litchi)** - Complete API documentation
- **[OFFICE_API_GUIDE.md](docs/OFFICE_API_GUIDE.md)** - Comprehensive guide with examples
- **[FEATURE_MATRIX.md](docs/FEATURE_MATRIX.md)** - Feature comparison with Apache POI
- **[Examples](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](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](https://poi.apache.org/) - Java library for Microsoft Office formats
- [python-docx](https://github.com/python-openxml/python-docx) - Python library for DOCX files
- [python-pptx](https://github.com/scanny/python-pptx) - Python library for PPTX files
- [openpyxl](https://openpyxl.readthedocs.io/) - Python library for XLSX files
- [calamine](https://github.com/tafia/calamine) - Rust Excel/ODS reader
- [pyxlsb2](https://github.com/willtrnr/pyxlsb) - Python XLSB parser
- [xlrd](https://github.com/python-excel/xlrd) - Python library for reading Excel files

**OpenDocument Formats:**
- [odfpy](https://github.com/eea/odfpy) - Python API for OpenDocument files
- [odfdo](https://github.com/jdum/odfdo) - Modern Python library for ODF

**Apple iWork Formats:**
- [libetonyek](https://github.com/LibreOffice/libetonyek) - Library for Apple Keynote presentations
- [iWorkFileFormat](https://github.com/obriensp/iWorkFileFormat) - iWork file format documentation
- [pyiwa](https://github.com/masaccio/pyiwa) - Python iWork Archive parser

**RTF Formats:**
- [rtf2latex2e](https://github.com/wilfriedh/rtf2latex2e) - RTF to LaTeX converter
- [RtfDomParser](https://github.com/elistevens/RtfDomParser) - RTF parser

**Formula Conversion:**
- [plurimath](https://github.com/plurimath/plurimath) - Multi-format mathematical formula converter

**Image Conversion:**
- [libemf2svg](https://github.com/kakwa/libemf2svg) - EMF/WMF to SVG conversion
- [libwmf](https://github.com/caolanm/libwmf) - Windows Metafile library
- [pict2png](https://github.com/0x00000FF/pict2png) - PICT to PNG conversion

**Utilities:**
- [file](https://github.com/file/file) - File type identification (libmagic)
- [calibre](https://github.com/kovidgoyal/calibre) - E-book management and format documentation

**Specifications:**
- [Microsoft Office File Format Documentation](https://docs.microsoft.com/en-us/openspecs/office_file_formats/)

All projects retain their original licenses.