ucf 0.5.0 → 0.6.0

data/Changes.rdoc

@@ -1,5 +1,10 @@
 = Changes log for the UCF Ruby Gem
 
+== Version 0.6.0
+
+* Move to use version 0.9.0 of the zip-container library.
+* Update and polish the example scripts.
+
 == Version 0.5.0
 
 * Add support for managed entries in the container.

data/Rakefile

@@ -52,9 +52,10 @@ Jeweler::Tasks.new do |s|
   s.platform         = Gem::Platform::RUBY
   s.summary          = "Universal Container Format (UCF) Ruby Library"
   s.description      = "A Ruby library for working with Universal Container "\
-    "Format files. See "\
-    "https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format "\
-    "for the specification."
+    "Format files - a type of EPUB document. See the "\
+    "{UCF specification}[https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format] "\
+    "for details. They are very similar, although not as restrictive, as the "\
+    "{EPUB Open Container Format (OCF)}[http://www.idpf.org/epub/30/spec/epub30-ocf.html]."
   s.require_path     = "lib"
   s.test_file        = "test/ts_ucf.rb"
   s.has_rdoc         = true
@@ -63,7 +64,7 @@ Jeweler::Tasks.new do |s|
   s.add_development_dependency('rake', '~> 10.0.4')
   s.add_development_dependency('rdoc', '~> 4.0.1')
   s.add_development_dependency('jeweler', '~> 1.8.4')
-  s.add_runtime_dependency('rubyzip', '~> 0.9.9')
+  s.add_runtime_dependency('zip-container', '~> 0.9.0')
 end
 
 Rake::TestTask.new do |t|

data/ReadMe.rdoc

@@ -13,7 +13,8 @@ Copyright::   (c) 2013 The University of Manchester, UK
 
 This is a Ruby library for working with UCF documents. See
 {the specification}[https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format]
