peregrin 1.1.4 → 1.2.1

data/README.md

@@ -150,4 +150,9 @@ deeper meaning.
 
 ## History
 
-* 1.1.4 - Basic EPUB3 and EPUB fixed-layout read support (thanks @klacointe!)
+* 1.2.0
+  - Metadata files like OPF, OCX now first-class citizens called 'blueprints'
+  - Page progression direction from EPUB3 (@nono)
+  - Fixed-layout attributes for components (@nono)
+* 1.1.4
+  - Basic EPUB3 and EPUB fixed-layout read support (@klacointe)

data/lib/formats/epub.rb

@@ -35,7 +35,7 @@ class Peregrin::Epub
     begin
       book = Peregrin::Book.new
       epub = new(book)
-      epub.send(:load_config_documents, zf)
+      epub.send(:load_blueprints, zf)
     rescue => e
       raise e.class.new(path)
     end
@@ -70,7 +70,7 @@ class Peregrin::Epub
 
 
   def to_book(options = {})
-    bk = @book.deep_clone
+    @book.deep_clone
   end
 
 
@@ -81,84 +81,86 @@ class Peregrin::Epub
     #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
     def load_from_path(epub_path)
-      docs = nil
       Zip::Archive.open(epub_path) { |zipfile|
-        docs = load_config_documents(zipfile)
-        extract_properties(docs[:opf])
-        extract_components(zipfile, docs[:opf], docs[:opf_root])
-        extract_chapters(zipfile, {:ncx => docs[:ncx], :nav => docs[:nav]})
-        extract_cover(zipfile, docs)
+        load_blueprints(zipfile)
+        extract_properties
+        extract_components(zipfile)
+        extract_chapters(zipfile)
+        extract_cover(zipfile)
       }
       @book.read_resource_proc = lambda { |resource|
-        media_path = from_opf_root(docs[:opf_root], resource.src)
-        media_path = URI.unescape(media_path)
+        media_path = from_opf_root(resource.src)
+        media_path = uri_unescape(media_path)
         Zip::Archive.open(epub_path) { |zipfile| zipfile.content(media_path) }
       }
     end
 
 
-    def load_config_documents(zipfile)
+    def load_blueprints(zipfile)
       # The OCF file.
       begin
         ocf_content = zipfile.content(OCF_PATH)
-        docs = { :ocf => Nokogiri::XML::Document.parse(ocf_content) }
+        ocf = @book.add_blueprint(:ocf, OCF_PATH, ocf_content)
       rescue
         raise FailureLoadingOCF
       end
 
       # The OPF file.
       begin
-        docs[:opf_path] = docs[:ocf].at_xpath(
-          '//ocf:rootfile[@media-type="application/oebps-package+xml"]',
-          NAMESPACES[:ocf]
-        )['full-path']
-        docs[:opf_root] = File.dirname(docs[:opf_path])
-        opf_content = zipfile.content(docs[:opf_path])
-        docs[:opf] = Nokogiri::XML::Document.parse(opf_content)
+        opf_xp = '//ocf:rootfile[@media-type="application/oebps-package+xml"]'
+        opf_src = ocf.document.at_xpath(opf_xp, NAMESPACES[:ocf])['full-path']
+        opf_content = zipfile.content(opf_src)
+        opf = @book.add_blueprint(:opf, opf_src, opf_content)
       rescue
         raise FailureLoadingOPF
       end
 
-      # Extract Epub version
-      @book.version = docs[:opf].at_xpath('//opf:package', NAMESPACES[:opf])['version'].to_f
+      # EPUB version
+      pkg_elem = opf.document.at_xpath('//opf:package', NAMESPACES[:opf])
+      @epub_version = pkg_elem['version']
 
       # The NCX file.
-      # Must be present only with Ebook < 3.0 but can be use for forward compatibility
+      # Must be present only with Ebook < 3.0 but can be used
+      # for forward compatibility
       begin
-        spine = docs[:opf].at_xpath('//opf:spine', NAMESPACES[:opf])
+        spine = opf.document.at_xpath('//opf:spine', NAMESPACES[:opf])
         ncx_id = spine['toc'] ? spine['toc'] : 'ncx'
