epub::doc

Struct EpubDoc

pub struct EpubDoc<R: Read + Seek> {
    pub version: EpubVersion,
    pub spine: Vec<SpineItem>,
    pub resources: HashMap<String, (PathBuf, String)>,
    pub toc: Vec<NavPoint>,
    pub toc_title: String,
    pub metadata: HashMap<String, Vec<String>>,
    pub root_base: PathBuf,
    pub root_file: PathBuf,
    pub extra_css: Vec<String>,
    pub unique_identifier: Option<String>,
    pub cover_id: Option<String>,
    /* private fields */
}

Expand description

Struct to control the epub document

Fields§

§version: EpubVersion

epub spec version

§spine: Vec<SpineItem>

epub spine ids

§resources: HashMap<String, (PathBuf, String)>

resource id -> (path, mime)

§toc: Vec<NavPoint>

table of content, list of NavPoint in the toc.ncx

§toc_title: String

title of toc

§metadata: HashMap<String, Vec<String>>

The epub metadata stored as key -> value

§Examples

let title = doc.metadata.get("title");
assert_eq!(title.unwrap(), &vec!["Todo es mío".to_string()]);

§root_base: PathBuf

root file base path

§root_file: PathBuf

root file full path

§extra_css: Vec<String>

Custom css list to inject in every xhtml file

§unique_identifier: Option<String>

unique identifier

§cover_id: Option<String>

The id of the cover, if any

Implementations§

Source §

impl EpubDoc<BufReader<File>>

Source

pub fn new<P: AsRef<Path>>(path: P) -> Result<Self, DocError>

Opens the epub file in path.

Initialize some internal variables to be able to access to the epub spine definition and to navigate through the epub.

§Examples

use epub::doc::EpubDoc;

let doc = EpubDoc::new("test.epub");
assert!(doc.is_ok());

§Errors

Returns an error if the epub is broken or if the file doesn’t exists.

Source §

impl<R: Read + Seek> EpubDoc<R>

Source

pub fn from_reader(reader: R) -> Result<Self, DocError>

Opens the epub contained in reader.

Initialize some internal variables to be able to access to the epub spine definition and to navigate through the epub.

§Examples

use epub::doc::EpubDoc;
use std::fs::File;
use std::io::{Cursor, Read};

let mut file = File::open("test.epub").unwrap();
let mut buffer = Vec::new();
file.read_to_end(&mut buffer).unwrap();

let cursor = Cursor::new(buffer);

let doc = EpubDoc::from_reader(cursor);
assert!(doc.is_ok());

§Errors

Returns an error if the epub is broken.

Source

pub fn mdata(&self, name: &str) -> Option<String>

Returns the first metadata found with this name.

§Examples

let title = doc.mdata("title");
assert_eq!(title.unwrap(), "Todo es mío");

Source

pub fn get_cover_id(&self) -> Option<String>

Returns the id of the epub cover.

The cover is searched in the doc metadata, by the tag <meta name="cover" value"..">

§Examples

use epub::doc::EpubDoc;

let doc = EpubDoc::new("test.epub");
assert!(doc.is_ok());
let mut doc = doc.unwrap();

let cover_id = doc.get_cover_id();

This returns the cover id, which can be used to get the cover data. The id is not guaranteed to be valid.

Source

pub fn get_cover(&mut self) -> Option<(Vec<u8>, String)>

Returns the cover’s content and mime-type

§Examples

use std::fs;
use std::io::Write;
use epub::doc::EpubDoc;

let doc = EpubDoc::new("test.epub");
assert!(doc.is_ok());
let mut doc = doc.unwrap();

let cover_data = doc.get_cover().unwrap();

let f = fs::File::create("/tmp/cover.png");
assert!(f.is_ok());
let mut f = f.unwrap();
let resp = f.write_all(&cover_data);

Returns None if the cover can’t be found.

Source

pub fn get_release_identifier(&self) -> Option<String>

Returns Release Identifier defined at https://www.w3.org/publishing/epub32/epub-packages.html#sec-metadata-elem-identifiers-pid

Source

pub fn get_resource_by_path<P: AsRef<Path>>( &mut self, path: P, ) -> Option<Vec<u8>>

Returns the resource content by full path in the epub archive

Returns None if the path doesn’t exist in the epub

Source

pub fn get_resource(&mut self, id: &str) -> Option<(Vec<u8>, String)>

Returns the resource content and mime-type by the id defined in the spine

Returns None if the id doesn’t exists in the epub

Source

pub fn get_resource_str_by_path<P: AsRef<Path>>( &mut self, path: P, ) -> Option<String>

Returns the resource content by full path in the epub archive, as String

