mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-12 08:52:32 +00:00
Dylan M. Taylor
e3e31693c7
* Add craft-wordmodel: WordCraft's document model without its editing code WordCraft's crates/doc (wordcraft-doc, at 07f97737) moved as it is, so the DOCX, RTF, ODT and other text-format crates can read into and write from one model. Module paths, type names and serde attributes are unchanged: an app that re-exports the crate keeps its native file format. Left in the app: range editing (edit.rs), IME text and equation editing. Not model, and already in craft-libs: code pages (craft-rtf), the ZIP entry-count check (craft-opc), the compound-file guard (craft-cfb). The paragraph walks moved to walk.rs and the unit helpers of wordcraft-geom to geom.rs. * craft-wordmodel: math_tree, the arguments of an equation node and a walk over its runs The DOCX reader and writer walk an equation's runs. The walk and the child accessors it uses were in WordCraft's equation editor (math_edit.rs), which stays in the app; they are structure, not editing. * craft-wordmodel: keep the document operations (edit.rs) with the model The DOCX and RTF readers use them: alternative-format chunks are merged into a document with adopt_blocks, and a reader formats ranges with format_range and inserts objects. They operate on the document, not on a view, so they belong beside it. The tests that drove them come back with them; the paragraph walks stay in walk.rs and edit re-exports them. base64 0.23, as WordCraft and craft-offcrypto use. * craft-docx: WordCraft's crates/docx as it is at wordcraft 07f97737 The source, unchanged, so the next commit shows only what the move changes. This commit does not build on its own (it still names wordcraft-doc and wordcraft-geom, and is not a workspace member yet). * craft-docx: on craft-wordmodel, craft-opc, craft-xml and craft-offcrypto - The package (zip reading, part names, relationships, content types, zip writing) is craft-opc's; the module keeps WordCraft's bookkeeping (passthrough keys, the embedded-part manifest) and its own Rel/Rels shape. - Parts are parsed with craft-xml's canonical names (the Strict drawing names and mc:Choice/@Requires through its hooks), then given the tree shape the reader was written against. - Encryption and Restrict Editing hashes are craft-offcrypto's; this crate maps its errors and the w:documentProtection attributes. - wordcraft-doc is craft-wordmodel; wordcraft-geom's helpers are its geom. Tests that covered what now lives in craft-opc and craft-offcrypto are left to those crates; the DIFAT regression is craft-cfb's. Test-only zip use follows zip 9's fallible names. The attribute-cap test times the read only.
50 lines
2.0 KiB
Markdown
50 lines
2.0 KiB
Markdown
# craft-docx
|
|
|
|
DOCX (ECMA-376 / ISO/IEC 29500 WordprocessingML) read and written, on the `craft-wordmodel`
|
|
document model. Also Word XML Documents (Flat OPC, one `.xml` file holding the whole package)
|
|
and Word 2003 XML, password-protected packages and Restrict Editing password hashes.
|
|
|
|
It is WordCraft's DOCX crate, moved onto the shared crates: `craft-opc` for the package,
|
|
`craft-xml` for parsing, `craft-offcrypto` for encryption, `craft-wordmodel` for the model.
|
|
|
|
```rust
|
|
use craft_wordmodel::Document;
|
|
|
|
let doc = Document::from_text("Hello\nWorld");
|
|
let bytes = craft_docx::write(&doc).unwrap();
|
|
let back = craft_docx::read(&bytes).unwrap();
|
|
assert_eq!(back.plain_text(craft_wordmodel::StoryRef::Body), doc.plain_text(craft_wordmodel::StoryRef::Body));
|
|
```
|
|
|
|
## Reading
|
|
|
|
- `read(bytes)`, `read_with(bytes, &ReadOptions { password, chunks })`, `read_with_password`.
|
|
- `read_xml(bytes)`: a Word XML Document or a Word 2003 XML Document, told apart by its root.
|
|
- `package_title(reader, max_part)`: the title in `docProps/core.xml`, inflating only that part.
|
|
|
|
The reader is lenient (unknown markup is skipped, bad numbers fall back to defaults) and bounded:
|
|
|
|
| Limit | Value |
|
|
| --- | --- |
|
|
| ZIP entries | 20,000 (checked before the archive is indexed) |
|
|
| One part | 256 MiB |
|
|
| All parts | 512 MiB, counting entries that fail their checksum |
|
|
| XML nesting | 256 open elements |
|
|
| XML elements | 8,000,000 in one part |
|
|
| Attributes | 1,024 on one element |
|
|
| Word XML file | 1 GiB |
|
|
|
|
Markup the model does not hold is kept in `Document::passthrough` and the `kept` markup, and
|
|
written back as it was read.
|
|
|
|
## Writing
|
|
|
|
`write(doc)`, `write_as(doc, Flavor)` for `.docx`, `.docm`, `.dotx` and `.dotm`; `write_flat`
|
|
and `write_wordml2003` for the XML forms; `encrypt` for a password.
|
|
|
|
## Not here yet
|
|
|
|
- DrawingML (`a:`) shape fills, lines, custom geometry and colours are still read with this
|
|
crate's own code; they move to `craft-drawingml`.
|
|
- Equations (OMML) are read and written by this crate; they move to `craft-math`.
|