easydoc-core

Core types, traits, and error model for the easydoc-rust DOC/DOCX document operations workspace.

English | 简体中文

Positioning · Traits · Data Model · Errors · Features · Upstream · License

Status: alpha pre-release (latest on crates.io) MSRV: Rust 1.88 Edition: 2024 Maturity: Alpha Last verified: 2026-08-11

1. Project Positioning & Status

1.1 What It Is

easydoc-core is the foundation crate of the easydoc-rust workspace. It defines the 6 extension traits, the semantic document data model, the unified error type, and the style/metadata primitives that all other crates depend on.

1.2 What It Is Not

• Not a DOCX parser or generator -- those live in easydoc-reader and easydoc-writer.
• Not the user-facing entry point -- use easydoc (the facade crate) for that.
• Not coupled to any specific backend (docx-rs, office_oxide, etc.).

1.3 Status Evidence

2. Extension Traits

The 6 extension traits form the backbone of easydoc-rust extensibility. They correspond to the extension points in Java EasyExcel 4.0.3.

2.1 DocxRow

Maps a Rust struct to/from DOCX table rows. Typically implemented via #[derive(DocxRow)] from easydoc-derive.

#[derive(DocxRow)]
struct User {
    #[docx(name = "Name", order = 0)]
    name: String,
    #[docx(name = "Age", order = 1)]
    age: u32,
}

Methods: schema(), from_row(), from_row_with_converters(), to_row(), to_row_with_converters().

2.2 DocConverter<T>

Bidirectional conversion between a Rust type T and DocValue. Registered via ConverterRegistry or builder's register_converter.

impl DocConverter<String> for MyConverter {
    fn support_type() -> TypeId { TypeId::of::<String>() }
    fn to_doc_value(&self, value: &String, col: &TableColumn) -> Result<DocValue> { ... }
    fn from_doc_value(&self, value: &DocValue, col: &TableColumn) -> Result<String> { ... }
}

2.3 DocReadListener<T>

Receives parsed content during streaming read. Methods: invoke(), invoke_table(), on_complete(), on_error(), has_next().

2.4 DocWriteHandler

Write lifecycle interceptor at document, paragraph, table, and cell levels. All methods have empty default implementations. Methods: order(), before_document(), after_document(), before_paragraph(), after_paragraph(), before_table(), after_table(), before_cell(), after_cell().

2.5 DocumentReader

Backend-agnostic read interface. Implementations provide read_model() and read_events(). No direct Java equivalent -- this is an easydoc-rust original abstraction.

2.6 EventSink

Consumes DocumentEvent instances during SAX streaming. The built-in ContentCollector implementation collects events into DocumentContent.

Event types: DocumentStart, Heading, Paragraph, Table, List, Image, PageBreak, ColumnBreak, CodeBlock, Section, DocumentEnd.

3. Data Model

The semantic document model is backend-independent -- it has no direct Java EasyExcel equivalent (Java EasyExcel does not process DOCX).

3.1 Model Hierarchy

DocumentContent
├── metadata: DocumentMeta (title, author, ...)
└── blocks: Vec<DocumentBlock>
    ├── Heading { level, runs }
    ├── Paragraph(runs)
    ├── Table(DocumentTable)
    │   └── rows: Vec<DocumentTableRow>
    │       └── cells: Vec<DocumentTableCell>
    │           └── blocks: Vec<DocumentBlock>
    ├── List(DocumentList)
    │   └── items: Vec<DocumentListItem>
    ├── Image(DocumentImage)
    ├── CodeBlock { language, code }
    ├── TextBox(blocks)
    ├── Footnote { id, blocks }
    ├── Endnote { id, blocks }
    ├── Section { blocks, section_type }
    ├── Math { latex, display }
    ├── ThematicBreak
    ├── PageBreak
    └── ColumnBreak

3.2 Key Types

3.3 Data Types (DocValue)

DocValue is the universal value enum bridging Rust types and DOCX content.

From implementations are provided for String, &str, bool, i32, u32, i64, f64, DateTime<Utc>, NaiveDate, NaiveDateTime, and Option<T>.

3.4 Supporting Types

4. Error Model

All operations return easydoc_core::Result<T> (alias for Result<T, DocError>).

Java EasyExcel spreads errors across 7 RuntimeException subclasses; easydoc-core unifies them into a single idiomatic Rust enum.

5. Cargo Features

# Minimal (no serde)
[dependencies]
easydoc-core = "0.1.0-alpha"

# With serde support
easydoc-core = { version = "0.1.0-alpha", features = ["serde"] }

6. Upstream Compatibility

easydoc-core maps its trait system to Java EasyExcel 4.0.3 extension points.

6.1 Trait Mapping

6.2 Language Semantic Mapping

7. Build & Test

cargo check -p easydoc-core
cargo test -p easydoc-core
cargo test -p easydoc-core --features serde
cargo clippy -p easydoc-core -- -D warnings
cargo doc -p easydoc-core --no-deps

8. License

Apache-2.0 -- see LICENSE for details.

Back to top · docs.rs · crates.io · Issues