Read EPUB format e-books into a data frame using
epub or extract EPUB archive files for direct use with
1 2 3 4 5 6 7 8 9 10 11 12
character, input EPUB filename. May be a vector for
character, vector of metadata fields (data frame columns) to parse from metadata, if they exist. See details.
character, a regular expression pattern string to identify text sections (rows of nested text data frame) to drop.
character, a regular expression pattern string to attempt distinguishing nested data frame rows of chapter text entries from other types of entries.
character, defaults to
additional arguments. With the exception of passing
The primary function here is
epub. It parses EPUB file metadata and textual content into a data frame.
The output data frame has one row for each file in
It has metadata in all columns except the
data column, which is a column of nested data frames containing e-book text by book section (e.g., chapters).
Both the primary and nested data frames are tibbles and safe to print to the console "as is".
Be careful if
file is a long vector of many EPUB files.
This could take a long time to process as well as could potentially use up all of your system RAM if you have far too many large books in one call to
On a case by case basis, you can always select columns and filter rows of a resulting data frame for a single e-book subsequent to visual inspection.
However, the optional arguments
chapter_pattern allow you to do some of this as part of the EPUB file reading process.
You can ignore these arguments and do all your own post-processing of the resulting data frame, but if using these arguments,
they are most likely to be useful for bulk e-book processing where
file is a vector of like-formatted files.
fields argument can be used to limit the columns returned in the primary data frame.
fields = c("title", "creator", "date", "identifier", "publisher", "file"). Some fields will be returned even if not in
fields, such as
Ideally, you should already know what metadata fields are in the EPUB file. This is not possible for large collections with possibly different formatting. Note that when
"file" is included in
fields, the output will include a column of the original file names, in case this is different from the content of a
source field that may be present in the metadata.
So this field is always available even if not part of the file metadata.
Additionally, if there is no
title field in the metadata, the output data frame will include a
title column filled in with the same file names,
unless you pass the additional optional title argument, e.g.
title = "TitleFieldID" so that another field can me mapped to
If supplying a
title argument that also does not match an existing field in the e-book, the output
title column will again default to file names.
File names are the fallback option because unlike e-book metadata fields, file names always exist and should also always be unique when performing vectorized reads over multiple books,
title can be a column in the output data frame that uniquely identifies different e-books even if the books did not have a
title field in their metadata.
Columns of the nested data frames in
data are fixed. Select from these in subsequent data frame manipulations.
chapter_pattern argument may be helpful for bulk processing of similarly formatted EPUB files. This should be ignored for poorly formatted EPUB files or where there is inconsistent naming across an e-book collection.
fields, you should explore file metadata in advance or this argument will not be useful. If provided, a column
nchap is added to the output data frame giving the guessed number of chapters.
data column, the
section column of the nested data frames will also be updated to reflect guessed chapters with new, consistent chapter IDs, always beginning with
ch and ending with digits.
drop_sections argument also uses regular expression pattern matching like
chapter_pattern and operates on the same
section column. It simply filters out any matched rows.
This is useful for dropping rows that may pertain to book cover, copyright and acknowledgements pages, and other similar, clearly non-chapter text, e-book sections.
An example that might work for many books could be
drop_sections = "^co(v|p)|^ack"
Rows of the primary data frame are fixed. Filter or otherwise manipulate these in subsequent data frame manipulations. There is one row per file so filtering does not make sense to do as part of the initial file reading.
epub_meta to return a data frame of only the metadata for each file in
file. This skips the reading of each file's text contents, strictly parsing the metadata.
It returns a data frame with one row for each file and
n columns where
n is equal to the union of all fields identified across all files in
Fields available for at least one e-book in
file will return
NA in that column for any row pertaining to an e-book that does not have that field in its metadata.
If the metadata contains multiple entries for a field, such as multiple subjects or publication dates, they are collapsed using the pipe character.
epub_unzip directly on individual EPUB files, this gives you control over where to extract archive files to and what to do with them subsequently.
epub_unzip internally to extract EPUB archive files to the R session temp directory (with
You do not need to use
epub_unzip directly prior to using these other functions. It is only needed if you want the internal files for some other purpose in or out of R.
epub returns a data frame.
epub_unzip returns nothing but extracts files from an EPUB file archive.
1 2 3 4 5 6 7 8 9 10 11 12 13 14
# Use a local example EPUB file included in the package file <- system.file("dracula.epub", package = "epubr") bookdir <- file.path(tempdir(), "dracula") epub_unzip(file, exdir = bookdir) # unzip to directly inspect archive files list.files(bookdir, recursive = TRUE) epub_meta(file) # parse EPUB file metadata only x <- epub(file) # parse entire e-book x x$data[] epub(file, fields = c("title", "creator"), drop_sections = "^cov")
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.