epub-rb 0.0.0

data/lib/epub/epub.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Epub
+  class Epub
+    # Root directory, so we can get the relative path for `:files`.
+    #
+    attr_accessor :root_dir
+
+    # EPUB spec version engine. Only EPUBv3 is supported.
+    #
+    attr_accessor :epub_engine
+
+    # The book's title.
+    #
+    attr_accessor :title
+
+    # The book's subtitle.
+    #
+    attr_accessor :subtitle
+
+    # The list of files that will be package.
+    # Must include everything (fonts, stylesheets, videos, etc).
+    #
+    attr_reader :files
+
+    # The path to the cover image (can be .png or .jpg).
+    #
+    attr_accessor :cover_image
+
+    # The epub identifier.
+    # This must be a UUIDv4. For additional ids based on identifier schemes,
+    # use `Epub::Epub#identifiers`.
+    #
+    attr_accessor :id
+
+    # The epub's identifier schemes. Must be a list of URN strings.
+    #
+    # URNs look like:
+    #
+    # - UUID: `urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809`
+    # - ISBN: `urn:isbn:9780000000001`
+    # - DOI: `doi:10.1016/j.iheduc.2008.03.001`
+    # - JDCN: `915869090000000000DD`
+    #
+    # http://idpf.github.io/epub-registries/identifiers/identifiers.html
+    #
+    attr_accessor :identifiers
+
+    # The publication date. Must be a string like `2024-01-24`.
+    #
+    attr_accessor :date
+
+    # The publisher entity.
+    #
+    attr_accessor :publisher
+
+    # A list of creators.
+    #
+    # @type String[]
+    #
+    attr_accessor :creators
+
+    # A list of contributors.
+    #
+    # @type String[]
+    #
+    attr_accessor :contributors
+
+    # The copyright notice.
+    #
+    attr_accessor :copyright
+
+    # The book language.
+    # Defaults to `en`.
+    #
+    attr_accessor :language
+
+    # Temporary directory. Defaults to `Dir.mktmpdir`.
+    #
+    attr_accessor :tmpdir
+
+    # Set debug mode.
+    # It will output debugging info, and won't remove tmpdir after book is
+    # generated.
+    #
+    attr_accessor :debug
+    alias debug? debug
+
+    def initialize(**kwargs)
+      kwargs.each {|key, value| public_send(:"#{key}=", value) }
+
+      self.date = Date.parse(date || Date.today.to_s)
+      self.id ||= SecureRandom.uuid
+      self.epub_engine ||= V3
+      self.language ||= "en"
+      self.tmpdir ||= Pathname.new(File.join(Dir.tmpdir, SecureRandom.uuid))
+      self.tmpdir = Pathname.new(tmpdir)
+      self.root_dir = Pathname.new(root_dir || Dir.pwd)
+      self.creators = Array(creators)
+      self.contributors = Array(contributors)
+      self.identifiers = Array(identifiers)
+      self.files ||= []
+      identifiers << "urn:uuid:#{id}"
+    end
+
+    def files=(files)
+      @files = Array(files).map {|file| Pathname.new(file) }
+    end
+
+    # Save the file at specified output path.
+    # If a file already exists, an error will be raised.
+    def save(output_path)
+      FileUtils.mkdir_p(tmpdir)
+      epub_engine.new(config: self, output_path:).save
+    ensure
+      FileUtils.rm_rf(tmpdir) unless debug?
+    end
+  end
+end

data/lib/epub/generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Epub
+  class Generator < Thor::Group
+    include Thor::Actions
+
+    attr_accessor :options
+
+    def self.source_root
+      File.join(__dir__, "templates")
+    end
+
+    no_commands do
+      # Add helper methods here
+    end
+  end
+end

data/lib/epub/mime_type.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Epub
+  module MimeType
+    # https://www.w3.org/TR/epub/#sec-core-media-types
+    def self.list
+      @list ||= {
+        ".html" => "application/xhtml+xml",
+        ".xhtml" => "application/xhtml+xml",
+        ".png" => "image/png",
+        ".jpeg" => "image/jpeg",
+        ".jpg" => "image/jpeg",
+        ".gif" => "image/gif",
+        ".webp" => "image/webp",
+        ".svg" => "image/svg+xml",
+        ".woff" => "font/woff",
+        ".woff2" => "font/woff2",
+        ".ttf" => "font/ttf",
+        ".otf" => "font/otf",
+        ".css" => "text/css",
+        ".mp3" => "audio/mpeg",
+        ".m4a" => "audio/mp4",
+        ".ogg" => "audio/ogg; codecs=opus",
+        ".js" => "application/javascript",
+        ".ncx" => "application/x-dtbncx+xml"
+      }
+    end
+
+    def self.[](file)
+      list[File.extname(file).downcase]
+    end
+  end
+end

