bookbinder 0.2.0

data/lib/bookbinder/media_type.rb

@@ -0,0 +1,17 @@
+require 'mime/types'
+
+module Bookbinder::MediaType
+
+  MEDIA_TYPES = {
+    '.ncx' => 'application/x-dtbncx+xml',
+    '.opf' => 'application/oebps-package+xml',
+    '.smil' => 'application/smil+xml'
+  }
+
+
+  def self.of(path)
+    ext = File.extname(path)
+    MEDIA_TYPES[ext] || MIME::Types.of(ext).first.to_s || 'text/plain'
+  end
+
+end

data/lib/bookbinder/operations.rb

@@ -0,0 +1,59 @@
+class Bookbinder::Operations
+
+  class << self
+
+    # This inspects a path and gives you the package class that
+    # probably can read or write it.
+    #
+    def recognize(path)
+      ObjectSpace.each_object(Class).detect { |klass|
+        klass < Bookbinder::Package && klass.recognize(path)
+      } || raise(Bookbinder::UnknownFormat, path)
+    end
+
+
+    def map(path)
+      JSON.pretty_generate(validate(path).map)
+    end
+
+
+    def validate(path)
+      pkg_klass = recognize(path)
+      pkg = pkg_klass.read(path)
+      # TODO: emit warnings?
+      pkg
+    end
+
+
+    # This will REPLACE the ebook with itself, after
+    # POSSIBLY LOSSY parsing by Bookbinder. Be careful!
+    # If you want to copy-and-normalize, use convert.
+    #
+    def normalize(path)
+      pkg_klass = recognize(path)
+      pkg = pkg_klass.read(path)
+      pkg.write(path)
+      pkg
+    end
+
+
+    # This will take the ebook at src_path, map it, then convert it
+    # to the format recognized in dest_path. Be aware that ANYTHING
+    # already at dest_path will be replaced.
+    #
+    def convert(src_path, dest_path)
+      src_klass = recognize(src_path)
+      dest_klass = recognize(dest_path)
+      src_pkg = src_klass.read(src_path)
+      dest_pkg = src_pkg.export(dest_klass)
+      dest_pkg.write(dest_path)
+      [src_pkg, dest_pkg]
+    end
+
+  end
+
+
+
+  class Bookbinder::UnknownFormat < RuntimeError; end
+
+end

data/lib/bookbinder/package/epub.rb

@@ -0,0 +1,69 @@
+class Bookbinder::Package::EPUB < Bookbinder::Package
+
+  require_transforms('epub')
+
+  DEFAULT_TRANSFORMS = [
+    Bookbinder::Transform::EPUB_PackageIdentifier,
+    Bookbinder::Transform::EPUB_Title,
+    Bookbinder::Transform::EPUB_Creator,
+    Bookbinder::Transform::EPUB_Contributor,
+    Bookbinder::Transform::EPUB_Language,
+    Bookbinder::Transform::EPUB_CoverImage,
+    Bookbinder::Transform::EPUB_Description,
+    Bookbinder::Transform::EPUB_Version,
+    Bookbinder::Transform::EPUB_Spine,
+    Bookbinder::Transform::EPUB_Resources,
+    Bookbinder::Transform::EPUB_NavToc,
+    Bookbinder::Transform::EPUB_CoverPage,
+    Bookbinder::Transform::EPUB_Rendition,
+    Bookbinder::Transform::EPUB_AudioOverlay,
+    Bookbinder::Transform::Organizer,
+    Bookbinder::Transform::Generator
+  ]
+
+  DEFAULT_CONTENT_ROOT = 'EPUB'
+
+
+  def self.recognize(path)
+    return (
+      File.extname(path).downcase == '.epub' ||
+      File.directory?(File.join(path, 'META-INF'))
+    )
+  end
+
+
+  def self.transforms
+    @transforms = DEFAULT_TRANSFORMS
+  end
+
+
+  def transforms
+    self.class.transforms
+  end
+
+
+  def make_id(path)
+    path.gsub(/[^\w]/, '-')
+  end
+
+
+  def make_path(href)
+    CGI.unescape(href)
+  end
+
+
+  def make_href(path)
+    CGI.escape(path)
+  end
+
+
+  protected
+
+    # Overriding this Package method to inject EPUB's mimetype file.
+    #
+    def write_to_file_system(dest_file_system)
+      dest_file_system.write('mimetype', 'application/epub+zip')
+      super
+    end
+
+end

