epub/lib.rs
1#![warn(clippy::pedantic, clippy::nursery)]
2#![allow(
3 clippy::module_name_repetitions,
4 clippy::let_underscore_drop,
5
6 // for MSRV
7 clippy::unnested_or_patterns,
8 clippy::uninlined_format_args,
9 clippy::missing_const_for_fn,
10)]
11
12//! EPUB library
13//! lib to read and navigate through an epub file contents
14//!
15//! # Examples
16//!
17//! ## Opening
18//!
19//! ```
20//! use epub::doc::EpubDoc;
21//! let doc = EpubDoc::new("test.epub");
22//! assert!(doc.is_ok());
23//! let doc = doc.unwrap();
24//!
25//! ```
26//!
27//! ## Getting doc metadata
28//!
29//! Metadata is a [`HashMap`](std::collections::HashMap) storing all metadata defined in the epub
30//!
31//! ```
32//! # use epub::doc::EpubDoc;
33//! # let doc = EpubDoc::new("test.epub");
34//! # let doc = doc.unwrap();
35//! let title = doc.mdata("title");
36//! assert_eq!(title.unwrap(), "Todo es mío");
37//! ```
38//!
39//! ## Accessing resources
40//!
41//! In the resources var is stored each resource defined
42//! in the epub indexed by the id and with the full internal
43//! path and mimetype. It's a `HashMap<a: String, (b: String, c: String)>`
44//! where `a` is the resource id, `b` is the resource full path and
45//! `c` is the resource mimetype
46//!
47//! ```
48//! # use epub::doc::EpubDoc;
49//! # use std::path::Path;
50//! # let doc = EpubDoc::new("test.epub");
51//! # let doc = doc.unwrap();
52//! assert_eq!(23, doc.resources.len());
53//! let tpage = doc.resources.get("titlepage.xhtml");
54//! assert_eq!(tpage.unwrap().0, Path::new("OEBPS/Text/titlepage.xhtml"));
55//! assert_eq!(tpage.unwrap().1, "application/xhtml+xml");
56//! ```
57//!
58//! ## Navigating using the spine
59//!
60//! Spine is a `Vec<String>` storing the epub spine as resources ids
61//!
62//! ```
63//! # use epub::doc::EpubDoc;
64//! # let doc = EpubDoc::new("test.epub");
65//! # let doc = doc.unwrap();
66//! assert_eq!(17, doc.spine.len());
67//! assert_eq!("titlepage.xhtml", doc.spine[0].idref);
68//! ```
69//!
70//! ## Navigation using the doc internal state
71//!
72//! ```
73//! use epub::doc::EpubDoc;
74//! let doc = EpubDoc::new("test.epub");
75//! let mut doc = doc.unwrap();
76//! assert_eq!(0, doc.get_current_page());
77//! assert_eq!("application/xhtml+xml", doc.get_current_mime().unwrap());
78//!
79//! doc.go_next();
80//! assert_eq!("000.xhtml", doc.get_current_id().unwrap());
81//! doc.go_next();
82//! assert_eq!("001.xhtml", doc.get_current_id().unwrap());
83//! doc.go_prev();
84//! assert_eq!("000.xhtml", doc.get_current_id().unwrap());
85//!
86//! doc.set_current_page(2);
87//! assert_eq!("001.xhtml", doc.get_current_id().unwrap());
88//! assert_eq!(2, doc.get_current_page());
89//! assert!(!doc.set_current_page(50));
90//!
91//! // doc.get_current() will return a Vec<u8> with the current page content
92//! // doc.get_current_str() will return a String with the current page content
93//! ```
94//!
95//! ## Getting the cover
96//!
97//! ```ignore
98//! use std::fs;
99//! use std::io::Write;
100//! use epub::doc::EpubDoc;
101//!
102//! let doc = EpubDoc::new("test.epub");
103//! assert!(doc.is_ok());
104//! let mut doc = doc.unwrap();
105//!
106//! let cover_data = doc.get_cover().unwrap();
107//!
108//! let f = fs::File::create("/tmp/cover.png");
109//! assert!(f.is_ok());
110//! let mut f = f.unwrap();
111//! let resp = f.write_all(&cover_data);
112//! ```
113
114mod xmlutils;
115
116pub mod archive;
117pub mod doc;