docx_rust/lib.rs
1//! A Rust library for parsing and generating docx files.
2//!
3//! # Create a new document
4//!
5//! Use `Docx::default` to create a new empty `Docx`, then use
6//! [`Docx::write_file`] for saving it to a file.
7//!
8//! [`Docx::write_file`]: struct.Docx.html#method.write_file
9//!
10//! ```no_run
11//! use docx_rust::document::Paragraph;
12//! use docx_rust::Docx;
13//!
14//! let mut docx = Docx::default();
15//!
16//! // create a new paragraph and insert it
17//! let para = Paragraph::default().push_text("Lorem Ipsum");
18//! docx.document.push(para);
19//!
20//! docx.write_file("demo.docx").unwrap();
21//! ```
22//!
23//! Also see: [`Docx::write`].
24//!
25//! [`Docx::write`]: struct.Docx.html#method.write
26//!
27//! # Reading from files
28//!
29//! Use [`DocxFile::from_file`] to extract content from docx files, then use
30//! [`DocxFile::parse`] to generate a `Docx` struct.
31//!
32//! [`DocxFile::from_file`]: struct.DocxFile.html#method.from_file
33//! [`DocxFile::parse`]: struct.DocxFile.html#method.parse
34//!
35//! ```no_run
36//! use docx_rust::document::Paragraph;
37//! use docx_rust::DocxFile;
38//!
39//! let docx = DocxFile::from_file("origin.docx").unwrap();
40//! let mut docx = docx.parse().unwrap();
41//!
42//! let para = Paragraph::default().push_text("Lorem Ipsum");
43//! docx.document.push(para);
44//!
45//! docx.write_file("origin_appended.docx").unwrap();
46//! ```
47//!
48//! To reduce allocations, `DocxFile::parse` returns a `Docx` struct contains
49//! references to `DocxFile` itself. It means you have to make sure that
50//! `DocxFile` lives as long as its returned `Docx`:
51//!
52//! ```compile_fail
53//! use docx_rust::DocxFile;
54//!
55//! let mut docx_option = None;
56//! {
57//! let docx_file = DocxFile::from_file("foo.docx").unwrap();
58//! let mut docx = docx_file.parse().unwrap();
59//! docx_option = Some(docx);
60//! // `docx_file` gets dropped here and code fails to compile
61//! }
62//! docx_option.unwrap().write_file("foo.docx").unwrap();
63//! ```
64//!
65//! Also see: [`DocxFile::from_reader`].
66//!
67//! [`DocxFile::from_reader`]: struct.DocxFile.html#method.from_reader
68//!
69//! # Similar Projects
70//!
71//! [`bokuweb/docx-rs`]: A .docx file writer with Rust/WebAssembly.
72//!
73//! [`bokuweb/docx-rs`]: https://github.com/bokuweb/docx-rs
74//!
75//! # License
76//!
77//! MIT
78//!
79
80mod macros;
81
82pub mod app;
83pub mod content_type;
84pub mod core;
85pub mod document;
86mod docx;
87mod error;
88pub mod font_table;
89pub mod formatting;
90pub mod media;
91pub mod rels;
92mod schema;
93pub mod settings;
94pub mod styles;
95pub mod web_settings;
96
97use std::io::Write;
98
99use hard_xml::{XmlWrite, XmlWriter};
100
101pub use crate::docx::{Docx, DocxFile};
102pub use crate::error::{DocxError, DocxResult};
103
104pub fn write_attr<W: Write, T: XmlWrite>(
105 element: &Option<T>,
106 writer: &mut XmlWriter<W>,
107) -> Result<(), hard_xml::XmlError> {
108 if let Some(e) = element {
109 e.to_writer(writer)?;
110 };
111 Ok(())
112}