data/lib/bookbinder/package/openbook.rb

@@ -0,0 +1,33 @@
+class Bookbinder::Package::Openbook < Bookbinder::Package
+
+  require_transforms('openbook')
+
+  DEFAULT_CONTENT_ROOT = ''
+  attr_accessor(:mip)
+
+
+  def self.recognize(path)
+    ext = File.extname(path).downcase
+    return (
+      ext == '.openbook' ||
+      File.exists?(File.join(path, 'book.json')) ||
+      (ext.empty? && !File.exists?(path))
+    )
+  end
+
+
+  def transforms
+    [
+      Bookbinder::Transform::Generator,
+      Bookbinder::Transform::Openbook_JSON
+    ]
+  end
+
+
+  def from_map
+    @mip = duplicate_map(@map)
+    super
+  end
+
+
+end

data/lib/bookbinder/package.rb

@@ -0,0 +1,295 @@
+class Bookbinder::Package
+
+  attr_accessor(:file_system, :map, :content_root, :file_aliases, :options)
+  attr_reader(:warnings)
+
+
+  # In subclasses, return true if you can handle the path.
+  # We'll iterate through all the descendent classes of
+  # Package and return the first matching class.
+  #
+  def self.recognize(path)
+    # IMPLEMENT IN SUBCLASSES
+  end
+
+
+  # This will require() all the .rb files within the given subdirectory
+  # of 'bookbinder/transform'. So, for the EPUB package, you'd just call:
+  #
+  #   require_transforms('epub')
+  #
+  # ... to load all the EPUB-specific transforms.
+  #
+  def self.require_transforms(dir)
+    Dir.glob(
+      File.join(File.dirname(__FILE__), 'transform', dir, '*.rb')
+    ).each { |rb|
+      require("bookbinder/transform/#{dir}/#{File.basename(rb, '.rb')}")
+    }
+  end
+
+
+  # Creates a new package of this class pointing at the given
+  # path (but not reading from it automatically).
+  #
+  def self.build(path)
+    new.tap { |pkg|
+      pkg.build(path)
+    }
+  end
+
+
+  # Creates a new package of this class by reading content
+  # from a path.
+  #
+  def self.read(path)
+    new.tap { |pkg|
+      pkg.read(path)
+    }
+  end
+
+
+  def initialize
+    @content_root = ''
+    @file_aliases = {}
+    @options = {}
+    @files = {}
+    reset_transforms
+  end
+
+
+  # Prepares this package for mapping the contents of
+  # the given path.
+  #
+  def build(path)
+    @map = {}
+    @file_system = file_system_from_path(path)
+  end
+
+
+  # Reads the path and generates a hash "map" of the book,
+  # returning it.
+  #
+  def read(path)
+    build(path)
+    to_map
+    @map
+  end
+
+
+  # Creates a new package of the given class, using
+  # our map and file_system, and returns it.
+  #
+  def export(package_class)
+    package_class.new.import(map, file_system, content_root, options)
+  end
+
+
+  # Copies state: a map, a file-system, and a content root.
+  # That should be enough to be a fully independent package.
+  #
+  def import(map, file_system, content_root, options)
+    @map = duplicate_map(map)
+    @file_system = file_system
+    @content_root = content_root
+    @options = options.clone
+    self
+  end
+
+
+  # Copy all components and resources in the map to the new file system,
+  # then creates a new temporary package based on this one and yields it.
+  #
+  # We create a new temporary package rather than using the current one
+  # so that we can have a different file system (and a different content
+  # root if we want that, and fresh hashes for `files`, `file_aliases`,
+  # etc).
+  #
+  def copy_to(path_or_file_system, content_root)
+    dest_file_system = path_or_file_system
+    if path_or_file_system.kind_of?(String)
+      dest_file_system = file_system_from_path(dest_file_system)
+    end
+    all_book_content.each { |ref|
+      rsrc = file(ref['path'])
+      dest_path = ref['path']
+      if content_root && !content_root.empty?
+        dest_path = File.join(content_root, dest_path)
+        dest_path = File.expand_path(dest_path, '/')[1..-1]
+      end
+      rsrc.copy_to(dest_file_system, dest_path)
+    }
+    self.class.new.tap { |pkg|
+      pkg.import(@map, dest_file_system, content_root, @options)
+    }
+  end
+
+
+  def all_book_content
+    book_content = []
+    book_content += map['cover'].values  if map['cover']
+    book_content += map['spine']  if map['spine']
+    book_content += map['resources']  if map['resources']
+    book_content
+  end
+
+
+  # Writes package to path. This is destructive! Anything already
+  # at the path will be replaced.
+  #
+  def write(path)
+    tmp_path = Dir::Tmpname.create(File.basename(path)) { |tmp_path|
+      raise Errno::EEXIST  if File.exists?(tmp_path)
+    }
+    dest_fs = file_system_from_path(tmp_path)
+    write_to_file_system(dest_fs)
+    dest_fs.close  if dest_fs.respond_to?(:close)
+    FileUtils.rm_r(path)  if File.exists?(path)
+    FileUtils.move(tmp_path, path)
+  end
+
+
+  # Returns a file object for the given path within this package --
+  # by default, the path is from this package's content_root.
+  #
+  def file(path, root_path = @content_root)
+    if full_path = file_path(path, root_path)
+      @files[full_path] ||= Bookbinder::File.new(full_path, @file_system)
+    else
+      nil
+    end
+  end
+
+
+  # Returns the fully-resolved path to a file within this package,
+  # converting aliases and applying the content_root if appropriate.
+  #
+  def file_path(path, root_path = @content_root)
+    path = file_aliases[path]  if file_aliases[path]
+    if path.kind_of?(Symbol)
+      nil
+    else
+      path = File.join(root_path, path)  if root_path && !root_path.empty?
+      path = File.expand_path(path, '/')[1..-1]
+      path
+    end
+  end
+
+
+  # Yields the file only if it exists.
+  #
+  def if_file(*file_args)
+    f = file(*file_args)
+    yield(f)  if f && f.exists?
+  end
+
+
+  # The list of transforms to be applied when mapping or writing
+  # this package.
+  #
+  def transforms
+    # IMPLEMENT IN SUBCLASSES
+    []
+  end
+
+
+  # This is the default "to_map" behavior, but feel free to
+  # override it in subclasses.
+  #
+  def to_map
+    transforms.each { |transform_class|
+      apply_transform(:to_map, transform_class)
+    }
+  end
+
+
+  # This is the default "from_map" behavior, but feel free to
+  # override it in subclasses.
+  #
+  def from_map
+    transforms.each { |transform_class|
+      apply_transform(:from_map, transform_class)
+    }
+  end
+
+
+  # Applies the given transform by instantiating the class
+  # and invoking the specified method on it. `mthd` should
+  # be either `to_map` or `from_map`.
+  #
+  # Runs all dependencies (that have not already run) first.
+  #
+  def apply_transform(mthd, transform_class)
+    run = @transformed[mthd] ||= []
+    return  if run.include?(transform_class)
+    run.push(transform_class)
+    transform = transform_class.new
+    transform.dependencies.each { |dep| apply_transform(mthd, dep) }
+    if transform.respond_to?(mthd)
+      # puts("[TRANSFORM] #{transform_class}##{mthd}")
+      @transform = transform
+      @transform_method = mthd
+      @transform.send(mthd, self)
+      @transform = nil
+      @transform_method = nil
+    end
+  end
+
+
+  def reset_transforms
+    @warnings = []
+    @transformed = {}
+  end
+
+
+  def warn(msg)
+    @warnings.push({
+      :transform => @transform.class,
+      :method => @transform_method,
+      :message => msg
+    })
+    nil
+  end
+
+
+  # Any file that is marked 'dirty' (because it has been opened
+  # in 'w' mode) will be written out to its file-system.
+  #
+  def save_open_files
+    @files.each_value { |file| file.save }
+  end
+
+
+  protected
+
+    # Inspects the path string to choose a filesystem.
+    # Override this in subclasses if the logic is inadequate.
+    #
+    def file_system_from_path(path)
+      if File.directory?(path) || File.extname(path).empty?
+        Bookbinder::FileSystem::Directory.new(path)
+      else
+        Bookbinder::FileSystem::ZipFile.new(path)
+      end
+    end
+
+
+    # Creates a new package with the default content root for this
+    # package class, and invokes `from_map` on it, which will write
+    # it out to the given file system.
+    def write_to_file_system(dest_file_system)
+      new_content_root = self.class::DEFAULT_CONTENT_ROOT
+      copy_to(dest_file_system, new_content_root).tap { |pkg|
+        # Apply all our transforms.
+        pkg.from_map
+        # Save all the open files.
+        pkg.save_open_files
+      }
+    end
+
+
+    def duplicate_map(src_map)
+      JSON.load(JSON.dump(src_map))
+    end
+
+end

