peregrin 1.1.1

data/lib/formats/zhook.rb

@@ -0,0 +1,394 @@
+class Peregrin::Zhook
+
+  FORMAT = "Zhook"
+
+  FILE_EXT = ".zhook"
+  INDEX_PATH = "index.html"
+  COVER_PATH = "cover.png"
+  BODY_XPATH = '/html/body'
+  HEAD_XPATH = '/html/head'
+
+  # Raises an exception if file at path is not a valid Zhook. Otherwise
+  # returns true.
+  #
+  def self.validate(path)
+    raise FileNotFound.new(path)  unless File.file?(path)
+    raise WrongExtension.new(path)  unless File.extname(path) == FILE_EXT
+    begin
+      zf = Zip::Archive.open(path)
+    rescue
+      raise NotAZipArchive.new(path)
+    end
+
+    unless zf.find(INDEX_PATH)
+      raise MissingIndexHTML.new(path)
+    end
+
+    unless zf.find(COVER_PATH)
+      raise MissingCoverPNG.new(path)
+    end
+
+    doc = Nokogiri::HTML::Document.parse(zf.read(INDEX_PATH), nil, 'UTF-8')
+    raise IndexHTMLRootHasId.new(path)  if doc.root['id']
+
+  ensure
+    zf.close  if zf
+  end
+
+
+  # Unzips the file at path, generates a simple book object, passes to new.
+  #
+  def self.read(path)
+    validate(path)
+    book = Peregrin::Book.new
+    Zip::Archive.open(path) { |zf|
+      book.add_component(INDEX_PATH, zf.read(INDEX_PATH))
+      zf.each { |entry|
+        ze = entry.name
+        book.add_resource(ze)  unless ze == INDEX_PATH || entry.directory?
+      }
+    }
+    book.read_resource_proc = lambda { |resource|
+      Zip::Archive.open(path) { |zipfile|
+        zipfile.read(resource.src)
+      }
+    }
+
+    extract_properties_from_index(book)
+
+    new(book)
+  end
+
+
+  # Stitches together components of the internal book.
+  #
+  def initialize(book)
+    @book = book
+
+    if @book.components.length > 1
+      stitch_components(@book)
+    end
+
+    consolidate_properties(@book)
+
+    @book.chapters = outline_book(index)
+
+    @book.cover ||= (
+      @book.resources.detect { |r| r.src == COVER_PATH } ||
+      @book.add_resource(COVER_PATH)
+    )
+  end
+
+
+  # Writes the internal book object to a .zhook file at the given path.
+  #
+  def write(path)
+    File.unlink(path)  if File.exists?(path)
+    Zip::Archive.open(path, Zip::CREATE) { |zipfile|
+      zipfile.add_buffer(INDEX_PATH, htmlize(index))
+      @book.resources.each { |resource|
+        zipfile.add_buffer(resource.src, @book.read_resource(resource))
+      }
+      unless @book.cover.src == COVER_PATH
+        zipfile.add_buffer(COVER_PATH, to_png_data(@book.cover))
+      end
+    }
+    path
+  end
+
+
+  # Returns the internal book object.
+  #
+  def to_book(options = {})
+    bk = @book.deep_clone
+
+    # XPath => URI mapping tools
+    cmpt_xpaths = []
+
+    boilerplate_rel_links =
+      '<link rel="start" href="cover.html" />' +
+      '<link rel="contents" href="toc.html" />'
+
+    # Componentizing.
+    if options[:componentize]
+      componentizer = Peregrin::Componentizer.new(index)
+      componentizer.process(index.root.at_css('body'))
+      bk.components = componentizer.component_xpaths.collect { |xpath|
+        cmpt_xpaths.push(xpath)
+        doc = componentizer.generate_component(xpath)
+        Peregrin::Component.new(uri_for_xpath(xpath, cmpt_xpaths), doc)
+      }
+
+      # 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+'" />'
+      bk.components.each_with_index { |cmpt, i|
+        head = cmpt.contents.at_xpath(HEAD_XPATH)
+        prev_path = bk.components[i-1].src  if (i-1) >= 0
+        next_path = bk.components[i+1].src  if (i+1) < bk.components.size
+        head.add_child(boilerplate_rel_links)
+        head.add_child('<link rel="prev" href="'+prev_path+'" />')  if prev_path
+        head.add_child('<link rel="next" href="'+next_path+'" />')  if next_path
+        cmpt.contents = htmlize(cmpt.contents)
+      }
+    else
+      cmpt_xpaths.push(BODY_XPATH)
+      bk.components.clear
+      bk.add_component(uri_for_xpath(BODY_XPATH), htmlize(index))
+    end
+
+    # Outlining.
+    bk.chapters = outline_book(index, cmpt_xpaths)
+
+    if options[:componentize]
+      # Table of Contents
+      doc = Nokogiri::HTML::Builder.new(:encoding => 'UTF-8') { |html|
+        curse = lambda { |children|
+          parts = children.collect { |chp|
+            chp.empty_leaf? ? nil : [chp.title, chp.src, chp.children]
+          }.compact
+
+          html.ol {
+            parts.each { |part|
+              html.li {
+                html.a(part[0], :href => part[1])
+                curse.call(part[2])  if part[2].any?
+              }
+            }
+          }  if parts.any?
+        }
+        curse.call(bk.chapters)
+      }.doc
+      if doc.root
+        toc_doc = componentizer.generate_document(doc.root)
+        toc_doc.at_xpath(HEAD_XPATH).add_child(boilerplate_rel_links)
+        bk.add_component(
+          "toc.html",
+          htmlize(toc_doc),
+          nil,
+          :linear => "no",
+          :guide => "Table of Contents",
+          :guide_type => "toc"
+        )
+      end
+
+      # List of Illustrations
+      figures = index.css('figure[id], div.figure[id]')
+      if figures.any?
+        doc = Nokogiri::HTML::Builder.new(:encoding => 'UTF-8') { |html|
+          html.ol {
+            figures.each { |fig|
+              next  unless caption = fig.at_css('figcaption, .figcaption')
+              n = fig
+              while n && n.respond_to?(:parent)
+                break if cmpt_uri = uri_for_xpath(n.path, cmpt_xpaths)
+                n = n.parent
+              end
+              next  unless cmpt_uri
+              html.li {
+                html.a(caption.content, :href => "#{cmpt_uri}##{fig['id']}")
+              }
+            }
+          }
+        }.doc
+        loi_doc = componentizer.generate_document(doc.root)
+        loi_doc.at_xpath(HEAD_XPATH).add_child(boilerplate_rel_links)
+        bk.add_component(
+          "loi.html",
+          htmlize(loi_doc),
+          nil,
+          :linear => "no",
+          :guide => "List of Illustrations",
+          :guide_type => "loi"
+        )
+      end
+
+      # Cover
+      doc = Nokogiri::HTML::Builder.new(:encoding => 'UTF-8') { |html|
+        html.div(:id => "cover") {
+          html.img(:src => bk.cover.src, :alt => bk.property_for("title"))
+        }
+      }.doc
+      cover_doc = componentizer.generate_document(doc.root)
+      cover_doc.at_xpath(HEAD_XPATH).add_child(boilerplate_rel_links)
+      bk.components.unshift(
+        Peregrin::Component.new(
+          "cover.html",
+          htmlize(cover_doc),
+          nil,
+          :linear => "no",
+          :guide => "Cover",
+          :guide_type => "cover"
+        )
+      )
+    end
+
+    bk
+  end
+
+
+  protected
+
+    def index
+      @index_document ||= Nokogiri::HTML::Document.parse(
+        @book.components.first.contents
+      )
+    end
+
+
+    # Takes a book with multiple components and joins them together,
+    # by creating article elements from every body element and appending them
+    # to the body of the first component.
+    #
+    def stitch_components(book)
+      node = Nokogiri::XML::Node.new('article', index)
+      bdy = index.at_xpath(BODY_XPATH)
+      head = index.at_xpath(HEAD_XPATH)
+      bdy.children.each { |ch|
+        node.add_child(ch)
+      }
+      bdy.add_child(node)
+
+      book.components.shift
+      while cmpt = book.components.shift
+        str = cmpt.contents
+        doc = Nokogiri::HTML::Document.parse(str)
+        art = doc.at_xpath(BODY_XPATH)
+        art.name = 'article'
+        bdy.add_child(art)
+
+        # Import all other unique elements from the head, like link & meta tags.
+        if dhead = doc.at_xpath(HEAD_XPATH)
+          dhead.children.each { |foreign_child|
+            next  if foreign_child.name.downcase == "title"
+            next  if head.children.any? { |index_child|
+              index_child.to_s == foreign_child.to_s
+            }
+            head.add_child(foreign_child.dup)
+          }
+        end
+      end
+      book.components.clear
+      book.add_component(uri_for_xpath(BODY_XPATH), htmlize(index))
+    end
+
+
+    # Takes the properties out of the book and ensures that there are matching
+    # meta tags in the index document.
+    #
+    def consolidate_properties(book)
+      head = index.at_xpath('/html/head')
+      head.css('meta[name]').each { |meta| meta.remove }
+      book.properties.each { |property|
+        # FIXME: handle properties with attributes?
+        meta = Nokogiri::XML::Node.new('meta', index)
+        meta['name'] = property.key
+        meta['content'] = property.value
+        head.add_child(meta)
+      }
+    end
+
+
+    def outline_book(doc, cmpt_xpaths = [BODY_XPATH])
+      unless defined?(@outliner) && @outliner
+        @outliner = Peregrin::Outliner.new(doc)
+        @outliner.process(doc.at_css('body'))
+      end
+
+      i = 0
+      curse = lambda { |sxn|
+        chapter = Peregrin::Chapter.new(sxn.heading_text, i+=1)
+
+        # identify any relevant child sections
+        children = sxn.sections.collect { |ch|
+          curse.call(ch) unless ch.empty?
+        }.compact
+        chapter.children = children  if children.any?
+
+        # Find the component parent
+        n = sxn.node || sxn.heading
+        while n && n.respond_to?(:parent)
+          break if cmpt_uri = uri_for_xpath(n.path, cmpt_xpaths)
+          n = n.parent
+        end
+
+        if cmpt_uri
+          # get URI for section
+          sid = sxn.heading['id']  if sxn.heading
+          cmpt_uri += "#"+sid  if sid && !sid.empty?
+          chapter.src = cmpt_uri
+        end
+
+        chapter
+      }
+
+      result = curse.call(@outliner.result_root).children
+      while result && result.length == 1 && result.first.title.nil?
+        result = result.first.children
+      end
+      result
+    end
+
+
+    def uri_for_xpath(xpath, cmpt_xpaths = [BODY_XPATH])
+      return nil  unless cmpt_xpaths.include?(xpath)
+      i = cmpt_xpaths.index(xpath)
+      (i == 0) ? "index.html" : "part#{"%03d" % i}.html"
+    end
+
+
+    def htmlize(doc)
+      "<!DOCTYPE html>\n"+doc.root.to_html
+    end
+
+
+    def to_png_data(resource)
+      return  if resource.nil?
+      if File.extname(resource.src) == ".png"
+        return @book.read_resource(resource)
+      else
+        raise ConvertUtilityMissing  unless `which convert`
+        out = nil
+        IO.popen("convert - png:-", "r+") { |io|
+          io.write(@book.read_resource(resource))
+          io.close_write
+          out = io.read
+        }
+        out
+      end
+    end
+
+
+    def self.extract_properties_from_index(book)
+      doc = Nokogiri::HTML::Document.parse(
+        book.components.first.contents
+      )
+      doc.css('html head meta[name]').each { |meta|
+        name = meta['name']
+        content = meta['content']
+        book.add_property(name, content)
+      }
+    end
+
+
+  class ValidationError < ::RuntimeError
+
+    def initialize(path = nil)
+      @path = path
+    end
+
+  end
+
+  class FileNotFound < ValidationError; end
+  class WrongExtension < ValidationError; end
+  class NotAZipArchive < ValidationError; end
+  class MissingIndexHTML < ValidationError; end
+  class MissingCoverPNG < ValidationError; end
+  class IndexHTMLRootHasId < ValidationError; end
+
+  class ConvertUtilityMissing < RuntimeError; end
+
+end

