peregrin 1.1.1

data/lib/peregrin/outliner.rb

@@ -0,0 +1,204 @@
+class Peregrin::Outliner
+
+  REGEXES = {
+    :section_root => /^BLOCKQUOTE|BODY|DETAILS|FIELDSET|FIGURE|TD$/i,
+    :section_content => /^ARTICLE|ASIDE|NAV|SECTION$/i,
+    :heading => /^H[1-6]|HGROUP$/i
+  }
+
+  class Utils
+
+    def self.section_root?(el)
+      element_name_is?(el, REGEXES[:section_root])
+    end
+
+
+    def self.section_content?(el)
+      element_name_is?(el, REGEXES[:section_content])
+    end
+
+
+    def self.heading?(el)
+      element_name_is?(el, REGEXES[:heading])
+    end
+
+
+    def self.named?(el, name)
+      element_name_is?(el, /^#{name}$/)
+    end
+
+
+    def self.heading_rank(el)
+      raise "Not a heading: #{el.inspect}"  unless heading?(el)
+      if named?(el, 'HGROUP')
+        1.upto(6) { |n| return n  if el.at_css("h#{n}") }
+        return 6 #raise "Heading not found in HGROUP: #{el.inspect}"
+      else
+        el.name.reverse.to_i
+      end
+    end
+
+
+    def self.element_name_is?(el, pattern)
+      return false  unless el
+      return false  unless el.respond_to?(:name)
+      return false  if el.name.nil? || el.name.empty?
+      el.name.upcase.match(pattern) ? true : false
+    end
+
+  end
+
+
+  class Section
+
+    attr_accessor :sections, :heading, :container, :node
+
+
+    def initialize(node = nil)
+      self.node = node
+      self.sections = []
+    end
+
+
+    def append(subsection)
+      subsection.container = self
+      sections.push(subsection)
+    end
+
+
+    def empty?
+      heading_text.nil? && sections.all? { |sxn| sxn.empty? }
+    end
+
+
+    def heading_text
+      return nil  unless Utils.heading?(heading)
+      h = heading
+      h = h.at_css("h#{Utils.heading_rank(h)}")  if Utils.named?(h, 'HGROUP')
+      return  nil  unless h && !h.content.strip.empty?
+      h.content.strip
+    end
+
+
+    def heading_rank
+      # FIXME: some doubt as to whether 1 is the sensible default
+      Utils.heading?(heading) ? Utils.heading_rank(heading) : 1
+    end
+
+  end
+
+
+
+  def initialize(doc)
+    @document = doc
+  end
+
+
+  def process(from)
+    @outlinee = nil
+    @outlines = {}
+    @section = Section.new
+    @stack = []
+    walk(from)
+  end
+
+
+  def walk(node)
+    return  unless node
+    enter_node(node)
+    node.children.each { |ch| walk(ch) }
+    exit_node(node)
+  end
+
+
+  def enter_node(node)
+    return  if Utils.heading?(@stack.last)
+
+    if Utils.section_content?(node) || Utils.section_root?(node)
+      @stack.push(@outlinee)  unless @outlinee.nil?
+      @outlinee = node
+      @section = Section.new(node)
+      @outlines[@outlinee] = Section.new(node)
+      @outlines[@outlinee].sections = [@section]
+      return
+    end
+
+    return  if @outlinee.nil?
+
+    if Utils.heading?(node)
+      node_rank = Utils.heading_rank(node)
+      if !@section.heading
+        @section.heading = node
+      elsif node_rank <= @outlines[@outlinee].sections.last.heading_rank
+        @section = Section.new
+        @section.heading = node
+        @outlines[@outlinee].sections.push(@section)
+      else
+        candidate = @section
+        while true
+          if node_rank > candidate.heading_rank
+            @section = Section.new
+            candidate.append(@section)
+            @section.heading = node
+            break
+          end
+          candidate = candidate.container
+        end
+      end
+      @stack.push(node)
+    end
+  end
+
+
+  def exit_node(node)
+    if Utils.heading?(@stack.last)
+      @stack.pop  if @stack.last == node
+      return
+    end
+
+    if Utils.section_content?(node) && !@stack.empty?
+      @outlinee = @stack.pop
+      @section = @outlines[@outlinee].sections.last
+      @outlines[node].sections.each { |s| @section.append(s) }
+      return
+    end
+
+    if Utils.section_root?(node) && !@stack.empty?
+      @outlinee = @stack.pop
+      @section = @outlines[@outlinee].sections.last
+      while @section.sections.any?
+        @section = @section.sections.last
+      end
+      return
+    end
+
+    if Utils.section_content?(node) || Utils.section_root?(node)
+      @section = @outlines[@outlinee].sections.first
+      return
+    end
+  end
+
+
+  def to_html
+    curse = lambda { |section, is_root|
+      below = section.sections.collect { |ch|
+        ch_out = curse.call(ch, false).strip
+        (ch_out.nil? || ch_out.empty?) ? "" : "<li>#{ch_out}</li>"
+      }.join.strip
+      below = (below.nil? || below.empty?) ? "" : "<ol>#{below}</ol>\n"
+      if is_root
+        below
+      else
+        heading = block_given? ? yield(section, below) : section.heading_text
+        "#{heading}#{below}"
+      end
+    }
+    curse.call(result_root, true)
+  end
+
+
+  def result_root
+    @outlines[@outlinee]
+  end
+
+end

data/lib/peregrin/property.rb

@@ -0,0 +1,16 @@
+# Books have metadata. Each unit of metadata (each metadatum?) is a 'property'
+# of the book.
+#
+# A property has a key, a value and an optional set of attributes.
+#
+class Peregrin::Property
+
+  attr_accessor :key, :value, :attributes
+
+  def initialize(key, value, attributes = {})
+    @key = key
+    @value = value
+    @attributes = attributes
+  end
+
+end

data/lib/peregrin/resource.rb

@@ -0,0 +1,24 @@
+# Any file that is a part of the book but not one of its linear sections (ie,
+# Components) is a Resource.
+#
+# Resources can potentially be quite large, so as far as possible we don't
+# store their contents in memory.
+#
+class Peregrin::Resource
+
+  attr_accessor :src, :attributes
+  attr_writer :media_type
+
+  def initialize(src, media_type = nil, attributes = {})
+    @src = src
+    @media_type = media_type || MIME::Types.of(File.basename(@src))
+    @media_type = @media_type.first  if @media_type.kind_of?(Array)
+    @attributes = attributes
+  end
+
+
+  def media_type
+    @media_type ? @media_type.to_s : nil
+  end
+
+end

data/lib/peregrin/version.rb

@@ -0,0 +1,5 @@
+module Peregrin
+
+  VERSION = "1.1.1"
+
+end

data/lib/peregrin/zip_patch.rb

@@ -0,0 +1,11 @@
+class Zip::Archive
+
+  def read(path)
+    fopen(path) { |f| f.read }
+  end
+
+  def find(path)
+    detect { |f| f.name == path }
+  end
+
+end

data/lib/peregrin.rb

@@ -0,0 +1,139 @@
+module Peregrin
+
+  # Required libraries
+  require 'fileutils'
+  require 'uri'
+  require 'zipruby'
+  require 'nokogiri'
+  require 'mime/types'
+
+  # Require libs in this directory
+  [
+    "peregrin/version",
+    "peregrin/zip_patch",
+    "peregrin/book",
+    "peregrin/resource",
+    "peregrin/component",
+    "peregrin/chapter",
+    "peregrin/property",
+    "peregrin/componentizer",
+    "peregrin/outliner",
+    "formats/epub",
+    "formats/zhook",
+    "formats/ochook"
+  ].each { |lib|
+    require lib
+  }
+
+
+  class Main
+
+    def self.run(args)
+      if args.size == 1
+        src = args.first
+        validate(src) and inspect(src)
+      elsif args.size == 2
+        src, dest = args
+        validate(src) and convert(src, dest) and inspect(dest)
+      else
+        usage
+      end
+    end
+
+
+    def self.usage
+      puts "Peregrin [http://ochook.org/peregrin]"
+      puts "Version: #{VERSION}"
+      puts "A tool for inspecting Zhooks, Ochooks and EPUB ebooks,"
+      puts "and converting between them."
+      puts ""
+      puts "Usage: peregrin srcpath [destpath]"
+      puts ""
+      puts "If one path given, validates ebook at that path and outputs analysis."
+      puts "If two paths given, converts from srcpath to destpath and outputs "
+      puts "analysis of converted ebook."
+    end
+
+
+    def self.validate(path)
+      klass = format_for_path(path)
+      klass.validate(path)
+      true
+    rescue UnknownFileFormat => e
+      exit_with("Unknown file format: #{path}")
+    rescue => e
+      exit_with("Invalid #{klass::FORMAT}: #{path}", "Reason - #{e}")
+    end
+
+
+    def self.convert(src_path, dest_path, src_klass = nil, dest_klass = nil)
+      src_klass ||= format_for_path(src_path)
+      dest_klass ||= format_for_path(dest_path)
+
+      src_ook = src_klass.read(src_path)
+
+      # FIXME: how do we do these options? User-specified? Dest-format-specified?
+      options = {}
+      options[:componentize] = true  if dest_klass == Peregrin::Epub
+      book = src_ook.to_book(options)
+
+      dest_ook = dest_klass.new(book)
+      dest_ook.write(dest_path)
+      validate(dest_path)
+    end
+
+
+    def self.inspect(path)
+      klass = format_for_path(path)
+      ook = klass.read(path)
+      book = ook.to_book
+      puts "[#{klass::FORMAT}]"
+      puts "\nCover\n  #{book.cover.src}"
+      puts "\nComponents [#{book.components.size}]"
+      book.components.each { |cmpt| puts "  #{cmpt.src}" }
+      puts "\nResources [#{book.resources.size}]"
+      book.resources.each { |res| puts "  #{res.src}" }
+      puts "\nChapters"
+      book.chapters.each { |chp| print_chapter_title(chp, "- ") }
+      puts "\nProperties [#{book.properties.size}]"
+      book.properties.each { |property|
+        puts "  #{property.key}: #{property.value}"  unless property.value.empty?
+      }
+      true
+    end
+
+
+    private
+
+      def self.format_for_path(path)
+        return Peregrin::Zhook  if File.extname(path) == ".zhook"
+        return Peregrin::Epub  if File.extname(path) == ".epub"
+        return Peregrin::Ochook  if File.directory?(path) || !File.exists?(path)
+        raise UnknownFileFormat.new(path)
+      end
+
+
+      def self.exit_with(*remarks)
+        remarks.each { |rm| puts(rm) }
+        false
+      end
+
+
+      def self.print_chapter_title(chp, padd)
+        puts "#{padd}#{chp.title}"
+        chp.children.each { |ch|
+          print_chapter_title(ch, "  "+padd)
+        }
+      end
+
+
+
+    class UnknownFileFormat < RuntimeError
+      def initialize(path = nil)
+        @page = path
+      end
+    end
+
+  end
+
+end

data/test/conversion_test.rb

@@ -0,0 +1,80 @@
+require 'test_helper'
+
+class Peregrin::Tests::ConversionTest < Test::Unit::TestCase
+
+  def test_epub_to_ochook
+    conversion_test(
+      Peregrin::Epub,
+      Peregrin::Ochook,
+      'test/fixtures/epubs/strunk.epub',
+      'test/output/conversions/epub_to_ochook'
+    )
+  end
+
+
+  def test_epub_to_zhook
+    conversion_test(
+      Peregrin::Epub,
+      Peregrin::Zhook,
+      'test/fixtures/epubs/strunk.epub',
+      'test/output/conversions/epub_to_zhook.zhook'
+    )
+  end
+
+
+  def test_ochook_to_epub
+    conversion_test(
+      Peregrin::Ochook,
+      Peregrin::Epub,
+      'test/fixtures/ochooks/basic',
+      'test/output/conversions/ochook_to_epub.epub',
+      :componentize => true
+    )
+  end
+
+
+  def test_ochook_to_zhook
+    conversion_test(
+      Peregrin::Ochook,
+      Peregrin::Zhook,
+      'test/fixtures/ochooks/basic',
+      'test/output/conversions/ochook_to_zhook.zhook',
+      :componentize => true
+    )
+    assert_nil(@dest_ook.send(:index).root['manifest'])
+  end
+
+
+  def test_zhook_to_epub
+    conversion_test(
+      Peregrin::Zhook,
+      Peregrin::Epub,
+      'test/fixtures/zhooks/flat.zhook',
+      'test/output/conversions/zhook_to_epub.epub',
+      :componentize => true
+    )
+  end
+
+
+  def test_zhook_to_ochook
+    conversion_test(
+      Peregrin::Zhook,
+      Peregrin::Ochook,
+      'test/fixtures/zhooks/flat.zhook',
+      'test/output/conversions/zhook_to_ochook',
+      :componentize => true
+    )
+  end
+
+
+  private
+
+    def conversion_test(src_klass, dest_klass, src, dest, to_book_options = {})
+      @src_ook = src_klass.read(src)
+      @dest_ook = dest_klass.new(@src_ook.to_book(to_book_options))
+      FileUtils.mkdir_p(File.dirname(dest))
+      @dest_ook.write(dest)
+      assert_nothing_raised { dest_klass.validate(dest) }
+    end
+
+end

data/test/formats/epub_test.rb

@@ -0,0 +1,159 @@
+require 'test_helper'
+
+class Peregrin::Tests::EpubTest < Test::Unit::TestCase
+
+  # A fairly trivial book-in, book-out test.
+  def test_book_to_book
+    epub = Peregrin::Epub.new(strunk_book)
+    book = epub.to_book
+    assert_equal(22, book.components.length)
+    assert_equal(6, book.chapters.length)
+    assert_equal("William Strunk Jr.", book.property_for('creator'))
+  end
+
+
+  def test_write_to_epub
+    epub = Peregrin::Epub.new(strunk_book)
+    epub.write('test/output/strunk_test.epub')
+    assert(File.exists?('test/output/strunk_test.epub'))
+    assert_nothing_raised {
+      Peregrin::Epub.validate("test/output/strunk_test.epub")
+    }
+  end
+
+
+  def test_heading_depth
+    epub = Peregrin::Epub.new(strunk_book)
+    assert_equal(2, epub.send(:heading_depth))
+  end
+
+
+  def test_epub_validation
+    assert_nothing_raised {
+      Peregrin::Epub.validate("test/fixtures/epubs/strunk.epub")
+    }
+  end
+
+
+  def test_extracting_metadata
+    epub = Peregrin::Epub.read("test/fixtures/epubs/strunk.epub")
+    assert_equal("The Elements of Style", epub.to_book.property_for('title'))
+  end
+
+
+  def test_extracting_components
+    epub = Peregrin::Epub.read("test/fixtures/epubs/strunk.epub")
+    book = epub.to_book
+    assert_equal(
+      ["cover.xml", "title.xml", "about.xml", "main0.xml", "main1.xml", "main2.xml", "main3.xml", "main4.xml", "main5.xml", "main6.xml", "main7.xml", "main8.xml", "main9.xml", "main10.xml", "main11.xml", "main12.xml", "main13.xml", "main14.xml", "main15.xml", "main16.xml", "main17.xml", "main18.xml", "main19.xml", "main20.xml", "main21.xml", "similar.xml", "feedbooks.xml"],
+      book.components.collect { |cmpt| cmpt.src }
+    )
+    assert_equal(
+      ["css/page.css", "css/feedbooks.css", "css/title.css", "css/about.css", "css/main.css", "images/logo-feedbooks-tiny.png", "images/logo-feedbooks.png", "images/cover.png"],
+      book.resources.collect { |res| res.src }
+    )
+  end
+
+
+  def test_extracting_contents
+    epub = Peregrin::Epub.read("test/fixtures/epubs/strunk.epub")
+    assert_equal(2, epub.send(:heading_depth))
+  end
+
+
+  def test_extracting_cover
+    # Cover image referenced from metadata
+    epub = Peregrin::Epub.read("test/fixtures/epubs/covers/cover_in_meta.epub")
+    assert_equal("cover.png", epub.to_book.cover.src)
+
+    # First image in a component listed in the guide as 'cover'
+    epub = Peregrin::Epub.read("test/fixtures/epubs/covers/cover_in_guide.epub")
+    assert_equal("cover.png", epub.to_book.cover.src)
+
+    # A component with the id of 'cover-image'.
+    epub = Peregrin::Epub.read(
+      "test/fixtures/epubs/covers/cover-image_in_manifest.epub"
+    )
+    assert_equal("cover.png", epub.to_book.cover.src)
+
+    # First image in component with the id of 'cover'.
+    epub = Peregrin::Epub.read(
+      "test/fixtures/epubs/covers/cover_in_manifest.epub"
+    )
+    assert_equal("cover.png", epub.to_book.cover.src)
+
+    # First image in first component.
+    epub = Peregrin::Epub.read(
+      "test/fixtures/epubs/covers/cover_in_first_cmpt.epub"
+    )
+    assert_equal("cover.png", epub.to_book.cover.src)
+  end
+
+
+  def test_read_epub_to_write_epub
+    epub = Peregrin::Epub.read("test/fixtures/epubs/strunk.epub")
+    epub.write("test/output/strunk_test2.epub")
+    assert(File.exists?('test/output/strunk_test2.epub'))
+    assert_nothing_raised {
+      Peregrin::Epub.validate("test/output/strunk_test2.epub")
+    }
+  end
+
+
+  protected
+
+    def strunk_book
+      book = Peregrin::Book.new
+      0.upto(21) { |i|
+        path = "main#{i}.xml"
+        book.add_component(
+          path,
+          IO.read("test/fixtures/epubs/strunk/OPS/#{path}")
+        )
+      }
+      pos = 0
+      chp = book.add_chapter(
+        "Chapter 1 - Introductory",
+        pos+=1,
+        "main0.xml"
+      )
+      chp = book.add_chapter(
+        "Chapter 2 - Elementary Rules of Usage",
+        pos+=1,
+        "main1.xml"
+      )
+      chp.add_child(
+        "1. Form the possessive singular of nounds with 's",
+        pos+=1,
+        "main1.xml#section_98344"
+      )
+      chp = book.add_chapter(
+        "Chapter 3 - Elementary Principles of Composition",
+        pos+=1,
+        "main9.xml"
+      )
+      chp = book.add_chapter(
+        "Chapter 4 - A Few Matters of Form",
+        pos+=1,
+        "main19.xml"
+      )
+      chp = book.add_chapter(
+        "Chapter 5 - Words and Expressions Commonly Misused",
+        pos+=1,
+        "main20.xml"
+      )
+      chp = book.add_chapter(
+        "Chapter 6 - Words Commonly Misspelled",
+        pos+=1,
+        "main21.xml"
+      )
+      book.add_property("title", "The Elements of Style")
+      book.add_property("creator", "William Strunk Jr.")
+      book.add_resource("css/main.css")
+      book.read_resource_proc = lambda { |resource|
+        IO.read("test/fixtures/epubs/strunk/OPS/#{resource.src}")
+      }
+      book
+    end
+
+end