data/lib/bookbinder/transform/epub/audio_overlay.rb

@@ -0,0 +1,227 @@
+# EPUB 3 only. Spec:
+#
+#   http://www.idpf.org/epub/301/spec/epub-mediaoverlays.html#sec-package-metadata
+#
+# Each spine item's manifest item may have a media-overlay attribute, which
+# is an idref pointing at a SMIL manifest item.
+#
+# Other properties to manage:
+#
+#   <meta property="media:active-class">-epub-media-overlay-active</meta>
+#   <meta property="media:playback-active-class">-epub-media-overlay-playing</meta>
+#   <meta property="media:duration" refines="#ch1_audio">0:32:29</meta>
+#   <meta property="media:duration">1:36:20</meta>
+#   <meta property="media:narrator">Bill Speaker</meta>
+#
+# Note: "The Package Document must include the duration of each
+# Media Overlay as well as of the entire Publication."
+#
+class Bookbinder::Transform::EPUB_AudioOverlay < Bookbinder::Transform
+
+  def dependencies
+    [
+      Bookbinder::Transform::EPUB_Metadata,
+      Bookbinder::Transform::EPUB_Resources,
+      Bookbinder::Transform::EPUB_Spine
+    ]
+  end
+
+
+  def to_map(package)
+    meta_to_prop(
+      package,
+      'media:active-class',
+      'audio-overlay-active-class'
+    )
+    meta_to_prop(
+      package,
+      'media:playback-active-class',
+      'audio-overlay-playback-active-class'
+    )
+    book_overlay_duration = meta_to_prop(
+      package,
+      'media:duration',
+      'audio-overlay-duration'
+    ) { |hashes|
+      hashes.detect { |hash|
+        unless hash.has_key?('refines')
+          hash['@'] = smil_clock_value_to_seconds(hash['@'])
+          true
+        end
+      }
+    }
+    # TODO: check that book does have a duration if there are any overlays.
+    meta_to_prop(
+      package,
+      'media:narrator',
+      'audio-overlay-narrator'
+    ) { |hashes|
+      hashes.detect { |hash| !hash.has_key?('refines') }
+    }
+    # Find each manifest item (SI) with media-overlay attribute:
+    #
+    #   - find the map['resources'] item that matches the media-overlay id
+    #   - find the map['spine'] item that matches the SI id
+    #     - set 'audio-overlay' to the AO path
+    #     - set 'audio-overlay-duration' to the refined duration
+    #     - set 'audio-overlay-narrator' to the refined narrator
+    #
+    opf_doc = package.file(:opf).document('r')
+    opf_doc.each('opf|manifest > opf|item[media-overlay]') { |cmpt_item|
+      cmpt_id = cmpt_item['id']
+      cmpt = package.map['spine'].detect { |c| c['id'] == cmpt_id }
+      # TODO: nil check cmpt
+      ao_id = cmpt_item['media-overlay']
+      rsrc = package.map['resources'].detect { |r| r['id'] == ao_id }
+      # TODO: nil check rsrc
+      cmpt['audio-overlay'] = rsrc['path']
+      cmpt_overlay_duration = meta_to_prop(
+        package,
+        'media:duration',
+        'audio-overlay-duration',
+        cmpt
+      ) { |hashes|
+        hashes.detect { |hash|
+          if hash['refines']['@'] == '#'+ao_id
+            hash['@'] = smil_clock_value_to_seconds(hash['@'])
+            true
+          end
+        }
+      }
+      # TODO: nil check cmpt_overlay_duration
+      meta_to_prop(
+        package,
+        'media:narrator',
+        'audio-overlay-narrator',
+        cmpt
+      ) { |hashes|
+        hash['refines']['@'] == '#'+ao_id
+      }
+    }
+  end
+
+
+  # Create a meta tag for:
+  #   audio-overlay-active-class => media:active-class
+  #   audio-overlay-playback-active-class => media:playback-active-class
+  #   audio-overlay-duration => media:duration
+  #   audio-overlay-narrator => media:narrator
+  #
+  # For each spine item with a 'media-overlay' key:
+  #
+  #   Find the corresponding map resource
+  #   Find the corresponding manifest item for component:
+  #     - set 'media-overlay' to rsrc['id']
+  #   Create a top-level meta tag:
+  #     cmpt['audio-overlay-duration'] => meta[property='media:duration'][refines='rsrc["id"]]
+  #   Also create a top-level meta tag for media:narrator if cmpt has 'audio-overlay-narrator'
+  #
+  def from_map(package)
+    opf_doc = package.file(:opf).document
+    metadata_tag = opf_doc.find('opf|metadata')
+    prop_to_meta(
+      package.map,
+      metadata_tag,
+      'audio-overlay-active-class',
+      'media:active-class'
+    )
+    prop_to_meta(
+      package.map,
+      metadata_tag,
+      'audio-overlay-playback-active-class',
+      'media:playback-active-class'
+    )
+    prop_to_meta(
+      package.map,
+      metadata_tag,
+      'audio-overlay-duration',
+      'media:duration'
+    )
+    prop_to_meta(
+      package.map,
+      metadata_tag,
+      'audio-overlay-narrator',
+      'media:narrator'
+    )
+    package.map['spine'].each { |cmpt|
+      next  unless cmpt['audio-overlay']
+      rsrc = package.map['resources'].detect { |r|
+        r['path'] == cmpt['audio-overlay']
+      }
+      cmpt_manifest_item = opf_doc.find("opf|manifest > opf|item##{cmpt['id']}")
+      cmpt_manifest_item['media-overlay'] = rsrc['id']
+      duration_meta_tag = prop_to_meta(
+        cmpt,
+        metadata_tag,
+        'audio-overlay-duration',
+        'media:duration'
+      )
+      duration_meta_tag['refines'] = '#'+rsrc['id']
+      narrator_meta_tag = prop_to_meta(
+        cmpt,
+        metadata_tag,
+        'audio-overlay-narrator',
+        'media:narrator'
+      )
+      narrator_meta_tag['refines'] = '#'+rsrc['id']  if narrator_meta_tag
+    }
+  end
+
+
+  protected
+
+    def meta_to_prop(package, meta_name, prop_name, target = nil)
+      return  unless package.map['metadata']
+      hashes = package.map['metadata'][meta_name]
+      return  unless hashes && hashes.any?
+      hash = block_given? ? yield(hashes) : hashes.first
+      if hash
+        hashes.delete(hash)
+        package.map['metadata'].delete(meta_name)  if hashes.empty?
+        (target || package.map)[prop_name] = hash['@']
+      end
+    end
+
+
+    # 5:34:31.396 = 5 hours, 34 minutes, 31 seconds and 396 milliseconds
+    # 124:59:36 = 124 hours, 59 minutes and 36 seconds
+    # 0:05:01.2 = 5 minutes, 1 second and 200 milliseconds
+    # 0:00:04 = 4 seconds
+    # 09:58 = 9 minutes and 58 seconds
+    # 00:56.78 = 56 seconds and 780 milliseconds
+    # 76.2s = 76.2 seconds = 76 seconds and 200 milliseconds
+    # 7.75h = 7.75 hours = 7 hours and 45 minutes
+    # 13min = 13 minutes
+    # 2345ms = 2345 milliseconds
+    # 12.345 = 12 seconds and 345 milliseconds
+    def smil_clock_value_to_seconds(clock)
+      return clock.to_f  if clock.kind_of?(Numeric)
+      clock = clock.to_s
+      if match = clock.match(/(\d+:)?(\d+:)(\d+\.?\d*)/)
+        h = match[1].to_s.to_f
+        m = match[2].to_s.to_f
+        s = match[3].to_s.to_f
+        h*60*60 + m*60 + s
+      elsif match = clock.match(/^(\d+\.?\d*)h$/)
+        match[1].to_f*60*60
+      elsif match = clock.match(/^(\d+\.?\d*)min$/)
+        match[1].to_f*60
+      elsif match = clock.match(/^(\d+\.?\d*)s?$/)
+        clock.to_f
+      elsif match = clock.match(/^(\d+\.?\d*)ms$/)
+        clock.to_f / 1000.0
+      end
+    end
+
+
+    def prop_to_meta(scope, metadata_tag, prop_name, meta_name)
+      if scope[prop_name]
+        meta_tag = Nokogiri::XML::Node.new('meta', metadata_tag)
+        meta_tag['property'] = meta_name
+        meta_tag.content = scope[prop_name]
+        metadata_tag.add_child(meta_tag)
+        return meta_tag
+      end
+    end
+
+end