data/lib/peregrin/book.rb

@@ -0,0 +1,87 @@
+class Peregrin::Book
+
+  # Unique identifier for this book
+  attr_accessor :identifier
+
+  # An array of Components
+  attr_accessor :components
+
+  # A tree of Chapters. Top-level chapters in this array, each with
+  # children arrays.
+  attr_accessor :chapters
+
+  # An array of Properties.
+  attr_accessor :properties
+
+  # An array of Resources.
+  attr_accessor :resources
+
+  # A Resource that is used for the book cover.
+  attr_accessor :cover
+
+  # A proc that copies a resource to the given destination.
+  attr_writer :read_resource_proc
+
+
+  def initialize
+    @components = []
+    @chapters = []
+    @properties = []
+    @resources = []
+  end
+
+
+  def all_files
+    @components + @resources
+  end
+
+
+  def add_component(*args)
+    @components.push(Peregrin::Component.new(*args)).last
+  end
+
+
+  def add_resource(*args)
+    @resources.push(Peregrin::Resource.new(*args)).last
+  end
+
+
+  def add_chapter(*args)
+    @chapters.push(Peregrin::Chapter.new(*args)).last
+  end
+
+
+  def add_property(*args)
+    @properties.push(Peregrin::Property.new(*args)).last
+  end
+
+
+  def property_for(key)
+    key = key.to_s
+    prop = @properties.detect { |p| p.key == key }
+    prop ? prop.value : nil
+  end
+
+
+  def read_resource(resource_path)
+    @read_resource_proc.call(resource_path)  if @read_resource_proc
+  end
+
+
+  def copy_resource_to(resource_path, dest_path)
+    File.open(dest_path, 'w') { |f|
+      f << read_resource(resource_path)
+    }
+  end
+
+
+  def deep_clone
+    @read_resource_proc ||= nil
+    tmp = @read_resource_proc
+    @read_resource_proc = nil
+    clone = Marshal.load(Marshal.dump(self))
+    clone.read_resource_proc = @read_resource_proc = tmp
+    clone
+  end
+
+end

