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 page layout the document's first master page points at.
43    ///
44    /// A text document has one master page per page style, and the first is the
45    /// one the body starts on. Where there is none, or no `styles.xml` at all,
46    /// the default of [`PageLayout`] applies.
47    pub fn page_layout(&self) -> PageLayout {
48        let master = self
49            .document
50            .styles_part
51            .as_ref()
52            .and_then(|styles| styles.child(&Ns::Office, "master-styles"))
53            .and_then(|masters| masters.child(&Ns::Style, "master-page"))
54            .and_then(|master| master.attr(&Ns::Style, "name"));
55        master
56            .and_then(|name| self.document.styles.page_layout_of(name))
57            .cloned()
58            .unwrap_or_default()
59    }
60
61    /// The width a line of body text may be: the page less its side margins.
62    pub fn text_width(&self) -> f32 {
63        let layout = self.page_layout();
64        let left = layout
65            .margin
66            .left
67            .map_or(0.0, super::super::value::Length::points);
68        let right = layout
69            .margin
70            .right
71            .map_or(0.0, super::super::value::Length::points);
72        (layout.width.points() - left - right).max(1.0)
73    }
74
75    /// The document's headings, as an outline for navigating it: each heading's
76    /// level, its text, and its position among the body's children.
77    ///
78    /// Only the top level of the body is walked. A heading inside a table cell or
79    /// a frame is not a heading in the outline — ODF permits one and no
80    /// application lists it — and a heading inside a section is, which is why
81    /// sections are descended into.
82    pub fn outline(&self) -> Vec<Heading> {
83        let mut headings = Vec::new();
84        if let Some(body) = self.body() {
85            collect_headings(body, &mut headings);
86        }
87        headings
88    }
89
90    /// The style a block element asks for, resolved.
91    ///
92    /// The family is the one the element belongs to, which for everything in a
93    /// text flow is [`Family::Paragraph`] except a table and its parts.
94    pub fn paragraph_style(&self, element: &Element) -> std::rc::Rc<crate::Properties> {
95        let name = element.attr(&Ns::Text, "style-name").unwrap_or("Standard");
96        self.document.styles.resolve(&Family::Paragraph, name)
97    }
98}
99
100/// One entry of a document's outline.
101pub struct Heading {
102    /// `text:outline-level`, where 1 is the top. A heading with no level
103    /// declared is level 1, which is what ODF says.
104    pub level: u8,
105    /// The heading's text, with ODF's whitespace elements resolved.
106    pub text: String,
107}
108
109fn collect_headings(parent: &Element, into: &mut Vec<Heading>) {
110    for element in parent.elements() {
111        if element.is(&Ns::Text, "h") {
112            let level = element
113                .attr_usize(&Ns::Text, "outline-level")
114                .unwrap_or(1)
115                .clamp(1, 10);
116            #[allow(clippy::cast_possible_truncation)]
117            into.push(Heading {
118                level: level as u8,
119                text: element.plain_text(),
120            });
121        } else if element.is(&Ns::Text, "section") {
122            collect_headings(element, into);
123        }
124    }
125}
odox_core/doc/text.rs

odox_core/doc/
text.rs