-        item = docs[:opf].at_xpath(
-          "//opf:manifest/opf:item[@id=#{escape_for_xpath(ncx_id)}]",
-          NAMESPACES[:opf]
-        )
-
-        docs[:ncx_path] = from_opf_root(docs[:opf_root], item['href'])
-        ncx_content = zipfile.content(docs[:ncx_path])
-        docs[:ncx] = Nokogiri::XML::Document.parse(ncx_content)
-      rescue => e
+        ncx_xp = "//opf:manifest/opf:item[@id=#{escape_for_xpath(ncx_id)}]"
+        ncx_href = opf.document.at_xpath(ncx_xp, NAMESPACES[:opf])['href']
+        ncx_src = from_opf_root(ncx_href)
+        ncx_content = zipfile.content(ncx_src)
+        ncx = @book.add_blueprint(:ncx, ncx_src, ncx_content)
+      rescue
         # Only raise an exeption for Ebook with version lower than 3.0
-        raise FailureLoadingNCX if @book.version < 3
+        raise FailureLoadingNCX if epub_version < 3
       end
 
       # The NAV file. (Epub3 only)
-      if @book.version >= 3
+      if epub_version >= 3
         begin
-          docs[:nav_path] = from_opf_root(
-            docs[:opf_root],
-            docs[:opf].at_xpath("//opf:manifest/opf:item[contains(concat(' ', normalize-space(@properties), ' '), ' nav ')]", NAMESPACES[:opf])['href']
-          )
-          nav_content = zipfile.content(docs[:nav_path])
-          docs[:nav] = Nokogiri::XML::Document.parse(nav_content)
+          nav_xp = "//opf:manifest/opf:item[contains"+
+            "(concat(' ', normalize-space(@properties), ' '), ' nav ')]"
+          nav_href = opf.document.at_xpath(nav_xp, NAMESPACES[:opf])['href']
+          nav_src = from_opf_root(nav_href)
+          nav_content = zipfile.content(nav_src)
+          nav = @book.add_blueprint(:nav, nav_src, nav_content)
         rescue => e
           raise FailureLoadingNAV
         end
       end
 
-      docs
+      # The others
+      inf_rels = %w[container manifest metadata signature encryption rights]
+      inf_rels.each { |rel|
+        src = "META-INF/#{rel}.xml"
+        next  unless zipfile.find(src)
+        bp = @book.add_blueprint(rel.to_sym, src, zipfile.content(src))
+      }
     end
 
 
-    def extract_properties(opf_doc)
+    def extract_properties
+      opf_doc = @book.blueprint_for(:opf).document
       meta_elems = opf_doc.at_xpath(
         '//opf:metadata',
         NAMESPACES[:opf]
@@ -184,11 +186,21 @@ class Peregrin::Epub
         }
         @book.add_property(name, content, atts) unless name.nil?
       }
+
+      # Assign EPUB version
+      @book.add_format_property('source', 'EPUB')
+      @book.add_format_property('version', @epub_version)  if @epub_version
+
+      # Extract page-turning direction
+      if spine = opf_doc.at_xpath('//opf:spine', NAMESPACES[:opf])
+        dir = spine['page-progression-direction']
+        @book.add_format_property('page-progression-direction', dir)  if dir
+      end
     end
 
 
-    def extract_components(zipfile, opf_doc, opf_root)
-      ids = {}
+    def extract_components(zipfile)
+      opf_doc = @book.blueprint_for(:opf).document
       manifest = opf_doc.at_xpath('//opf:manifest', NAMESPACES[:opf])
       spine = opf_doc.at_xpath('//opf:spine', NAMESPACES[:opf])
 
@@ -201,18 +213,20 @@ class Peregrin::Epub
           href = item['href']
           linear = iref['linear'] != 'no'
           begin
-            content = zipfile.content(from_opf_root(opf_root, href))
+            content = zipfile.content(from_opf_root(href))
           rescue
-            href = URI.unescape(href)
-            content = zipfile.content(from_opf_root(opf_root, href))
+            href = uri_unescape(href)
+            content = zipfile.content(from_opf_root(href))
           end
-          @book.add_component(
-            href,
-            content,
-            item['media-type'],
-            :id => id,
-            :linear => linear ? "yes" : "no"
-          )
+          atts = { :id => id, :linear => linear ? "yes" : "no" }
+          iref['properties'].split(/\s+/).each do |prop|
+            if prop =~ /^rendition:(layout|orientation|spread)-(.+)$/
+              atts["rendition:#{$1}"] = $2
+            else
+              atts[prop] = true
+            end
+          end if iref['properties']
+          @book.add_component(href, content, item['media-type'], atts)
         end
       }
 