Returns None if the path doesn’t exists in the epub

Source

pub fn get_resource_str(&mut self, id: &str) -> Option<(String, String)>

Returns the resource content and mime-type by the id defined in the spine, as String

Returns None if the id doesn’t exists in the epub

Source

pub fn get_resource_mime(&self, id: &str) -> Option<String>

Returns the resource mime-type

§Examples

let mime = doc.get_resource_mime("portada.png");
assert_eq!("image/png", mime.unwrap());

Returns None the resource can’t be found.

Source

pub fn get_resource_mime_by_path<P: AsRef<Path>>( &self, path: P, ) -> Option<String>

Returns the resource mime searching by source full path

§Examples

let mime = doc.get_resource_mime_by_path("OEBPS/Images/portada.png");
assert_eq!("image/png", mime.unwrap());

Returns None the resource can’t be found.

Source

pub fn get_current(&mut self) -> Option<(Vec<u8>, String)>

Returns the current chapter content and mime-type

The current follows the epub spine order. You can modify the current calling to go_next, go_prev or set_current methods.

Can return None if the epub is broken.

Source

pub fn get_current_str(&mut self) -> Option<(String, String)>

See Self::get_current

Source

pub fn get_current_with_epub_uris(&mut self) -> Result<Vec<u8>, DocError>

Returns the current chapter data, with resource uris renamed so they have the epub:// prefix and all are relative to the root file

This method is useful to render the content with a html engine, because inside the epub local paths are relatives, so you can provide that content, because the engine will look for the relative path in the filesystem and that file isn’t there. You should provide files with epub:// using Self::get_resource_by_path

§Examples

let current = doc.get_current_with_epub_uris().unwrap();
let text = String::from_utf8(current).unwrap();
assert!(text.contains("epub://OEBPS/Images/portada.png"));
doc.go_next();
let current = doc.get_current_with_epub_uris().unwrap();
let text = String::from_utf8(current).unwrap();
assert!(text.contains("epub://OEBPS/Styles/stylesheet.css"));
assert!(text.contains("http://creativecommons.org/licenses/by-sa/3.0/"));

§Errors

Returns DocError::InvalidEpub if the epub is broken.

Source

pub fn get_current_mime(&self) -> Option<String>

Returns the current chapter mimetype

§Examples

let m = doc.get_current_mime();
assert_eq!("application/xhtml+xml", m.unwrap());

Can return None if the epub is broken.

Source

pub fn get_current_path(&self) -> Option<PathBuf>

Returns the current chapter full path

§Examples

let p = doc.get_current_path();
assert_eq!(Path::new("OEBPS/Text/titlepage.xhtml"), p.unwrap());

Can return None if the epub is broken.

Source

pub fn get_current_id(&self) -> Option<String>

Returns the current chapter id

§Examples

let id = doc.get_current_id();
assert_eq!("titlepage.xhtml", id.unwrap());

Can return None if the epub is broken.

Source

pub fn go_next(&mut self) -> bool

Changes current to the next chapter

§Examples

doc.go_next();
assert_eq!("000.xhtml", doc.get_current_id().unwrap());

let len = doc.spine.len();
for i in 1..len {
    doc.go_next();
}
assert!(!doc.go_next());

Returns false if the current chapter is the last one

Source

pub fn go_prev(&mut self) -> bool

Changes current to the prev chapter

§Examples

assert!(!doc.go_prev());

doc.go_next(); // 000.xhtml
doc.go_next(); // 001.xhtml
doc.go_next(); // 002.xhtml
doc.go_prev(); // 001.xhtml
assert_eq!("001.xhtml", doc.get_current_id().unwrap());

Returns false if the current chapter is the first one

Source

pub fn get_num_pages(&self) -> usize

Returns the number of chapters

§Examples

assert_eq!(17, doc.get_num_pages());

Source

pub fn get_current_page(&self) -> usize

Returns the current chapter number, starting from 0

Source

pub fn set_current_page(&mut self, n: usize) -> bool

Changes the current page

§Examples

assert_eq!(0, doc.get_current_page());
doc.set_current_page(2);
assert_eq!("001.xhtml", doc.get_current_id().unwrap());
assert_eq!(2, doc.get_current_page());
assert!(!doc.set_current_page(50));

Returns false if the page is out of bounds

Source

pub fn add_extra_css(&mut self, css: &str)

This will inject this css in every html page getted with Self::get_current_with_epub_uris

§Examples

let extracss = "body { background-color: black; color: white }";
doc.add_extra_css(extracss);
let current = doc.get_current_with_epub_uris().unwrap();
let text = String::from_utf8(current).unwrap();
assert!(text.contains(extracss));

Source