odox_core/doc/
text.rs

1//! A text document: `.odt`.
2//
3// Author: David M. Anderson
4// Built with AI assistance (Claude, Anthropic)
5
6use super::Document;
7use crate::media_type;
8use crate::style::PageLayout;
9use crate::xml::{Element, Ns};
10use crate::{Error, Family};
11
12/// An `OpenDocument` text document.
13///
14/// The body is a flow of block elements — paragraphs, headings, lists, tables,
15/// sections, frames — in the order they are read, which is the order they are
16/// drawn. Nothing here paginates: a page layout says how wide a line may be, and
17/// that is what [`Self::page_layout`] is for.
18pub struct TextDocument {
19    /// The package and everything shared with the other two formats.
20    pub document: Document,
21}
22
23impl TextDocument {
24    /// Read a `.odt` package.
25    ///
26    /// # Errors
27    ///
28    /// The bytes are not a text document, or its `content.xml` cannot be read.
29    pub fn read(bytes: &[u8]) -> Result<Self, Error> {
30        let document = Document::read(bytes, media_type::TEXT_ANY)?;
31        Ok(Self { document })
32    }
33
34    /// The `office:text` element: the flow.
35    ///
36    /// `None` for a package that declares itself a text document and carries no
37    /// text body, which is a broken document rather than an empty one.
38    pub fn body(&self) -> Option<&Element> {
39        self.document.body_of("text")
40    }
41
42    /// The same, for changing it.
43    pub fn body_mut(&mut self) -> Option<&mut Element> {
44        self.document
45            .content
46            .child_mut(&Ns::Office, "body")?
47            .child_mut(&Ns::Office, "text")
48    }
49
50    /// The page layout the document's first master page points at.
51    ///
52    /// A text document has one master page per page style, and the first is the
53    /// one the body starts on. Where there is none, or no `styles.xml` at all,
54    /// the default of [`PageLayout`] applies.
55    pub fn page_layout(&self) -> PageLayout {
56        let master = self
57            .document
58            .styles_part
59            .as_ref()
60            .and_then(|styles| styles.child(&Ns::Office, "master-styles"))
61            .and_then(|masters| masters.child(&Ns::Style, "master-page"))
62            .and_then(|master| master.attr(&Ns::Style, "name"));
63        master
64            .and_then(|name| self.document.styles.page_layout_of(name))
65            .cloned()
66            .unwrap_or_default()
67    }
68
69    /// The width a line of body text may be: the page less its side margins.
70    pub fn text_width(&self) -> f32 {
71        let layout = self.page_layout();
72        let left = layout
73            .margin
74            .left
75            .map_or(0.0, super::super::value::Length::points);
76        let right = layout
77            .margin
78            .right
79            .map_or(0.0, super::super::value::Length::points);
80        (layout.width.points() - left - right).max(1.0)
81    }
82
83    /// The document's headings, as an outline for navigating it: each heading's
84    /// level, its text, and its position among the body's children.
85    ///
86    /// Only the top level of the body is walked. A heading inside a table cell or
87    /// a frame is not a heading in the outline — ODF permits one and no
88    /// application lists it — and a heading inside a section is, which is why
89    /// sections are descended into.
90    pub fn outline(&self) -> Vec<Heading> {
91        let mut headings = Vec::new();
92        if let Some(body) = self.body() {
93            collect_headings(body, &mut headings);
94        }
95        headings
96    }
97
98    /// The style a block element asks for, resolved.
99    ///
100    /// The family is the one the element belongs to, which for everything in a
101    /// text flow is [`Family::Paragraph`] except a table and its parts.
102    pub fn paragraph_style(&self, element: &Element) -> std::rc::Rc<crate::Properties> {
103        let name = element.attr(&Ns::Text, "style-name").unwrap_or("Standard");
104        self.document.styles.resolve(&Family::Paragraph, name)
105    }
106}
107
108/// One entry of a document's outline.
109pub struct Heading {
110    /// `text:outline-level`, where 1 is the top. A heading with no level
111    /// declared is level 1, which is what ODF says.
112    pub level: u8,
113    /// The heading's text, with ODF's whitespace elements resolved.
114    pub text: String,
115}
116
117fn collect_headings(parent: &Element, into: &mut Vec<Heading>) {
118    for element in parent.elements() {
119        if element.is(&Ns::Text, "h") {
120            let level = element
121                .attr_usize(&Ns::Text, "outline-level")
122                .unwrap_or(1)
123                .clamp(1, 10);
124            #[allow(clippy::cast_possible_truncation)]
125            into.push(Heading {
126                level: level as u8,
127                text: element.plain_text(),
128            });
129        } else if element.is(&Ns::Text, "section") {
130            collect_headings(element, into);
131        }
132    }
133}
odox_core/doc/text.rs

odox_core/doc/
text.rs