data/lib/peregrin/chapter.rb

@@ -0,0 +1,31 @@
+# Books have nested sections with headings - each of these is a chapter.
+#
+# TODO: flag whether a chapter is linkable?
+#
+class Peregrin::Chapter
+
+  attr_accessor :title, :src, :children, :position
+
+  def initialize(title, pos, src = nil)
+    @title = title.gsub(/[\r\n]/,' ')  if title
+    @src = src
+    @position = pos.to_i
+    @children = []
+  end
+
+
+  def add_child(child_title, child_pos, child_src = nil)
+    chp = Peregrin::Chapter.new(child_title, child_pos, child_src)
+    children.push(chp)
+    chp
+  end
+
+
+  # A chapter is an empty leaf if you can't link to it or any of its children.
+  # Typically you wouldn't show an empty-leaf chapter in a Table of Contents.
+  #
+  def empty_leaf?
+    src.nil? && children.all? { |ch| ch.empty_leaf? }
+  end
+
+end

data/lib/peregrin/component.rb

@@ -0,0 +1,12 @@
+# A component is a section of the book's linear text.
+#
+class Peregrin::Component < Peregrin::Resource
+
+  attr_accessor :contents
+
+  def initialize(src, contents = nil, media_type = nil, attributes = {})
+    @contents = contents
+    super(src, media_type, attributes)
+  end
+
+end