@@ -231,14 +245,16 @@ class Peregrin::Epub
       }
     end
 
-    def extract_chapters(zipfile, docs)
-      if @book.version >= 3 && !docs[:nav].nil?
-        extract_nav_chapters(zipfile, docs[:nav])
+
+    def extract_chapters(zipfile)
+      if epub_version >= 3 && nav = @book.blueprint_for(:nav)
+        extract_nav_chapters(zipfile, nav.document)
       else
-        extract_ncx_chapters(zipfile, docs[:ncx])
+        extract_ncx_chapters(zipfile, @book.blueprint_for(:ncx).document)
       end
     end
 
+
     # Epub < 3.0 only
     def extract_ncx_chapters(zipfile, ncx_doc)
       curse = lambda { |point|
@@ -259,6 +275,7 @@ class Peregrin::Epub
       }
     end
 
+
     # Epub >= 3.0 only
     def extract_nav_chapters(zipfile, nav_doc)
       curse = lambda { |point, position|
@@ -286,7 +303,7 @@ class Peregrin::Epub
     end
 
 
-    def extract_cover(zipfile, docs)
+    def extract_cover(zipfile)
       @book.cover = nil
 
       # 1. Cover image referenced from metadata
@@ -310,7 +327,7 @@ class Peregrin::Epub
       if res.media_type.match(/^image\//)
         @book.cover = res
       else
-        path = from_opf_root(docs[:opf_root], res.src)
+        path = from_opf_root(res.src)
         begin
           doc = Nokogiri::XML::Document.parse(zipfile.content(path))
           src = nil
@@ -582,7 +599,9 @@ class Peregrin::Epub
     end
 
 
-    def from_opf_root(opf_root, *args)
+    def from_opf_root(*args)
+      opf = @book.blueprint_for(:opf)
+      opf_root = File.dirname(opf.src)
       if opf_root && !opf_root.empty? && opf_root != '.'
         File.join(opf_root, *args)
       else
@@ -596,6 +615,17 @@ class Peregrin::Epub
     end
 
 
+    def uri_unescape(str)
+      @uri_parser ||= URI.const_defined?(:Parser) ? URI::Parser.new : URI
+      @uri_parser.unescape(str)
+    end
+
+
+    def epub_version
+      @epub_version ? @epub_version.to_f : 0
+    end
+
+
   class ValidationError < ::RuntimeError
 
     def initialize(path = nil)

data/lib/formats/zhook.rb

@@ -118,8 +118,6 @@ class Peregrin::Zhook
       }
 
       # Add rel links and convert to html string
-      first_path = bk.components.first.src
-      last_path = bk.components.last.src
       boilerplate_rel_links <<
         '<link rel="first" href="'+bk.components.first.src+'" />' +
         '<link rel="last" href="'+bk.components.last.src+'" />'
@@ -361,6 +359,7 @@ class Peregrin::Zhook
 
 
     def self.extract_properties_from_index(book)
+      book.add_format_property('source', 'Zhook')
       doc = Nokogiri::HTML::Document.parse(
         book.components.first.contents
       )

data/lib/peregrin/blueprint.rb

@@ -0,0 +1,38 @@
+# Some ebook formats contain 'metadata' files that describe the contents of
+# the ebook package. Since Peregrin use 'metadata' to refer to key-value pairs
+# of information about the book, we call these files 'blueprints'.
+#
+class Peregrin::Blueprint < Peregrin::Resource
+
+  attr_accessor(:rel, :contents)
+
+  def initialize(rel, src, contents, media_type = 'application/xml', atts = {})
+    @rel = rel
+    @contents = contents
+    super(src, media_type, atts)
+  end
+
+
+  def document
+    raise "Not an XML document: #{src}"  unless xml?
+    @document ||= Nokogiri::XML::Document.parse(contents)
+  end
+
+
+  def xml?
+    media_type.match(/xml$/) ? true : false
+  end
+
+
+  def marshal_dump
+    instance_variables.inject({}) { |acc, v|
+      v.to_s == '@document' ? acc : acc.update(v => instance_variable_get(v))
+    }
+  end
+
+
+  def marshal_load(h)
+    h.each_pair { |k, v| instance_variable_set(k, v) }
+  end
+
+end

data/lib/peregrin/book.rb

@@ -10,19 +10,21 @@ class Peregrin::Book
   # children arrays.
   attr_accessor :chapters
 
-  # An array of Properties.
+  # An array of Properties containg the ebook-supplied metadata.
   attr_accessor :properties
 
+  # An array of Properties relating to the format of the ebook.
+  attr_accessor :format_properties
+
   # An array of Resources.
   attr_accessor :resources
 
+  # An array of Blueprints (ie, metadata files like the OPF or NCX).
+  attr_accessor :blueprints
+
   # A Resource that is used for the book cover.
   attr_accessor :cover
 
-  # The current version of document specifications
-  # Only used for Epub for now
-  attr_accessor :version
-
   # A proc that copies a resource to the given destination.
   attr_writer :read_resource_proc
 
@@ -31,12 +33,14 @@ class Peregrin::Book
     @components = []
     @chapters = []
     @properties = []
+    @format_properties = []
     @resources = []
+    @blueprints = []
   end
 
 
   def all_files
-    @components + @resources
+    @components + @resources + @blueprints
   end
 
 
@@ -50,6 +54,16 @@ class Peregrin::Book
   end
 
 
+  def add_blueprint(*args)
+    @blueprints.push(Peregrin::Blueprint.new(*args)).last
+  end
+
+
+  def blueprint_for(rel)
+    @blueprints.detect { |bp| bp.rel == rel }
+  end
+
+
   def add_chapter(*args)
     @chapters.push(Peregrin::Chapter.new(*args)).last
   end
@@ -67,6 +81,36 @@ class Peregrin::Book
   end
 
 
+  def add_format_property(*args)
+    @format_properties.push(Peregrin::Property.new(*args)).last
+  end
+
+
+  def format_property_for(key)
+    key = key.to_s
+    prop = @format_properties.detect { |p| p.key == key }
+    prop ? prop.value : nil
+  end
+
+
+  # The current version of document specifications.
+  # Only used for EPUB for now.
+  #
+  def version
+    v = format_property_for('version')
+    v ? v.to_f : nil
+  end
+
+
+  # The page progression direction.
+  # Can be "ltr" (left to right), "rtl" (right to left) or nil (omitted).
+  # Only used for EPUB for now.
+  #
+  def direction
+    format_property_for('page-progression-direction')
+  end
+
+
   def read_resource(resource_path)
     @read_resource_proc.call(resource_path)  if @read_resource_proc
   end

data/lib/peregrin/version.rb

@@ -1,5 +1,5 @@
 module Peregrin
 
-  VERSION = "1.1.4"
+  VERSION = "1.2.1"
 
 end

data/lib/peregrin.rb

@@ -14,6 +14,7 @@ module Peregrin
     "peregrin/book",
     "peregrin/resource",
     "peregrin/component",
+    "peregrin/blueprint",
     "peregrin/chapter",
     "peregrin/property",
     "peregrin/componentizer",

data/test/formats/epub_test.rb

@@ -89,6 +89,7 @@ class Peregrin::Tests::EpubTest < Test::Unit::TestCase
     assert_equal("cover.png", epub.to_book.cover.src)
   end
 
+
   def test_extracting_epub3_fixed_layout_properties
     epub = Peregrin::Epub.read("test/fixtures/epubs/epub3_fixed_layout.epub")
     book = epub.to_book
@@ -98,6 +99,20 @@ class Peregrin::Tests::EpubTest < Test::Unit::TestCase
     assert_equal("both", book.property_for('rendition:spread'))
   end
 
+
+  def test_extracting_epub3_fixed_layout_itemref
+    epub = Peregrin::Epub.read("test/fixtures/epubs/haruko-html-jpeg-20120524.epub")
+    book = epub.to_book
+    assert_equal(true, book.components[0].attributes["page-spread-left"])
+    assert_equal(nil, book.components[0].attributes["page-spread-right"])
+    assert_equal(nil, book.components[1].attributes["page-spread-left"])
+    assert_equal(true, book.components[1].attributes["page-spread-right"])
+    assert_equal(true, book.components.last.attributes["page-spread-left"])
+    assert_equal(nil, book.components.last.attributes["page-spread-right"])
+    assert_equal("reflowable", book.components.last.attributes["rendition:layout"])
+  end
+
+
   def test_extracting_version
     epub = Peregrin::Epub.read("test/fixtures/epubs/epub3_fixed_layout.epub")
     assert_equal(3.0, epub.to_book.version)
@@ -106,6 +121,7 @@ class Peregrin::Tests::EpubTest < Test::Unit::TestCase
     assert_equal(2.0, epub.to_book.version)
   end
 
+
   def test_extracting_chapters_from_ocx
     epub = Peregrin::Epub.read("test/fixtures/epubs/strunk.epub")
     assert_equal(9, epub.to_book.chapters.count)
@@ -117,6 +133,7 @@ class Peregrin::Tests::EpubTest < Test::Unit::TestCase
     assert_equal(27, epub.to_book.chapters.last.position)
   end
 
+
   def test_extracting_chapters_from_nav
     epub = Peregrin::Epub.read("test/fixtures/epubs/epub3_fixed_layout.epub")
     assert_equal(3, epub.to_book.chapters.count)
@@ -128,6 +145,7 @@ class Peregrin::Tests::EpubTest < Test::Unit::TestCase
     assert_equal(3, epub.to_book.chapters.last.position)
   end
 
+
   def test_extracting_nested_chapters_from_nav
     epub = Peregrin::Epub.read("test/fixtures/epubs/epub3_nested_nav.epub")
     assert_equal(11, epub.to_book.chapters.count)
@@ -175,6 +193,7 @@ class Peregrin::Tests::EpubTest < Test::Unit::TestCase
     )
   end
 
