ucf 0.0.2 → 0.1.0

data/Changes.rdoc

@@ -1,5 +1,24 @@
 = Changes log for the UCF Ruby Gem
 
+== Version 0.1.0
+
+* Improvements to the reserved names code to allow sub-classing.
+* Move exceptions to a new source file.
+* Use a base class for UCF exceptions.
+* Standardize the MalformedUCFError exception messages.
+* Add an exception for clashes with reserved names.
+* Implement Container#add to avoid using reserved names.
+* Raise an exception if renaming to a reserved name.
+* Implement Container#mkdir to avoid using reserved names.
+* Make sure testing reserved names copes with trailing slashes.
+* Fake up the connection to ZipFileSystem.
+* Implement Container#get_output_stream to respect reserved names.
+* Can now set comments on the UCF document.
+* Implement the close and commit methods.
+* Forward the commit_required? method.
+* Separate the opening and checking of a UCF document.
+* Documentation improvements and cleanup.
+
 == Version 0.0.2
 
 * Update the main ReadMe file.

data/ReadMe.rdoc

@@ -7,6 +7,7 @@ Source code:: https://github.com/myGrid/ruby-ucf
 Licence::     BSD (See Licence file or http://www.opensource.org/licenses/bsd-license.php)
 Copyright::   (c) 2013 The University of Manchester, UK
 
+{<img src="https://codeclimate.com/github/myGrid/ruby-ucf.png" />}[https://codeclimate.com/github/myGrid/ruby-ucf]
 
 == Synopsis
 
@@ -28,12 +29,12 @@ directory. See the contents of the tests directory for even more.
 The basic requirements of a UCF document are all implemented but there are a
 number of optional features that are not yet provided.
 
-* In memory operation. Presently all operations are performed on documents
-  that are resident on disk.
+* Memory resident UCF documents. Presently all operations are performed on
+  documents that are resident on disk as the underlying
+  {rubyzip library}[https://github.com/aussiegeek/rubyzip] currently
+  {cannot do anything else}[https://github.com/aussiegeek/rubyzip/issues/74].
 * META-INF directory support. Everything within the META-INF directory is
   optional but will supported in a near future version.
-* Changing the mimetype. It is not certain that this is a sensible operation
-  but is being considered for a future version.
 * Digital signatures (this feature has been deferred until a future revision
   of the UCF specification. It will be supported by this gem when it is added
   to the specification).

data/examples/create_ucf.rb

@@ -51,6 +51,9 @@ begin
 
     # Copy this example code in straight from a file.
     c.add("dir/code.rb", __FILE__)
+
+    # Add a explanation of this file.
+    c.comment = "This is an example UCF file!"
   end
 rescue UCF::MalformedUCFError, Zip::ZipError => err
   puts err.to_s

data/lib/ucf/container.rb

@@ -35,53 +35,58 @@ require 'zip/zipfilesystem'
 
 module UCF
 
-  # This class represents a UCF file in PK Zip format. See
-  # https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format
+  # This class represents a UCF document in PK Zip format. See
+  # {the specification}[https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format]
   # for more details.
   #
-  # This class mostly provides all 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
+  # 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.
   #
   # There are code examples available with the source code of this library.
   class Container
 
     extend Forwardable
-    def_delegators :@zipfile, :add, :close, :comment, :commit, :dir, :each,
-      :extract, :file, :find_entry, :get_entry, :get_input_stream,
-      :get_output_stream, :glob, :mkdir, :name, :read, :size
+    def_delegators :@zipfile, :comment, :comment=, :commit_required?, :each,
+      :extract, :find_entry, :get_entry, :get_input_stream, :glob, :name,
+      :read, :size
 
     private_class_method :new
 
-    # The mime-type of this UCF file. By default this is
+    # The mime-type of this UCF document. By default this is
     # "application/epub+zip".
     attr_reader :mimetype
 
     # :stopdoc:
     DEFAULT_MIMETYPE = "application/epub+zip"
 
-    # Reserved root file names. File names in UCF documents are
-    # case-insensitive so downcase where required in the reserved list.
+    # Reserved file and directory names for standard UCF documents.
     MIMETYPE_FILE = "mimetype"
     META_INF_DIR = "META-INF"
-    RESERVED_ROOT_NAMES = [MIMETYPE_FILE, META_INF_DIR.downcase]
 
-    ERR_MT_NONE = "Not a UCF file. 'mimetype' file is missing."
-    ERR_MT_BAD_OFF = "Not a UCF file. 'mimetype' file is not at offset 0."
-    ERR_MT_BAD_COMP = "Not a UCF file. 'mimetype' file is compressed."
-
-    def initialize(filename)
-      @zipfile = open_and_check_ucf(filename)
+    def initialize(document)
+      @zipfile = open_document(document)
+      check_document!
 
       @mimetype = read_mimetype
+      @on_disk = true
+
+      # 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") -> container
-    #   Container.create(filename, mimetype = "application/epub+zip") {|container| ...}
+    #   Container.create(filename, mimetype = "application/epub+zip") -> document
+    #   Container.create(filename, mimetype = "application/epub+zip") {|document| ...}
     #
-    # Create a new UCF file on disk with the specified mimetype.
+    # 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)
@@ -113,11 +118,11 @@ module UCF
     end
 
     # :call-seq:
-    #   Container.open(filename) -> container
-    #   Container.open(filename) {|container| ...}
+    #   Container.open(filename) -> document
+    #   Container.open(filename) {|document| ...}
     #
-    # Open an existing UCF file from disk. It will be checked for conformance
-    # to the UCF specification upon first access.
+    # 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)
 
@@ -135,9 +140,9 @@ module UCF
     # :call-seq:
     #   Container.verify(filename) -> boolean
     #
-    # Verify that the specified UCF file conforms to the UCF specification.
-    # This method returns +false+ if there are any problems at all with the
-    # file (including if it can't be found) or +true+ if it conforms.
+    # 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
         Container.verify!(filename)
@@ -151,128 +156,261 @@ module UCF
     # :call-seq:
     #   Container.verify!(filename)
     #
-    # Verify that the specified UCF file 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. not found).
+    # 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).close
       nil
     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)
+      raise ReservedNameClashError.new(entry.to_s) if reserved_entry?(entry)
+
+      @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)
+      raise ReservedNameClashError.new(entry.to_s) if reserved_entry?(entry)
+
+      @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)
+      raise ReservedNameClashError.new(name) if reserved_entry?(name)
+
+      @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. If asked to remove any reserved files such
-    # as the special mimetype header file this method will do nothing.
+    # 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, &continueOnExistsProc)
+    #   rename(entry, new_name, &continue_on_exists_proc)
     #
-    # Renames the specified entry. If asked to rename any reserved files such
-    # as the special mimetype header file this method will do nothing. See the
-    # rubyzip documentation for details of the +continue_on_exists_proc+
-    # parameter.
+    # 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)
-      @zipfile.rename(entry, new_name, continue_on_exists_proc)
+      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 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.
+    # 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:
+    #   reserved_files -> Array
+    #
+    # Return a list of reserved file names for this UCF document.
+    #
+    # When creating a more specialized sub-class of this class then this
+    # method should be overridden to add any extra reserved file names.
+    def reserved_files
+      [MIMETYPE_FILE]
+    end
+
+    # :call-seq:
+    #   reserved_directories -> Array
+    #
+    # Return a list of reserved directory names for this UCF document.
+    #
+    # When creating a more specialized sub-class of this class then this
+    # method should be overridden to add any extra reserved directory names.
+    def reserved_directories
+      [META_INF_DIR]
+    end
+
+    # :call-seq:
+    #   reserved_entry?(entry) -> boolean
+    #
+    # Is the given entry name in the reserved list of file or directory names?
+    def reserved_entry?(entry)
+      name = entry.kind_of?(::Zip::ZipEntry) ? entry.name : entry
+      name.chop! if name.end_with? "/"
+      reserved_names.map { |n| n.downcase }.include? name.downcase
+    end
+
+    # :call-seq:
+    #   reserved_names -> Array
+    #
+    # Return a list of reserved file and directory names for this UCF
+    # document.
+    #
+    # In practice this method simply returns the joined lists of reserved file
+    # and directory names.
+    def reserved_names
+      reserved_files + reserved_directories
+    end
+
     # :call-seq:
     #   to_s -> String
     #
-    # Return a String representation of this UCF file.
+    # Return a textual summary of this UCF document.
     def to_s
       @zipfile.to_s + " - #{@mimetype}"
     end
 
     private
 
-    def open_and_check_ucf(filename)
-      file = ::Zip::ZipFile.new(filename)
+    def open_document(document)
+      ::Zip::ZipFile.new(document)
+    end
 
+    def check_document!
       # Check mimetype file is present and correct.
-      entry = file.find_entry(MIMETYPE_FILE)
-      raise MalformedUCFError.new(ERR_MT_NONE) if entry.nil?
-      raise MalformedUCFError.new(ERR_MT_BAD_OFF) if entry.localHeaderOffset != 0
+      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(ERR_MT_BAD_COMP)
+        raise MalformedUCFError.new("'mimetype' file is compressed.")
       end
 
-      file
+      true
     end
 
     def read_mimetype
       @zipfile.read(MIMETYPE_FILE)
     end
 
-    # Remember that file names in UCF documents are case-insensitive so
-    # compare downcased versions.
-    def reserved_entry?(entry)
-      name = entry.kind_of?(::Zip::ZipEntry) ? entry.name : entry
-      RESERVED_ROOT_NAMES.include? name.downcase
-    end
-
     public
 
     # Lots of extra docs out of the way at the end here...
 
-    ##
-    # :method: add
-    # :call-seq:
-    #   add(entry, src_path, &continue_on_exists_proc)
-    #
-    # Convenience method for adding the contents of a file to the UCF file.
-    #
-    # See the rubyzip documentation for details of the
-    # +continue_on_exists_proc+ parameter.
-
-    ##
-    # :method: close
-    # :call-seq:
-    #   close
-    #
-    # Closes the UCF file committing any changes that have been made.
-
     ##
     # :method: comment
     # :call-seq:
     #   comment -> String
     #
-    # Returns the UCF file comment, if it has one.
+    # Returns the UCF document comment, if it has one.
 
     ##
-    # :method: commit
+    # :method: comment=
     # :call-seq:
-    #   commit
+    #   comment = comment
     #
-    # Commits changes that have been made since the previous commit to the
-    # UCF file.
+    # Set the UCF document comment to the new value.
 
     ##
-    # :method: dir
+    # :method: commit_required?
     # :call-seq:
-    #   dir -> Zip::ZipFsDir
+    #   commit_required? -> boolean
     #
-    # Returns an object which can be used like ruby's built in +Dir+ (class)
-    # object, except that it works on the UCF file on which this method is
-    # invoked.
-    #
-    # See the rubyzip documentation for details.
+    # Returns +true+ if any changes have been made to this UCF document since
+    # the last commit, +false+ otherwise.
 
     ##
     # :method: each
@@ -289,37 +427,26 @@ module UCF
     # :call-seq:
     #   extract(entry, dest_path, &on_exists_proc)
     #
-    # Extracts the specified entry to +dest_path+.
+    # Extracts the specified entry of the UCF document to +dest_path+.
     #
     # See the rubyzip documentation for details of the +on_exists_proc+
     # parameter.
 
-    ##
-    # :method: file
-    # :call-seq:
-    #   dir -> Zip::ZipFsFile
-    #
-    # Returns an object which can be used like ruby's built in +File+ (class)
-    # object, except that it works on the UCF file on which this method is
-    # invoked.
-    #
-    # See the rubyzip documentation for details.
-
     ##
     # :method: find_entry
     # :call-seq:
     #   find_entry(entry) -> Zip::ZipEntry
     #
-    # Searches for entries with the specified name. Returns +nil+ if no entry
-    # is found. See also +get_entry+.
+    # 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 like +find_entry+, but throws +Errno::ENOENT+ if
-    # no entry is found.
+    # 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
@@ -331,46 +458,23 @@ module UCF
     # 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: get_output_stream
-    # :call-seq:
-    #   get_output_stream(entry, permission_int = nil) -> stream
-    #   get_output_stream(entry, permission_int = 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.
-
     ##
     # :method: glob
     # :call-seq:
     #   glob(*args) -> Array of Zip::ZipEntry
     #   glob(*args) {|entry| ...}
     #
-    # Searches for entries given a glob.
+    # 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: mkdir
-    # :call-seq:
-    #   mkdir(entryName, permission_int = 0755)
-    #
-    # Creates a directory.
-    #
-    # See the rubyzip documentation for details of the +permission_int+
-    # parameter.
-
     ##
     # :method: name
     # :call-seq:
     #   name -> String
     #
-    # Returns the filename of this UCF file.
+    # Returns the filename of this UCF document.
 
     ##
     # :method: read

data/lib/ucf/exceptions.rb

@@ -0,0 +1,68 @@
+# Copyright (c) 2013 The University of Manchester, UK.
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#  * Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+#  * Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+#  * Neither the names of The University of Manchester nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# Author: Robert Haines
+
+module UCF
+
+  # The base class of all other exceptions raised by this library.
+  class UCFError < RuntimeError
+  end
+
+  # This exception is raised when a bad UCF is detected.
+  class MalformedUCFError < UCFError
+
+    # :call-seq:
+    #   new(reason = "")
+    #
+    # Create a new MalformedUCFError with an optional reason for why the UCF
+    # document is malformed.
+    def initialize(reason = nil)
+      if reason.nil?
+        super("Malformed UCF Document.")
+      else
+        super("Malformed UCF Document: #{reason}")
+      end
+    end
+  end
+
+  # This exception is raised when a clash occurs with a reserved name.
+  class ReservedNameClashError < UCFError
+
+    # :call-seq:
+    #   new(name)
+    #
+    # Create a new ReservedNameClashError with the name of the clash supplied.
+    def initialize(name)
+      super("'#{name}' is reserved for internal use in this UCF document.")
+    end
+  end
+
+end

data/lib/ucf.rb

@@ -31,13 +31,15 @@
 # Author: Robert Haines
 
 require 'yaml'
+require 'ucf/exceptions'
 require 'ucf/container'
 
 # This is a ruby library to read and write UCF files in PK Zip format. See the
 # UCF::Container class for more information.
 #
-# See https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format
-# for more details on the UCF.
+# See
+# {the UCF specification}[https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format]
+# for more details.
 module UCF
 
   # Library version information.
@@ -50,12 +52,4 @@ module UCF
     STRING = [:major, :minor, :patch].map {|d| INFO[d]}.compact.join('.')
   end
 
-  # Exception raised when a bad UCF is detected.
-  class MalformedUCFError < RuntimeError
-    # :stopdoc:
-    def initialize(message = "")
-      super(message)
-    end
-    # :startdoc:
-  end
 end

data/test/tc_create.rb

@@ -42,6 +42,9 @@ class TestCreation < Test::Unit::TestCase
 
       assert_nothing_raised do
         UCF::Container.create(filename) do |c|
+          assert(c.on_disk?)
+          refute(c.in_memory?)
+
           assert(c.find_entry("mimetype").localHeaderOffset == 0)
         end
       end
@@ -61,6 +64,9 @@ class TestCreation < Test::Unit::TestCase
 
       assert_nothing_raised do
         UCF::Container.create(filename) do |c|
+          assert(c.on_disk?)
+          refute(c.in_memory?)
+
           assert(c.find_entry("mimetype").localHeaderOffset == 0)
         end
       end
@@ -71,31 +77,60 @@ class TestCreation < Test::Unit::TestCase
     end
   end
 
-  # Check creation of stuff in ucf files.
+  # Check creation of stuff in ucf files. Check the commit status a few times
+  # to ensure that what we expect to happen, happens.
   def test_create_contents_file
     Dir.mktmpdir do |dir|
       filename = File.join(dir, "test.ucf")
 
       assert_nothing_raised do
         UCF::Container.create(filename) do |ucf|
+          assert(ucf.on_disk?)
+          refute(ucf.in_memory?)
+
           ucf.file.open("test.txt", "w") do |f|
             f.print "testing"
           end
 
+          assert(ucf.commit_required?)
+          assert(ucf.commit)
+          refute(ucf.commit_required?)
+          refute(ucf.commit)
+
           ucf.dir.mkdir("dir1")
           ucf.mkdir("dir2")
+
+          assert(ucf.commit_required?)
+          assert(ucf.commit)
+          refute(ucf.commit_required?)
+          refute(ucf.commit)
+
+          ucf.comment = "A comment!"
+
+          assert(ucf.commit_required?)
+          assert(ucf.commit)
+          refute(ucf.commit_required?)
+          refute(ucf.commit)
         end
       end
 
       assert_nothing_raised(UCF::MalformedUCFError, Zip::ZipError) do
         UCF::Container.open(filename) do |ucf|
+          assert(ucf.on_disk?)
+          refute(ucf.in_memory?)
+
           assert(ucf.file.exists?("test.txt"))
           assert(ucf.file.exists?("dir1"))
           assert(ucf.file.exists?("dir2"))
-          assert(!ucf.file.exists?("dir3"))
+          refute(ucf.file.exists?("dir3"))
 
           text = ucf.file.read("test.txt")
           assert_equal("testing", text)
+
+          assert_equal("A comment!", ucf.comment)
+
+          refute(ucf.commit_required?)
+          refute(ucf.commit)
         end
       end
     end

data/test/tc_read.rb

@@ -40,7 +40,7 @@ class TestRead < Test::Unit::TestCase
       UCF::Container.verify!($file_null)
     end
 
-    assert(!UCF::Container.verify($file_null))
+    refute(UCF::Container.verify($file_null))
   end
 
   # Check that the empty ucf file does verify.
@@ -58,7 +58,7 @@ class TestRead < Test::Unit::TestCase
       UCF::Container.verify!($zip_empty)
     end
 
-    assert(!UCF::Container.verify($zip_empty))
+    refute(UCF::Container.verify($zip_empty))
   end
 
   # Check that a compressed mimetype file is detected.
@@ -67,7 +67,7 @@ class TestRead < Test::Unit::TestCase
       UCF::Container.verify!($ucf_compressed_mimetype)
     end
 
-    assert(!UCF::Container.verify($ucf_compressed_mimetype))
+    refute(UCF::Container.verify($ucf_compressed_mimetype))
   end
 
   # Check the raw mimetype bytes
@@ -79,10 +79,13 @@ class TestRead < Test::Unit::TestCase
     assert_not_equal("application/epub+zip", compressed_mimetype[38..57])
   end
 
-  # Check reading files out of a ucf file.
+  # Check reading files out of a ucf file and make sure we don't change it.
   def test_read_files_from_ucf
     assert_nothing_raised(UCF::MalformedUCFError, Zip::ZipError) do
       UCF::Container.open($ucf_example) do |ucf|
+        assert(ucf.on_disk?)
+        refute(ucf.in_memory?)
+
         assert(ucf.file.exists?("greeting.txt"))
 
         greeting = ucf.file.read("greeting.txt")
@@ -92,6 +95,11 @@ class TestRead < Test::Unit::TestCase
         assert(ucf.file.directory?("dir"))
 
         assert(ucf.file.exists?("dir/code.rb"))
+
+        assert_equal("This is an example UCF file!", ucf.comment)
+
+        refute(ucf.commit_required?)
+        refute(ucf.commit)
       end
     end
   end

data/test/tc_reserved_names.rb

@@ -32,8 +32,78 @@
 
 require 'ucf'
 
+# A class to test the overriding of reserved names.
+class NewUCF < UCF::Container
+  def reserved_files
+    super + ["index.html"]
+  end
+
+  def reserved_directories
+    super + ["src", "test", "lib"]
+  end
+end
+
 class TestReservedNames < Test::Unit::TestCase
 
+  # Check the reserved names stuff all works correctly, baring in mind that
+  # such comparisons for UCF documents should be case sensitive.
+  def test_reserved_names
+    UCF::Container.open($ucf_example) do |ucf|
+      assert_equal(1, ucf.reserved_files.length)
+      assert_equal(["mimetype"], ucf.reserved_files)
+      assert(ucf.reserved_entry?("mimetype"))
+      assert(ucf.reserved_entry?("mimetype/"))
+      assert(ucf.reserved_entry?("MimeType"))
+
+      assert_equal(1, ucf.reserved_directories.length)
+      assert_equal(["META-INF"], ucf.reserved_directories)
+      assert(ucf.reserved_entry?("META-INF"))
+      assert(ucf.reserved_entry?("META-INF/"))
+      assert(ucf.reserved_entry?("MeTa-iNf"))
+      assert(ucf.reserved_entry?("MeTa-iNf/"))
+
+      assert_equal(2, ucf.reserved_names.length)
+      assert_equal(["mimetype", "META-INF"], ucf.reserved_names)
+
+      refute(ucf.reserved_entry?("This_should_fail"))
+      refute(ucf.reserved_entry?("META_INF"))
+      refute(ucf.reserved_entry?("META_INF/"))
+    end
+  end
+
+  # Check that overriding the reserved names in a sub-class works correctly
+  def test_subclass_reserved_names
+    NewUCF.open($ucf_example) do |ucf|
+      assert_equal(2, ucf.reserved_files.length)
+      assert_equal(["mimetype", "index.html"], ucf.reserved_files)
+      assert(ucf.reserved_entry?("mimetype"))
+      assert(ucf.reserved_entry?("mimetype/"))
+      assert(ucf.reserved_entry?("MimeType"))
+      assert(ucf.reserved_entry?("index.html"))
+      assert(ucf.reserved_entry?("Index.HTML"))
+
+      assert_equal(4, ucf.reserved_directories.length)
+      assert_equal(["META-INF", "src", "test", "lib"], ucf.reserved_directories)
+      assert(ucf.reserved_entry?("META-INF"))
+      assert(ucf.reserved_entry?("META-INF/"))
+      assert(ucf.reserved_entry?("MeTa-iNf"))
+      assert(ucf.reserved_entry?("src"))
+      assert(ucf.reserved_entry?("SRC"))
+      assert(ucf.reserved_entry?("test"))
+      assert(ucf.reserved_entry?("lib"))
+      assert(ucf.reserved_entry?("lIb/"))
+
+      assert_equal(6, ucf.reserved_names.length)
+      assert_equal(["mimetype", "index.html", "META-INF", "src", "test", "lib"],
+        ucf.reserved_names)
+
+      refute(ucf.reserved_entry?("This_should_fail"))
+      refute(ucf.reserved_entry?("META_INF"))
+      refute(ucf.reserved_entry?("META_INF/"))
+      refute(ucf.reserved_entry?("index.htm"))
+    end
+  end
+
   # Check that nothing happens when trying to delete the mimetype file.
   def test_delete_mimetype
     UCF::Container.open($ucf_example) do |ucf|
@@ -49,7 +119,7 @@ class TestReservedNames < Test::Unit::TestCase
       assert(ucf.file.exists?("mimetype"))
       assert_nil(ucf.rename("mimetype", "something-else"))
       assert(ucf.file.exists?("mimetype"))
-      assert(!ucf.file.exists?("something-else"))
+      refute(ucf.file.exists?("something-else"))
     end
   end
 
@@ -63,6 +133,34 @@ class TestReservedNames < Test::Unit::TestCase
     end
   end
 
+  # Check that an exception is raised when trying to add file with a reserved
+  # name.
+  def test_add_reserved
+    UCF::Container.open($ucf_empty) do |ucf|
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.add("META-INF", $zip_empty)
+      end
+    end
+  end
+
+  # Check that an exception is raised when trying to add file with a reserved
+  # name to a subclassed container.
+  def test_subclass_add_reserved
+    NewUCF.open($ucf_empty) do |ucf|
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.add("META-INF", $zip_empty)
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.add("index.html", $zip_empty)
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.add("SRC", $zip_empty)
+      end
+    end
+  end
+
   # Check that nothing happens when trying to delete the META-INF directory.
   def test_delete_metainf
     UCF::Container.open($ucf_example) do |ucf|
@@ -77,4 +175,134 @@ class TestReservedNames < Test::Unit::TestCase
     end
   end
 
+  # Check that an exception is raised when trying to create a directory with a
+  # reserved name.
+  def test_mkdir_reserved
+    UCF::Container.open($ucf_empty) do |ucf|
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.mkdir("META-INF")
+      end
+    end
+  end
+
+  # Check that an exception is raised when trying to create a directory with a
+  # reserved name in a subclassed container.
+  def test_subclass_mkdir_reserved
+    NewUCF.open($ucf_empty) do |ucf|
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.mkdir("META-INF")
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.mkdir("index.html")
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.mkdir("Lib")
+      end
+    end
+  end
+
+  # Check that a file cannot be renamed to one of the reserved names.
+  def test_rename_to_reserved
+    UCF::Container.open($ucf_example) do |ucf|
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.rename("dir/code.rb", "mimetype")
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.rename("dir", "META-INF")
+      end
+    end
+  end
+
+  # Check that a file cannot be renamed to one of the reserved names in a
+  # subclassed container.
+  def test_subclass_rename_to_reserved
+    NewUCF.open($ucf_example) do |ucf|
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.rename("dir/code.rb", "mimetype")
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.rename("dir", "META-INF")
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.rename("dir/code.rb", "index.html")
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.rename("dir", "Test")
+      end
+    end
+  end
+
+  # Check that the ruby-like File and Dir classes respect reserved names.
+  def test_file_dir_ops_reserved
+    UCF::Container.open($ucf_empty) do |ucf|
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.file.open("META-INF", "w") do |f|
+          f.puts "TESTING"
+        end
+      end
+
+      assert_nothing_raised(UCF::ReservedNameClashError) do
+        ucf.file.open("mimetype") do |f|
+          assert_equal("application/epub+zip", f.read)
+        end
+      end
+
+      assert_nothing_raised(UCF::ReservedNameClashError) do
+        ucf.file.delete("mimetype")
+        assert(ucf.file.exists?("mimetype"))
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.dir.mkdir("meta-inf")
+      end
+    end
+  end
+
+  # Check that the ruby-like File and Dir classes respect reserved names in a
+  # subclassed container.
+  def test_subclass_file_dir_ops_reserved
+    NewUCF.open($ucf_empty) do |ucf|
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.file.open("META-INF", "w") do |f|
+          f.puts "TESTING"
+        end
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.file.open("INDEX.HTML", "w") do |f|
+          f.puts "TESTING"
+        end
+      end
+
+      assert_nothing_raised(UCF::ReservedNameClashError) do
+        ucf.file.open("mimetype") do |f|
+          assert_equal("application/epub+zip", f.read)
+        end
+      end
+
+      assert_nothing_raised(UCF::ReservedNameClashError) do
+        ucf.file.delete("mimetype")
+        assert(ucf.file.exists?("mimetype"))
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.dir.mkdir("meta-inf")
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.dir.mkdir("TEST")
+      end
+
+      assert_raises(UCF::ReservedNameClashError) do
+        ucf.dir.mkdir("index.html")
+      end
+    end
+  end
+
 end

data/ucf.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "ucf"
-  s.version = "0.0.2"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Robert Haines"]
-  s.date = "2013-05-29"
+  s.date = "2013-06-03"
   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."
   s.email = ["support@mygrid.org.uk"]
   s.extra_rdoc_files = [
@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
     "examples/verify_ucf.rb",
     "lib/ucf.rb",
     "lib/ucf/container.rb",
+    "lib/ucf/exceptions.rb",
     "test/data/compressed_mimetype.ucf",
     "test/data/empty.ucf",
     "test/data/empty.zip",

data/version.yml

@@ -1,4 +1,4 @@
 ---
   :major: 0
-  :minor: 0
-  :patch: 2
+  :minor: 1
+  :patch: 0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ucf
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-29 00:00:00.000000000 Z
+date: 2013-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -95,6 +95,7 @@ files:
 - examples/verify_ucf.rb
 - lib/ucf.rb
 - lib/ucf/container.rb
+- lib/ucf/exceptions.rb
 - test/data/compressed_mimetype.ucf
 - test/data/empty.ucf
 - test/data/empty.zip