data/lib/peregrin/componentizer.rb

@@ -0,0 +1,118 @@
+class Peregrin::Componentizer
+
+  attr_reader :component_xpaths
+
+
+  def initialize(doc)
+    @document = doc
+    @component_xpaths = []
+  end
+
+
+  # Build a list of xpaths for nodes that can be turned into standalone
+  # components.
+  #
+  def process(from)
+    @component_xpaths = []
+    walk(from)
+    @component_xpaths.reject! { |xpath| emptied?(xpath) }
+  end
+
+
+  def generate_component(xpath)
+    raise "Not a component: #{xpath}"  unless @component_xpaths.include?(xpath)
+    node = @document.at_xpath(xpath)
+    generate_document(node)
+  end
+
+
+  # Creates a new document with the same root and head nodes, but with
+  # a body that just contains the nodes at the given xpath.
+  #
+  def generate_document(node)
+    # Clean up the "shell" document.
+    @shell_document ||= @document.dup
+    bdy = @shell_document.at_xpath('/html/body')
+    bdy.children.remove
+
+    # Find the node we're going to copy into the shell document.
+    # Create a deep clone of it. Remove any children of it that are
+    # componentizable in their own right.
+    ndup = node.dup
+    node.children.collect { |ch|
+      next  unless component_xpaths.include?(ch.path)
+      dpath = ch.path.sub(/^#{Regexp.escape(node.path)}/, ndup.path)
+      ndup.children.detect { |dch| dch.path == dpath }
+    }.compact.each { |ch|
+      ch.unlink
+    }
+
+    # Append the node to the body of the shell (or replace the body, if
+    # the node is a body itself).
+    if node.name.downcase == "body"
+      bdy.replace(ndup)
+    else
+      bdy.add_child(ndup)
+    end
+
+    @shell_document.dup
+  end
+
+
+  # Writes the componentizable node at the given xpath to the given
+  # filesystem path.
+  #
+  # If you provide a block, you get the new document object,
+  # and you are expected to return the string containing its HTML form --
+  # in this way you can tweak the HTML output. Default is simply: doc.to_html
+  #
+  def write_component(xpath, path, &blk)
+    new_doc = generate_component(xpath)
+    out = block_given? ? blk.call(new_doc) : new_doc.to_html
+    File.open(path, 'w') { |f| f.write(out) }
+    out
+  end
+
+
+  protected
+
+    # The recursive method for walking the tree - checks if the current node
+    # is a component, then checks each child of the current node.
+    #
+    def walk(node)
+      return  unless componentizable?(node)
+      @component_xpaths.push(node.path)
+      node.children.each { |c| walk(c) }
+    end
+
+
+    # True if the node meets the criteria for being componentizable:
+    #   1) Is a body or article element (or a div.article)?
+    #   2) Are all subsequent siblings also componentizable?
+    #
+    def componentizable?(node)
+      begin
+        return false  unless (
+          %w[body article].include?(node.name.downcase) ||
+          (
+            node.name.downcase == "div" &&
+            node['class'] &&
+            node['class'].match(/\barticle\b/)
+          )
+        )
+      end while node = node.next
+      true
+    end
+
+
+    # True if all children are either componentizable or blank text nodes.
+    #
+    def emptied?(xpath)
+      node = @document.at_xpath(xpath)
+      node.children.all? { |ch|
+        @component_xpaths.include?(ch.path) ||
+        (ch.text? && ch.content.strip.empty?)
+      }
+    end
+
+end