= EPUB Parser = {doctitle} image:https://gitlab.com/KitaitiMakoto/epub-parser/badges/master/pipeline.svg[link="https://gitlab.com/KitaitiMakoto/epub-parser/commits/master",title="pipeline status"] image:https://badge.fury.io/rb/epub-parser.svg[link="https://gemnasium.com/KitaitiMakoto/epub-parser",title="Gem Version"] image:https://gitlab.com/KitaitiMakoto/epub-parser/badges/master/coverage.svg[link="https://kitaitimakoto.gitlab.io/epub-parser/coverage/",title="coverage report"] * https://kitaitimakoto.gitlab.io/epub-parser/file.Home.html[Homepage] * https://kitaitimakoto.gitlab.io/epub-parser/[Documentation] * https://gitlab.com/KitaitiMakoto/epub-parser[Source Code] * https://kitaitimakoto.gitlab.io/epub-parser/coverage/[Test Coverage] == INSTALLATION ---- gem install epub-parser ---- == USAGE === As a library ---- require 'epub/parser' book = EPUB::Parser.parse('book.epub') book.metadata.titles # => Array of EPUB::Publication::Package::Metadata::Title. Main title, subtitle, etc... book.metadata.title # => Title string including all titles book.metadata.creators # => Creators(authors) book.each_page_on_spine do |page| page.media_type # => "application/xhtml+xml" page.entry_name # => "OPS/nav.xhtml" entry name in EPUB package(zip archive) page.read # => raw content document page.content_document.nokogiri # => Nokogiri::XML::Document. The same to Nokogiri.XML(page.read) # do something more # : end book.cover_image # => EPUB::Publication::Package::Manifest::Item which represents cover image file ---- See document's {file:docs/Home.markdown} or https://kitaitimakoto.gitlab.io/epub-parser/[API Documentation] for more info. === `epubinfo` command-line tool `epubinfo` tool extracts and shows the metadata of specified EPUB book. ---- % epubinfo ./linear-algebra.epub Title: A First Course in Linear Algebra Identifiers: code.google.com.epub-samples.linear-algebra Titles: A First Course in Linear Algebra Languages: en Contributors: Coverages: Creators: Robert A. Beezer Dates: Descriptions: Formats: Publishers: Relations: Rights: This work is shared with the public using the GNU Free Documentation License, Version 1.2., © 2004 by Robert A. Beezer. Sources: Subjects: Types: Modified: 2012-03-05T12:47:00Z Unique identifier: code.google.com.epub-samples.linear-algebra Epub version: 3.0 Navigations: toc, landmarks ---- See {file:docs/Epubinfo.markdown} for more info. === `epub-open` command-line tool `epub-open` tool provides interactive shell(IRB) which helps you research about EPUB book. ---- epub-open path/to/book.epub ---- IRB starts. `self` becomes the EPUB book and can access to methods of `EPUB`. ---- title => "Title of the book" metadata.creators => [Author 1, Author2, ...] resources.first.properties => # # You know that first resource of this book is nav document nav = resources.first => ... nav.href => # nav.media_type => "application/xhtml+xml" puts nav.read : : : => nil exit # Enter "exit" when exit the session ---- See {file:docs/EpubOpen.markdown} for more info. === `epub-cover` command-line tool `epub-cover` tool extract cover image from EPUB book. ---- % epub-cover childrens-literature.epub Cover image output to cover.png ---- See {file:docs/EpubCover.adoc} for details. == DOCUMENTATION Documentation is available in https://kitaitimakoto.gitlab.io/epub-parser/file.Home.html[homepage]. If you installed EPUB Parser by gem command, you can also generate documentaiton yourself(https://rubygems.org/gems/rubygems-yardoc[rubygems-yardoc] gem is needed): ---- $ gem install epub-parser $ gem yardoc epub-parser ... Files: 33 Modules: 20 ( 20 undocumented) Classes: 45 ( 44 undocumented) Constants: 31 ( 31 undocumented) Methods: 292 ( 88 undocumented) 52.84% documented YARD documentation is generated to: /path/to/gempath/ruby/2.2.0/doc/epub-parser-0.2.0/yardoc ---- It will show you path to generated documentation(`/path/to/gempath/ruby/2.2.0/doc/epub-parser-0.2.0/yardoc` here) at the end. Or, generating by yardoc command is possible, too: ---- $ git clone https://gitlab.com/KitaitiMakoto/epub-parser.git $ cd epub-parser $ bundle install --path=deps $ bundle exec rake doc:yard ... Files: 33 Modules: 20 ( 20 undocumented) Classes: 45 ( 44 undocumented) Constants: 31 ( 31 undocumented) Methods: 292 ( 88 undocumented) 52.84% documented ---- Then documentation will be available in `doc` directory. == REQUIREMENTS * Ruby 2.3.0 or later == SIMILAR EFFORTS * https://github.com/skoji/gepub[gepub] - a generic EPUB library for Ruby * https://github.com/chdorner/epubinfo[epubinfo] - Extracts metadata information from EPUB files. Supports EPUB2 and EPUB3 formats. * https://github.com/kmuto/review[ReVIEW] - ReVIEW is a easy-to-use digital publishing system for books and ebooks. * https://github.com/takahashim/epzip[epzip] - epzip is EPUB packing tool. It's just only doing 'zip.' :) * https://github.com/jugyo/eeepub[eeepub] - EeePub is a Ruby ePub generator * https://gitlab.com/KitaitiMakoto/epub-maker[epub-maker] - This library supports making and editing EPUB books based on this EPUB Parser library * https://gitlab.com/KitaitiMakoto/epub-cfi[epub-cfi] - EPUB CFI library extracted this EPUB Parser library. If you find other gems, please tell me or request a pull request. == RECENT CHANGES === 0.4.7 * Remove version specification from Nokogiri to migrate to Ruby 3.1 === 0.4.6 * [BUG FIX]Prevent epubinfo tool raise exception when no nav elements * Tiny modifcation on Zip archive manipulation === 0.4.5 * [BUG FIX]Handle the case EPUB path is a Pathname === 0.4.4 * [BUG FIX]Fix navigation type check bug * Add feature to show navigations to `epubinfo` command-line tool === 0.4.3 * Encode file name passed from file system on Unix === 0.4.2 * [BUG FIX]Fix a bug that epub-cover refers out of scope variable * [BUG FIX]Fix a bug that `epubinfo` command with `--words` or `--chars` option causes load error if there is not Nokogiri in environment * [BUG FIX]Fix a bug that REXML::Element#content ignores descendant nodes See {file:CHANGELOG.adoc} for older changelogs and details. == TODOS * Consider to implement IRI feature instead of to use Addressable * EPUB 3.2 * Help features for `epub-open` tool * Vocabulary Association Mechanisms * Implementing navigation document and so on * Media Overlays * Content Document * Digital Signature * Handle with encodings other than UTF-8 == DONE * Simple inspect for `epub-open` tool * Using zip library instead of `unzip` command, which has security issue * Modify methods around fallback to see `bindings` element in the package * Content Document(only for Navigation Documents) * Fixed Layout * Vocabulary Association Mechanisms(only for itemref) * Archive library abstraction * Extracting and organizing common behavior from some classes to modules * Multiple rootfiles * Abstraction of XML parser(making it possible to use REXML, standard bundled XML library of Ruby) == LICENSE This library is distribuetd under the term of the MIT License. See {file:MIT-LICENSE} file for more info.