-for more details.
+for more details. UCF is a type of EPUB and very similar to the
+{EPUB Open Container Format (OCF)}[http://www.idpf.org/epub/30/spec/epub30-ocf.html].
 
 <b>This library is a work in progress!</b> Until we release version 1.0.0 you
 can expect the API to change in incompatible ways, although we will try to
@@ -21,6 +22,12 @@ keep this to an absolute minimum. Once version 1.0.0 is released we will be
 following the principles of {Semantic Versioning}[http://semver.org/] for our
 version numbering scheme.
 
+Most of this library's API is provided by the underlying
+{zip-container gem}[https://rubygems.org/gems/zip-container] so you will need
+to consult
+{that documentation as well}[http://mygrid.github.io/ruby-zip-container/] in
+addition to this.
+
 There are some examples of how to use the library provided in the examples
 directory. See the contents of the tests directory for even more.
 

data/examples/{create_ucf.rb → create-ucf}

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # Copyright (c) 2013 The University of Manchester, UK.
 #
 # All rights reserved.
@@ -33,13 +34,22 @@
 require 'rubygems'
 require 'ucf'
 
-ZIP_FILE = "example.zip"
-file = ARGV.length > 0 ? ARGV[0] : ZIP_FILE
+def usage
+  puts "Usage:\n  create-ucf <ucf-file>"
+  exit 1
+end
+
+usage unless ARGV.length == 1
 
-File.delete(file) if File.exists?(file)
+ucffile = ARGV[0]
+
+if File.exists?(ucffile)
+  puts "File '#{ucffile}' already exists. Exiting."
+  exit 1
+end
 
 begin
-  UCF::Container.create(file) do |c|
+  UCF::Container.create(ucffile) do |c|
 
     # Add a cheery greeting file from a string.
     c.file.open("greeting.txt", "w") do |f|
@@ -55,7 +65,7 @@ begin
     # Add a explanation of this file.
     c.comment = "This is an example UCF file!"
   end
-rescue UCF::MalformedUCFError, Zip::ZipError => err
+rescue ZipContainer::MalformedContainerError, Zip::ZipError => err
   puts err.to_s
   exit 1
 end

data/examples/ucfinfo

@@ -35,7 +35,7 @@ require 'rubygems'
 require 'ucf'
 
 def usage
-  puts "ucfinfo ucf-file"
+  puts "Usage:\n  ucfinfo <ucf-file>"
   exit 1
 end
 
@@ -45,7 +45,7 @@ ucffile = ARGV[0]
 
 begin
   ucf = UCF::Container.open(ucffile)
-rescue UCF::MalformedUCFError, Zip::ZipError => err
+rescue ZipContainer::MalformedContainerError, Zip::ZipError => err
   puts err.to_s
   exit 1
 end

data/examples/{verify_ucf.rb → verify-ucf}

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # Copyright (c) 2013 The University of Manchester, UK.
 #
 # All rights reserved.
@@ -33,12 +34,18 @@
 require 'rubygems'
 require 'ucf'
 
-ZIP_FILE = "example.zip"
-file = ARGV.length > 0 ? ARGV[0] : ZIP_FILE
+def usage
+  puts "Usage:\n  verify-ucf <ucf-file>"
+  exit 1
+end
+
+usage unless ARGV.length == 1
+
+ucffile = ARGV[0]
 
 begin
-  UCF::Container.verify!(file)
-rescue UCF::MalformedUCFError, Zip::ZipError => err
+  UCF::Container.verify!(ucffile)
+rescue ZipContainer::MalformedContainerError, Zip::ZipError => err
   puts err.to_s
   exit 1
 end

data/lib/ucf.rb

@@ -31,12 +31,6 @@
 # Author: Robert Haines
 
 require 'yaml'
-require 'ucf/exceptions'
-require 'ucf/entries/reserved'
-require 'ucf/entries/managed'
-require 'ucf/entries/entry'
-require 'ucf/entries/file'
-require 'ucf/entries/directory'
 require 'ucf/meta-inf'
 require 'ucf/container'
 

data/lib/ucf/container.rb

@@ -30,462 +30,51 @@
 #
 # Author: Robert Haines
 
-require 'forwardable'
-require 'zip/zipfilesystem'
+require 'zip-container'
 
 module UCF
 
-  # This class represents a UCF document in PK Zip format. See
-  # {the specification}[https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format]
+  # This class represents a UCF document - also known as an EPUB and very
+  # similar to the
+  # {EPUB Open Container Format (OCF)}[http://www.idpf.org/epub/30/spec/epub30-ocf.html].
+  # See the
+  # {UCF specification}[https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format]
   # for more details.
   #
-  # This class provides most of the facilities of the <tt>Zip::ZipFile</tt>
-  # class in the rubyzip gem. Please also consult the
-  # {rubyzip documentation}[http://rubydoc.info/gems/rubyzip/0.9.9/frames]
-  # alongside these pages.
+  # This class is a specialization of ZipContainer so you should see the
+  # {ZipContainer documentation}[http://mygrid.github.io/ruby-zip-container/]
+  # for much more information and a list of all the other methods available in
+  # this class. RDoc does not list inherited methods, unfortunately.
   #
   # There are code examples available with the source code of this library.
-  class Container
-    include ReservedNames
-    include ManagedEntries
-
-    extend Forwardable
-    def_delegators :@zipfile, :comment, :comment=, :commit_required?, :each,
-      :entries, :extract, :find_entry, :get_entry, :get_input_stream, :glob,
-      :name, :read, :size
+  class Container < ZipContainer::Container
 
     private_class_method :new
 
-    # The mime-type of this UCF document. By default this is
-    # "application/epub+zip".
-    attr_reader :mimetype
-
     # :stopdoc:
     DEFAULT_MIMETYPE = "application/epub+zip"
 
-    # The reserved mimetype file name for standard UCF documents.
-    MIMETYPE_FILE = "mimetype"
-
-    def initialize(document)
-      @zipfile = open_document(document)
-      check_mimetype!
-
-      @mimetype = read_mimetype
-      @on_disk = true
-
-      # Reserved entry names. Just the mimetype file by default.
-      register_reserved_name(MIMETYPE_FILE)
+    def initialize(filename)
+      super(filename)
 
       # Initialize the managed entries and register the META-INF directory.
       initialize_managed_entries(MetaInf.new)
-
-      # Here we fake up the connection to the rubyzip filesystem classes so
-      # that they also respect the reserved names that we define.
-      mapped_zip = ::Zip::ZipFileSystem::ZipFileNameMapper.new(self)
-      @fs_dir  = ::Zip::ZipFileSystem::ZipFsDir.new(mapped_zip)
-      @fs_file = ::Zip::ZipFileSystem::ZipFsFile.new(mapped_zip)
-      @fs_dir.file = @fs_file
-      @fs_file.dir = @fs_dir
     end
     # :startdoc:
 
     # :call-seq:
-    #   Container.create(filename, mimetype = "application/epub+zip") -> document
-    #   Container.create(filename, mimetype = "application/epub+zip") {|document| ...}
+    #   Container.create(filename) -> Container
+    #   Container.create(filename) {|container| ...}
     #
-    # Create a new UCF document on disk with the specified mimetype.
-    def Container.create(filename, mimetype = DEFAULT_MIMETYPE, &block)
-      ::Zip::ZipOutputStream.open(filename) do |stream|
-        stream.put_next_entry(MIMETYPE_FILE, nil, nil, ::Zip::ZipEntry::STORED)
-        stream.write mimetype
-      end
-
-      # Now open the newly created container.
-      c = new(filename)
-
-      if block_given?
-        begin
-          yield c
-        ensure
-          c.close
-        end
-      end
-
-      c
-    end
-
-    # :call-seq:
-    #   Container.each_entry -> Enumerator
-    #   Container.each_entry {|entry| ...}
+    # Create a new UCF document on disk and open it for editing.
     #
-    # Iterate over the entries in the UCF document. The entry objects returned
-    # by this method are Zip::ZipEntry objects. Please see the rubyzip
-    # documentation for details.
-    def Container.each_entry(filename, &block)
-      c = new(filename)
-
-      if block_given?
-        begin
-          c.each(&block)
-        ensure
-          c.close
-        end
-      end
-
-      c.each
+    # Please see the
+    # {ZipContainer documentation}[http://mygrid.github.io/ruby-zip-container/]
+    # for much more information and a list of all the other methods available
+    # in this class. RDoc does not list inherited methods, unfortunately.
+    def Container.create(filename, &block)
+      super(filename, DEFAULT_MIMETYPE, &block)
     end
 
-    # :call-seq:
-    #   Container.open(filename) -> document
-    #   Container.open(filename) {|document| ...}
-    #
-    # Open an existing UCF document from disk. It will be checked for
-    # conformance to the UCF specification upon first access.
-    def Container.open(filename, &block)
-      c = new(filename)
-
-      if block_given?
-        begin
-          yield c
-        ensure
-          c.close
-        end
-      end
-
-      c
-    end
-
-    # :call-seq:
-    #   Container.verify(filename) -> boolean
-    #
-    # Verify that the specified UCF document conforms to the UCF
-    # specification. This method returns +false+ if there are any problems at
-    # all with the file (including if it cannot be found).
-    def Container.verify(filename)
-      begin
-        new(filename).verify!
-      rescue
-        return false
-      end
-
-      true
-    end
-
-    # :call-seq:
-    #   Container.verify!(filename)
-    #
-    # Verify that the specified UCF document conforms to the UCF
-    # specification. This method raises exceptions when errors are found or if
-    # there is something fundamental wrong with the file itself (e.g. it
-    # cannot be found).
-    def Container.verify!(filename)
-      new(filename).verify!
-    end
-
-    # :call-seq:
-    #   add(entry, src_path, &continue_on_exists_proc)
-    #
-    # Convenience method for adding the contents of a file to the UCF
-    # document. If asked to add a file with a reserved name, such as the
-    # special mimetype header file, this method will raise a
-    # ReservedNameClashError.
-    #
-    # See the rubyzip documentation for details of the
-    # +continue_on_exists_proc+ parameter.
-    def add(entry, src_path, &continue_on_exists_proc)
-      if reserved_entry?(entry) || managed_directory?(entry)
-        raise ReservedNameClashError.new(entry.to_s)
-      end
-
-      @zipfile.add(entry, src_path, &continue_on_exists_proc)
-    end
-
-    # :call-seq:
-    #   commit -> boolean
-    #   close -> boolean
-    #
-    # Commits changes that have been made since the previous commit to the
-    # UCF document. Returns +true+ if anything was actually done, +false+
-    # otherwise.
-    def commit
-      return false unless commit_required?
-
-      if on_disk?
-        @zipfile.commit
-      end
-    end
-
-    alias :close :commit
-
-    # :call-seq:
-    #   dir -> Zip::ZipFsDir
-    #
-    # Returns an object which can be used like ruby's built in +Dir+ (class)
-    # object, except that it works on the UCF document on which this method is
-    # invoked.
-    #
-    # See the rubyzip documentation for details.
-    def dir
-      @fs_dir
-    end
-
-    # :call-seq:
-    #   file -> Zip::ZipFsFile
-    #
-    # Returns an object which can be used like ruby's built in +File+ (class)
-    # object, except that it works on the UCF document on which this method is
-    # invoked.
-    #
-    # See the rubyzip documentation for details.
-    def file
-      @fs_file
-    end
-
-    # :call-seq:
-    #   get_output_stream(entry, permission = nil) -> stream
-    #   get_output_stream(entry, permission = nil) {|stream| ...}
-    #
-    # Returns an output stream to the specified entry. If a block is passed
-    # the stream object is passed to the block and the stream is automatically
-    # closed afterwards just as with ruby's built-in +File.open+ method.
-    #
-    # See the rubyzip documentation for details of the +permission_int+
-    # parameter.
-    def get_output_stream(entry, permission = nil, &block)
-      if reserved_entry?(entry) || managed_directory?(entry)
-        raise ReservedNameClashError.new(entry.to_s)
-      end
-
-      @zipfile.get_output_stream(entry, permission, &block)
-    end
-
-    # :call-seq:
-    #   in_memory? -> boolean
-    #
-    # Is this UCF document memory resident as opposed to stored on disk?
-    def in_memory?
-      !@on_disk
-    end
-
-    # :call-seq:
-    #   mkdir(name, permission = 0755)
-    #
-    # Creates a directory in the UCF document. If asked to create a directory
-    # with a reserved name this method will raise a ReservedNameClashError.
-    #
-    # The new directory will be created with the supplied unix-style
-    # permissions. The default (+0755+) is owner read, write and list; group
-    # read and list; and world read and list.
-    def mkdir(name, permission = 0755)
-      if reserved_entry?(name) || managed_file?(name)
-        raise ReservedNameClashError.new(name)
-      end
-
-      @zipfile.mkdir(name, permission)
-    end
-
-    # :call-seq:
-    #   on_disk? -> boolean
-    #
-    # Is this UCF document stored on disk as opposed to memory resident?
-    def on_disk?
-      @on_disk
-    end
-
-    # :call-seq:
-    #   remove(entry)
-    #
-    # Removes the specified entry from the UCF document. If asked to remove
-    # any reserved files such as the special mimetype header file this method
-    # will do nothing.
-    def remove(entry)
-      return if reserved_entry?(entry)
-      @zipfile.remove(entry)
-    end
-
-    # :call-seq:
-    #   rename(entry, new_name, &continue_on_exists_proc)
-    #
-    # Renames the specified entry in the UCF document. If asked to rename any
-    # reserved files such as the special mimetype header file this method will
-    # do nothing. If asked to rename a file _to_ one of the reserved names a
-    # ReservedNameClashError is raised.
-    #
-    # See the rubyzip documentation for details of the
-    # +continue_on_exists_proc+ parameter.
-    def rename(entry, new_name, &continue_on_exists_proc)
-      return if reserved_entry?(entry)
-      raise ReservedNameClashError.new(new_name) if reserved_entry?(new_name)
-
-      @zipfile.rename(entry, new_name, &continue_on_exists_proc)
-    end
-
-    # :call-seq:
-    #   replace(entry, src_path)
-    #
-    # Replaces the specified entry of the UCF document with the contents of
-    # +src_path+ (from the file system). If asked to replace any reserved
-    # files such as the special mimetype header file this method will do
-    # nothing.
-    def replace(entry, src_path)
-      return if reserved_entry?(entry)
-      @zipfile.replace(entry, src_path)
-    end
-
-    # :call-seq:
-    #   to_s -> String
-    #
-    # Return a textual summary of this UCF document.
-    def to_s
-      @zipfile.to_s + " - #{@mimetype}"
-    end
-
-    # :call-seq:
-    #   verify!
-    #
-    # Verify the contents of this UCF document. All managed files and
-    # directories are checked to make sure that they exist, if required.
-    def verify!
-      verify_managed_entries!
-    end
-
-    private
-
-    def open_document(document)
-      ::Zip::ZipFile.new(document)
-    end
-
-    def check_mimetype!
-      # Check mimetype file is present and correct.
-      entry = @zipfile.find_entry(MIMETYPE_FILE)
-
-      raise MalformedUCFError.new("'mimetype' file is missing.") if entry.nil?
-      if entry.localHeaderOffset != 0
-        raise MalformedUCFError.new("'mimetype' file is not at offset 0 in the archive.")
-      end
-      if entry.compression_method != ::Zip::ZipEntry::STORED
-        raise MalformedUCFError.new("'mimetype' file is compressed.")
-      end
-
-      true
-    end
-
-    def read_mimetype
-      @zipfile.read(MIMETYPE_FILE)
-    end
-
-    public
-
-    # Lots of extra docs out of the way at the end here...
-
-    ##
-    # :method: comment
-    # :call-seq:
-    #   comment -> String
-    #
-    # Returns the UCF document comment, if it has one.
-
-    ##
-    # :method: comment=
-    # :call-seq:
-    #   comment = comment
-    #
-    # Set the UCF document comment to the new value.
-
-    ##
-    # :method: commit_required?
-    # :call-seq:
-    #   commit_required? -> boolean
-    #
-    # Returns +true+ if any changes have been made to this UCF document since
-    # the last commit, +false+ otherwise.
-
-    ##
-    # :method: each
-    # :call-seq:
-    #   each -> Enumerator
-    #   each {|entry| ...}
-    #
-    # Iterate over the entries in the UCF document. The entry objects returned
-    # by this method are Zip::ZipEntry objects. Please see the rubyzip
-    # documentation for details.
-
-    ##
-    # :method:
-    # :call-seq:
-    #   entries -> Enumerable
-    #
-    # Returns an Enumerable containing all the entries in the UCF Document.
-    # The entry objects returned by this method are Zip::ZipEntry objects.
-    # Please see the rubyzip documentation for details.
-
-    ##
-    # :method: extract
-    # :call-seq:
-    #   extract(entry, dest_path, &on_exists_proc)
-    #
-    # Extracts the specified entry of the UCF document to +dest_path+.
-    #
-    # See the rubyzip documentation for details of the +on_exists_proc+
-    # parameter.
-
-    ##
-    # :method: find_entry
-    # :call-seq:
-    #   find_entry(entry) -> Zip::ZipEntry
-    #
-    # Searches for entries within the UCF document with the specified name.
-    # Returns +nil+ if no entry is found. See also +get_entry+.
-
-    ##
-    # :method: get_entry
-    # :call-seq:
-    #   get_entry(entry) -> Zip::ZipEntry
-    #
-    # Searches for an entry within the UCF document in a similar manner to
-    # +find_entry+, but throws +Errno::ENOENT+ if no entry is found.
-
-    ##
-    # :method: get_input_stream
-    # :call-seq:
-    #   get_input_stream(entry) -> stream
-    #   get_input_stream(entry) {|stream| ...}
-    #
-    # Returns an input stream to the specified entry. If a block is passed the
-    # stream object is passed to the block and the stream is automatically
-    # closed afterwards just as with ruby's built in +File.open+ method.
-
-    ##
-    # :method: glob
-    # :call-seq:
-    #   glob(*args) -> Array of Zip::ZipEntry
-    #   glob(*args) {|entry| ...}
-    #
-    # Searches for entries within the UCF document that match the given glob.
-    #
-    # See the rubyzip documentation for details of the parameters that can be
-    # passed in.
-
-    ##
-    # :method: name
-    # :call-seq:
-    #   name -> String
-    #
-    # Returns the filename of this UCF document.
-
-    ##
-    # :method: read
-    # :call-seq:
-    #   read(entry) -> String
-    #
-    # Returns a string containing the contents of the specified entry.
-
-    ##
-    # :method: size
-    # :call-seq:
-    #   size -> int
-    #
-    # Returns the number of entries in the UCF document.
-
   end
 end