office_toolkit/

lib.rs

//! `office-toolkit` — facade crate for the toolkit.
//!
//! Single entry point re-exporting the public API of the format-specific crates, each behind its
//! own same-named Cargo feature — but all three enabled by `full`, which is also this crate's own
//! default. A plain `cargo add office-toolkit` compiles and works with zero configuration; the
//! features exist for anyone who wants to opt out of formats they don't use (smaller binary, faster
//! build), never as a requirement to get started. Simplicity for the common case was chosen
//! deliberately over "pay only for what you use by default".
//!
//! # Module layout
//!
//! - [`word`] — everything from `word_ooxml`, when the `word` feature is enabled (on by default).
//! - [`excel`] — everything from `excel_ooxml`, when the `excel` feature is enabled (on by
//!   default).
//! - [`powerpoint`] — everything from `powerpoint_ooxml`, when the `powerpoint` feature is enabled
//!   (on by default).
//! - [`drawing`]/[`chart`] — the two crates shared across all three formats (shape/text
//!   formatting, embedded charts respectively) — always available, unconditionally, since every
//!   format needs them to add an image, a shape, or a chart.
//! - [`prelude`] — the handful of types used constantly regardless of format
//!   (`Document`/`Workbook`/`Presentation`, each format's most basic content-building type —
//!   `Paragraph`/`Row`/`Slide` — plus the most common `drawing` types), re-exported unprefixed, so
//!   `use office_toolkit::prelude::*;` alone is enough to start writing code.
//!
//! Everything deeper stays in its own namespaced module above — that namespacing isn't optional
//! there: several types (`DocumentProperties`, `Theme`, `ColorScheme`, `CustomPropertyValue`)
//! intentionally share the same name across two or three formats (kept consistent between them on
//! purpose), so re-exporting all of them flat at this crate's root would collide.
//!
//! [`open`] auto-detects a `.docx`/`.xlsx`/`.pptx` file's format from the package's own content
//! (not the file's name or extension) and returns a single [`OfficeDocument`];
//! [`OpenFile`]/[`SaveToFile`] add `open_file`/`save_to_file` methods directly on
//! `Document`/`Workbook`/`Presentation` for the more common case where the caller already knows
//! which format they're working with.
//!
//! # Example
//!
//! ```no_run
//! use office_toolkit::prelude::*;
//! use office_toolkit::SaveToFile;
//!
//! # fn main() -> office_toolkit::Result<()> {
//! // Build a minimal Word document and save it — `Document` and `Paragraph` both come straight
//! // from the prelude. `save_to_file` comes from the `SaveToFile` trait (see [`SaveToFile`]) —
//! // it has to be imported explicitly like any trait method, the prelude only covers types, not
//! // traits.
//! let document = Document::new().with_paragraph(Paragraph::with_text("Hello, world!"));
//! document.save_to_file("hello.docx")?;
//!
//! // Open any .docx/.xlsx/.pptx without knowing its format ahead of time.
//! let opened = office_toolkit::open("hello.docx")?;
//! opened.save_to_file("hello-resaved.docx")?;
//! # Ok(())
//! # }
//! ```

#[cfg(feature = "word")]
pub mod word {
    //! Everything from `word_ooxml` — reading and writing `.docx`.
    pub use word_ooxml::*;
}

#[cfg(feature = "excel")]
pub mod excel {
    //! Everything from `excel_ooxml` — reading and writing `.xlsx`.
    pub use excel_ooxml::*;
}

#[cfg(feature = "powerpoint")]
pub mod powerpoint {
    //! Everything from `powerpoint_ooxml` — reading and writing `.pptx`.
    pub use powerpoint_ooxml::*;
}

pub mod drawing {
    //! Everything from the `drawing` crate — shape/text formatting shared by every format (fill,
    //! line, geometry, text body...). Always available: unlike `word`/`excel`/`powerpoint`, not
    //! gated by a feature, since it has no meaningful "opt out" — any format that has images or
    //! shapes at all needs it.
    pub use ::drawing::*;
}

pub mod chart {
    //! Everything from the `chart` crate — embedded charts, shared by every format. Always
    //! available, same reasoning as [`crate::drawing`].
    pub use ::chart::*;
}

pub mod prelude {
    //! The handful of types needed to get started with any format, re-exported unprefixed. See the
    //! crate-level doc comment for why only these (and not the rest of the API) live here.
    //!
    //! Alongside each format's entry point, its single most basic content-building type is included
    //! too (`Paragraph` for Word, `Row` for Excel, `Slide` for PowerPoint) — without at least one
    //! of these, `prelude::*` alone can't build so much as a "Hello, world!" file, which defeats
    //! the point of a prelude. `Cell` (Excel) is included too: `Sheet::write_cell` accepts a raw
    //! `&str`/`f64`/`bool` directly for the common cases, but reading a workbook back, or writing a
    //! formula/date/rich-text cell, still means naming `Cell`/`CellValue` explicitly. None of these
    //! collide with anything else re-exported here or in another format's own module.

    #[cfg(feature = "excel")]
    pub use excel_ooxml::{Cell, Row, Workbook};
    #[cfg(feature = "powerpoint")]
    pub use powerpoint_ooxml::{Presentation, Slide};
    #[cfg(feature = "word")]
    pub use word_ooxml::{Document, Paragraph};

    pub use ::drawing::{Color, Fill, ShapeProperties, Transform2D};
}

mod document;
mod error;

pub use document::{OfficeDocument, OpenFile, SaveToFile, open};
pub use error::{Error, Result};