epub_builder/
epub_content.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with
3// this file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
5use crate::TocElement;
6
7use std::io::Read;
8
9/// Represents the possible reference type of an EPUB page.
10///
11/// Used by the guide section of EPUB 2.0 and the lankmarks navigation section
12/// for EPUB 3.0.
13///
14/// For more information, see http://www.idpf.org/epub/20/spec/OPF_2.0.1_draft.htm#Section2.3
15/// and https://idpf.github.io/epub-vocabs/structure/
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum ReferenceType {
18    /// The Book cover(s) (this refers to the cover PAGE, not the cover IMAGE)
19    Cover,
20    /// Page with title, author, publisher
21    TitlePage,
22    /// Table of contents
23    Toc,
24    /// Index
25    Index,
26    /// Glossary
27    Glossary,
28    /// Aknowledgements
29    Acknowledgements,
30    /// Bibliography
31    Bibliography,
32    /// No idea what this might be
33    Colophon,
34    /// Copyright page
35    Copyright,
36    /// Dedication
37    Dedication,
38    /// Epigraph
39    Epigraph,
40    /// Foreword
41    Foreword,
42    /// List of illustrations
43    Loi,
44    /// List of tables
45    Lot,
46    /// Notes
47    Notes,
48    /// Preface
49    Preface,
50    /// Beginning of the real content
51    Text,
52}
53
54/// Represents a XHTML file that can be added to an EPUB document.
55///
56/// This struct is designed to be used with the `add_content` method
57/// of the `[EpubBuilder](struct.EpubBuilder.html).
58///
59/// # Example
60///
61/// ```
62/// use epub_builder::{EpubContent, TocElement};
63///
64/// let page_content = "Some XHTML content";
65///
66/// // Creates a new EpubContent
67/// let content = EpubContent::new("intro.xhtml", page_content.as_bytes())
68/// // ... and sets a title so it is added to the TOC
69///     .title("Introduction")
70/// // ... and add some toc information on the document structure
71///     .child(TocElement::new("intro.xhtml#1", "Section 1"))
72///     .child(TocElement::new("intro.xhtml#2", "Section 2"));
73/// ```
74#[derive(Debug)]
75pub struct EpubContent<R: Read> {
76    /// The title and url, plus sublevels
77    pub toc: TocElement,
78    /// The content
79    pub content: R,
80    /// Properties. See [EpubProperties](enum.EpubProperties.html)
81    pub reftype: Option<ReferenceType>,
82}
83
84impl<R: Read> EpubContent<R> {
85    /// Creates a new EpubContent
86    ///
87    /// By default, this element is at level 1, and it has no title
88    /// (meaning it won't be added to the [`Table of Contents`](struct.Toc.html).
89    pub fn new<S: Into<String>>(href: S, content: R) -> Self {
90        EpubContent {
91            content,
92            toc: TocElement::new(href, ""),
93            reftype: None,
94        }
95    }
96
97    /// Set the title of this content. If no title is set,
98    /// this part of the book will not be displayed in the table of content.
99    pub fn title<S: Into<String>>(mut self, title: S) -> Self {
100        self.toc.title = title.into();
101        self
102    }
103
104    /// Set the raw title of this content. Only useful if you disable HTML escaping
105    /// and do it yourself.
106    ///
107    /// This raw title must contain no HTML tags but should still be escaped,
108    /// e.g. it can contain &lt; or &gt;, but you have to make sure you encode
109    /// all of this properly.
110    pub fn raw_title<S: Into<String>>(mut self, raw_title: S) -> Self {
111        self.toc.raw_title = Some(raw_title.into());
112        self
113    }
114
115    /// Set the level
116    pub fn level(mut self, level: i32) -> Self {
117        self.toc = self.toc.level(level);
118        self
119    }
120
121    /// Adds a sublevel to the toc
122    pub fn child(mut self, elem: TocElement) -> Self {
123        self.toc = self.toc.child(elem);
124        self
125    }
126
127    /// Sets reference type of this content
128    ///
129    /// If this is set, this will list this item as a reference in the guide section.
130    ///
131    /// See www.idpf.org/epub/20/spec/OPF_2.0.1_draft.htm#Section2.3
132    ///
133    /// # Example
134    ///
135    /// Reference an item as the title page:
136    ///
137    /// ```
138    /// use epub_builder::{EpubContent, ReferenceType};
139    /// let dummy = "Should be a XHTML file";
140    /// let item = EpubContent::new("title.xhtml", dummy.as_bytes())
141    ///      .title("Title")
142    ///      .reftype(ReferenceType::TitlePage);
143    /// ```
144    pub fn reftype(mut self, reftype: ReferenceType) -> Self {
145        self.reftype = Some(reftype);
146        self
147    }
148}
epub_builder/epub_content.rs

epub_builder/
epub_content.rs