data/lib/epub/navigation.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Epub
+  class Navigation
+    Node = Struct.new(:level, :entry, :parent, keyword_init: true)
+    Entry = Struct.new(:title, :link, :navigation, keyword_init: true)
+    SELECTOR = "h1, h2[id], h3[id], h4[id], h5[id], h6[id]"
+
+    # Go through each files, sequentially and extract the table of contents
+    # hierarchy, so you don't have to do it yourself.
+    #
+    # Notice that only `h2-h6` headings with an `id` attribute will be added to
+    # the list. `h1` headings will always be added; if they don't have an id,
+    # then they'll be linked to the file itself.
+    #
+    # The output structure doesn't look like the one you're expecting, make sure
+    # your headings have the `id` attribute.
+    #
+    def self.extract_html(files, root_dir:)
+      navigation = extract(files, root_dir:)
+      html = renderer(navigation)
+      <<~HTML
+        <nav epub:type="toc">
+          #{html}
+        </nav>
+      HTML
+    end
+
+    def self.renderer(navigation)
+      return "" if navigation.empty?
+
+      html = []
+      html << "<ol>"
+
+      navigation.each do |item|
+        title = CGI.escape_html(item.title)
+
+        html << "<li>\n"
+        html << %[<a href="#{item.link}">#{title}</a>]
+        html << renderer(item.navigation)
+        html << "\n</li>"
+      end
+
+      html << "</ol>"
+
+      html.join
+    end
+
+    def self.extract(files, root_dir:)
+      root = Node.new(level: 0, entry: Entry.new(navigation: []))
+      current = root
+
+      sections = files.map do |file|
+        {
+          html: Nokogiri::HTML(File.read(file)),
+          path: Pathname.new(file).relative_path_from(root_dir).to_s
+        }
+      end
+
+      sections.each do |section|
+        section[:html].css(SELECTOR).each do |node|
+          title = node.text.strip
+          level = node.name[1].to_i
+
+          entry = Entry.new(
+            title:,
+            link: "#{section[:path]}##{node.attributes['id']}",
+            navigation: []
+          )
+
+          if level > current.level
+            current = Node.new(level:, entry:, parent: current)
+          elsif level == current.level
+            current = Node.new(level:, entry:, parent: current.parent)
+          else
+            while current.parent && current.parent.level >= level
+              current = current.parent
+            end
+
+            current = Node.new(level:, entry:, parent: current.parent)
+          end
+
+          current.parent.entry[:navigation] << entry
+        end
+      end
+
+      root.entry[:navigation]
+    end
+  end
+end

data/lib/epub/v3.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Epub
+  ContainerBreakoutError = Class.new(StandardError)
+
+  class V3
+    # The configuration object (`Epub::Epub`).
+    #
+    attr_reader :config
+
+    # The output path.
+    #
+    attr_reader :output_path
+
+    attr_reader :oebps_dir, :meta_inf_dir
+
+    def initialize(config:, output_path:)
+      @config = config
+      @output_path = Pathname.new(output_path)
+      @oebps_dir = config.tmpdir.join("OEBPS")
+      @meta_inf_dir = config.tmpdir.join("META-INF")
+    end
+
+    def save
+      create_dirs
+      create_mimetype_file
+      create_container_file
+      create_opf_file
+      copy_files
+      create_epub_file
+    end
+
+    private def create_epub_file
+      FileUtils.rm_rf(output_path)
+
+      Zip::File.open(output_path, Zip::File::CREATE) do |zip|
+        # The `mimetype` file must be stored first and it should be
+        # uncompressed.
+        zip.add_stored("mimetype", config.tmpdir.join("mimetype"))
+
+        config.tmpdir.glob("**/*").each do |source_path|
+          relative_path = source_path.relative_path_from(config.tmpdir)
+
+          next if source_path.directory?
+          next if relative_path.to_s == "mimetype"
+
+          zip.add(relative_path, source_path)
+        end
+      end
+    end
+
+    private def copy_files
+      config.files.each do |source_path|
+        relative_path = source_path.relative_path_from(config.root_dir)
+        target_path = oebps_dir.join(relative_path)
+
+        if relative_path.to_s.start_with?("..")
+          raise ContainerBreakoutError,
+                "Cannot copy #{source_path.expand_path}, " \
+                "as it breaks out the epub container (#{relative_path}).\n" \
+                "Ensure your files exist within #{config.root_dir.expand_path}."
+        end
+
+        FileUtils.mkdir_p(target_path.dirname)
+        FileUtils.cp(source_path, target_path)
+      end
+    end
+
+    private def create_mimetype_file
+      config.tmpdir.join("mimetype").open("w") do |file|
+        file << "application/epub+zip"
+      end
+    end
+
+    private def create_dirs
+      oebps_dir.mkdir
+      meta_inf_dir.mkdir
+    end
+
+    private def create_container_file
+      meta_inf_dir.join("container.xml").open("w") do |file|
+        file << <<~XML
+          <?xml version="1.0"?>
+          <container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+            <rootfiles>
+              <rootfile full-path="OEBPS/content.opf"
+                media-type="application/oebps-package+xml" />
+            </rootfiles>
+          </container>
+        XML
+      end
+    end
+
+    private def create_opf_file
+      xml = Builder::XmlMarkup.new(indent: 2)
+      xml.instruct! :xml, version: "1.0", encoding: "UTF-8"
+      xml.package(
+        xmlns: "http://www.idpf.org/2007/opf",
+        version: "3.0",
+        "xmlns:opf" => "http://www.idpf.org/2007/opf",
+        "unique-identifier" => "book-id"
+      ) do
+        render_opf_metadata(xml)
+        render_opf_manifest(xml)
+        render_opf_spine(xml)
+      end
+
+      oebps_dir.join("content.opf").open("w") do |file|
+        file << xml.target!
+      end
+    end
+
+    private def render_opf_metadata(xml)
+      xml.metadata("xmlns:dc" => "http://purl.org/dc/elements/1.1/") do
+        xml.dc(:identifier, config.id, id: "book-id")
+
+        config.identifiers.each do |id|
+          xml.dc(:identifier, id)
+        end
+
+        xml.dc(:title, config.title, id: "book-title")
+        xml.meta("main", refines: "#book-title", property: "title-type")
+
+        xml.meta(config.title, property: "dcterms:title")
+
+        unless config.subtitle.to_s == ""
+          xml.dc(:title, config.subtitle, id: "book-subtitle")
+          xml.meta("subtitle", refines: "#book-subtitle",
+                               property: "title-type")
+        end
+
+        xml.meta name: "cover", content: "cover-image"
+
+        xml.dc(:date, config.date.iso8601)
+        xml.meta("#{config.date.iso8601}T00:00:00Z",
+                 property: "dcterms:modified")
+        xml.dc(:language, config.language)
+        xml.meta(config.language, property: "dcterms:language")
+
+        config.creators.each_with_index do |creator, index|
+          xml.dc(:creator, creator, id: "creator-#{index}")
+          xml.meta(creator, id: "creator-#{index}-meta",
+                            property: "dcterms:creator")
+        end
+
+        config.contributors.each_with_index do |contributor, index|
+          xml.dc(:contributor, contributor, id: "contributor-#{index}")
+          xml.meta(contributor,
+                   id: "contributor-#{index}-meta",
+                   property: "dcterms:contributor")
+        end
+
+        xml.dc(:publisher, config.publisher)
+        xml.meta(config.publisher, property: "dcterms:publisher")
+
+        if config.copyright
+          xml.dc(:rights, config.copyright)
+          xml.meta(config.copyright, property: "dcterms:rights")
+        end
+      end
+    end
+
+    private def render_opf_manifest(xml)
+      xml.manifest do
+        config.files.each do |file|
+          id = guess_id(file)
+          props = {}
+          props[:properties] = "cover-image" if id == "cover-image"
+          props[:properties] = "nav" if id == "toc"
+
+          xml.item href: file.relative_path_from(config.root_dir),
+                   "media-type" => guess_media_type(file),
+                   id:,
+                   **props
+        end
+      end
+    end
+
+    private def guess_id(filename)
+      filename = filename.basename.to_s
+
+      case filename
+      when /^cover\.(png|jpe?g|gif|svg)$/i
+        "cover-image"
+      when /^cover\.x?html$/i
+        "cover"
+      when /^toc\.x?html$/i
+        "toc"
+      else
+        filename.tr(".", "-")
+      end
+    end
+
+    private def guess_media_type(file)
+      MimeType[file]
+    end
+
+    private def render_opf_spine(xml)
+      xml.spine do
+        config.files.each do |file|
+          next unless file.extname.match?(/\.x?html$/i)
+
+          xml.itemref idref: guess_id(file)
+        end
+      end
+    end
+  end
+end

data/lib/epub/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Epub
+  VERSION = "0.0.0"
+end

data/lib/epub-rb.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "epub"

data/lib/epub.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "builder"
+require "zip"
+require "nokogiri"
+
+module Epub
+  require "epub/version"
+  require "epub/epub"
+  require "epub/v3"
+  require "epub/mime_type"
+  require "epub/navigation"
+
+  def self.new(**)
+    Epub.new(**)
+  end
+end

data/playground.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+epub = Epub.new
+epub.files += []
+epub.cover_image = "cover.png"
+epub.cover_page = "cover.html"
+epub.toc_page = "toc.html"
+epub.id = {}
+epub.date = Time.now
+epub.publisher = "O'Reilly"
+epub.creator = "Author 1, Author 2, and Author 3"
+epub.navigation = navigation
+epub.save("file.epub")
+
+# epub.title        config[:title]
+# epub.language     config[:language]
+# epub.creator      config[:authors].to_sentence
+# epub.publisher    config[:publisher]
+# epub.date         config[:published_at]
+# epub.uid          "id"
+# epub.identifier   config[:identifier][:id],
+#                   scheme: config[:identifier][:type]
+
+# # epubchecker complains when assigning an image directly,
+# # but if we don't, then Apple Books doesn't render the cover.
+# # Need to investigate some more.
+# # epub.cover_page   cover_image if cover_image && File.exist?(cover_image)
+# epub.cover_page   "output/epub/cover.html"
+# epub.files(sections.map(&:filepath) + assets)
+# epub.nav(hierarchy)
+# epub.toc_page(toc_path)
+# epub.save(epub_path)