+
   def test_read_epub_to_write_epub
     epub = Peregrin::Epub.read("test/fixtures/epubs/strunk.epub")
     epub.write("test/output/strunk_test2.epub")
@@ -185,6 +204,23 @@ class Peregrin::Tests::EpubTest < Test::Unit::TestCase
   end
 
 
+  def test_extracting_direction
+    epub = Peregrin::Epub.read("test/fixtures/epubs/strunk.epub")
+    assert_equal(nil, epub.to_book.direction)
+    epub = Peregrin::Epub.read("test/fixtures/epubs/haruko-html-jpeg-20120524.epub")
+    assert_equal("rtl", epub.to_book.direction)
+  end
+
+
+  def test_extracting_blueprints
+    epub = Peregrin::Epub.read("test/fixtures/epubs/epub3_fixed_layout.epub")
+    assert_equal(
+      [:container, :nav, :ncx, :ocf, :opf],
+      epub.to_book.blueprints.collect(&:rel).sort
+    )
+  end
+
+
   protected
 
     def strunk_book

data/test/utils/componentizer_test.rb

@@ -37,7 +37,10 @@ class Peregrin::Tests::ComponentizerTest < Test::Unit::TestCase
     assert_equal(
       whitewash(
         "<!DOCTYPE html>" +
-        "<html><head><title>Components test 1</title></head><body>" +
+        "<html><head>" + 
+        "<meta http-equiv=\"Content-Type\" content=\"text/html;charset=UTF-8\">" +
+        "<title>Components test 1</title>" +
+        "</head><body>" +
         "<article><h2>B</h2></article>" +
         "</body></html>"
       ),

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: peregrin
 version: !ruby/object:Gem::Version 
-  hash: 27
-  prerelease: 
+  prerelease: false
   segments: 
   - 1
+  - 2
   - 1
-  - 4
-  version: 1.1.4
+  version: 1.2.1
 platform: ruby
 authors: 
 - Joseph Pearson
@@ -15,17 +14,16 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-05-14 00:00:00 Z
+date: 2012-09-29 00:00:00 +10:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: nokogiri
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -35,11 +33,9 @@ dependencies:
   name: zipruby
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -49,11 +45,9 @@ dependencies:
   name: mime-types
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -63,11 +57,9 @@ dependencies:
   name: rake
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -87,6 +79,7 @@ files:
 - lib/formats/epub.rb
 - lib/formats/ochook.rb
 - lib/formats/zhook.rb
+- lib/peregrin/blueprint.rb
 - lib/peregrin/book.rb
 - lib/peregrin/chapter.rb
 - lib/peregrin/component.rb
@@ -106,6 +99,7 @@ files:
 - test/utils/outliner_test.rb
 - README.md
 - MIT-LICENSE
+has_rdoc: true
 homepage: http://ochook.org/peregrin
 licenses: []
 
@@ -118,27 +112,23 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: nowarning
-rubygems_version: 1.8.24
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Peregrin - ebook conversion