hwpforge_core/
lib.rs

1//! HwpForge Core: format-independent Document Object Model.
2//!
3//! This crate defines the universal document structure used across
4//! all HwpForge format conversions. It is the **Anvil** in the Forge
5//! metaphor -- the surface on which all documents are shaped.
6//!
7//! # Architecture
8//!
9//! Core sits one layer above Foundation:
10//!
11//! ```text
12//! foundation (primitives: HwpUnit, Color, Index<T>)
13//!     |
14//!     v
15//! core (this crate: Document, Section, Paragraph, Run)
16//!     |
17//!     v
18//! blueprint (styles: CharShape, ParaShape, Template)
19//!     |
20//!     v
21//! smithy-* (format codecs: HWPX, HWP5, Markdown)
22//! ```
23//!
24//! Core has zero knowledge of XML, binary formats, or Markdown.
25//! It references style definitions by branded indices (Foundation's
26//! [`CharShapeIndex`](hwpforge_foundation::CharShapeIndex),
27//! [`ParaShapeIndex`](hwpforge_foundation::ParaShapeIndex)) without
28//! depending on Blueprint.
29//!
30//! # Document Lifecycle (Typestate)
31//!
32//! ```text
33//! Document<Draft>  --(validate)-->  Document<Validated>
34//!    (mutable)                         (immutable)
35//! ```
36//!
37//! - [`Draft`] documents can be modified (add sections, set metadata).
38//! - [`Validated`] documents are structurally sound and ready for export.
39//! - Deserialization always produces `Draft` (must re-validate).
40//!
41//! # DOM Hierarchy
42//!
43//! ```text
44//! Document
45//!   +-- Metadata
46//!   +-- Section[]
47//!         +-- PageSettings
48//!         +-- Paragraph[]
49//!               +-- Run[]
50//!                     +-- RunContent
51//!                           +-- Text(String)
52//!                           +-- Table(Box<Table>)
53//!                           +-- Image(Image)
54//!                           +-- Control(Box<Control>)
55//! ```
56//!
57//! # Examples
58//!
59//! ```
60//! use hwpforge_core::*;
61//! use hwpforge_core::run::Run;
62//! use hwpforge_core::section::Section;
63//! use hwpforge_core::paragraph::Paragraph;
64//! use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};
65//!
66//! let mut doc = Document::new();
67//! doc.add_section(Section::with_paragraphs(
68//!     vec![Paragraph::with_runs(
69//!         vec![Run::text("Hello, HwpForge!", CharShapeIndex::new(0))],
70//!         ParaShapeIndex::new(0),
71//!     )],
72//!     PageSettings::a4(),
73//! ));
74//!
75//! let validated = doc.validate().unwrap();
76//! assert_eq!(validated.section_count(), 1);
77//! ```
78
79#![deny(missing_docs)]
80#![deny(unsafe_code)]
81#![deny(clippy::all)]
82
83pub mod caption;
84pub mod chart;
85pub mod column;
86pub mod control;
87pub mod document;
88pub mod error;
89pub mod image;
90pub mod metadata;
91pub mod numbering;
92pub mod page;
93pub mod paragraph;
94pub mod run;
95pub mod section;
96pub mod tab;
97pub mod table;
98
99mod validate;
100
101// ---------------------------------------------------------------------------
102// Re-exports for convenience
103// ---------------------------------------------------------------------------
104
105pub use caption::{Caption, CaptionSide, DEFAULT_CAPTION_GAP};
106pub use chart::{ChartData, ChartGrouping, ChartSeries, ChartType, LegendPosition, XySeries};
107pub use column::{ColumnDef, ColumnLayoutMode, ColumnSettings, ColumnType};
108pub use control::{ArrowStyle, Control, Fill, LineStyle, ShapePoint, ShapeStyle};
109pub use document::{Document, Draft, Validated};
110pub use error::{CoreError, CoreErrorCode, CoreResult, ValidationError};
111pub use image::{Image, ImageFormat, ImageStore};
112pub use metadata::Metadata;
113pub use numbering::{NumberingDef, ParaHead};
114pub use page::PageSettings;
115pub use paragraph::Paragraph;
116pub use run::{Run, RunContent};
117pub use section::{
118    BeginNum, HeaderFooter, LineNumberShape, MasterPage, PageBorderFillEntry, PageNumber, Section,
119    Visibility,
120};
121pub use tab::TabDef;
122pub use table::{Table, TableCell, TableRow};
hwpforge_core/lib.rs

hwpforge_core/
lib.rs
