= EPUB Parser = {doctitle} image:https://gitlab.com/KitaitiMakoto/epub-parser/badges/master/build.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 ~/Documebts/Books/build_awesome_command_line_applications_in_ruby.epub Title: Build Awesome Command-Line Applications in Ruby (for KITAITI MAKOTO) Identifiers: 978-1-934356-91-3 Titles: Build Awesome Command-Line Applications in Ruby (for KITAITI MAKOTO) Languages: en Contributors: Coverages: Creators: David Bryant Copeland Dates: Descriptions: Formats: Publishers: The Pragmatic Bookshelf, LLC (338304) Relations: Rights: Copyright © 2012 Pragmatic Programmers, LLC Sources: Subjects: Pragmatic Bookshelf Types: Unique identifier: 978-1-934356-91-3 Epub version: 2.0 ---- 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.3.9 * [BUG FIX]Set {EPUB::Metadata::DCMES#lang} properly from xml:lang attribute * Change default XML backend from REXML to Nokogiri === 0.3.8 * [REFACTORING]Add {EPUB::Parser::NokogiriAttributeWithPrefix} and use `Nokogiri::XML::Node#attribute_with_prefix` instead of `EPUB::Parser::Utils#extract_attribute` * Set default value for detect_encoding argument for {EPUB::Publication::Package::Manifest::Item#read} to false * Make XML library switchable between REXML and Nokogiri * Make REXML a default XML backend === 0.3.7 * Strip leading and trailing white spaces from identifiers * Change home page and documentation from rubydoc.info to GitLab Pages * Make {EPUB::Book::Features#cover_image Book::Features#cover_image} return EPUB 2 cover image if EPUB 3's not available * Add `epub-cover` command-line tool. See {file:docs/EpubCover.adoc} for details. 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.