ucf 0.0.1

data/Changes.rdoc

@@ -0,0 +1,7 @@
+= Changes log for the UCF Ruby Gem
+
+== About this Changes file
+
+This file is, at least in part, generated by the following command:
+
+ $ git log --pretty=format:"* %s" --reverse --no-merges <commit-hash>..

data/Licence.rdoc

@@ -0,0 +1,29 @@
+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.

data/Rakefile

@@ -0,0 +1,83 @@
+# 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
+
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'jeweler'
+
+# we need to add lib to the path because we're not installed yet!
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), "lib")
+require 'ucf'
+
+task :default => [:test]
+
+Jeweler::Tasks.new do |s|
+  s.name             = "ucf"
+  s.version          = UCF::Version::STRING
+  s.authors          = ["Robert Haines"]
+  s.email            = ["support@mygrid.org.uk"]
+  s.homepage         = "http://www.taverna.org.uk/"
+  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."
+  s.require_path     = "lib"
+  s.test_file        = "test/ts_ucf.rb"
+  s.has_rdoc         = true
+  s.extra_rdoc_files = ["ReadMe.rdoc", "Licence.rdoc", "Changes.rdoc"]
+  s.rdoc_options     = ["-N", "--tab-width=2", "--main=ReadMe.rdoc"]
+  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')
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/ts_ucf.rb']
+  t.verbose = true
+end
+
+RDoc::Task.new do |r|
+  r.main = "ReadMe.rdoc"
+  lib = Dir.glob("lib/**/*.rb")
+  r.rdoc_files.include("ReadMe.rdoc", "Licence.rdoc", "Changes.rdoc", lib)
+  r.options << "-t Universal Container Format Ruby Library version " +
+    "#{UCF::Version::STRING}"
+  r.options << "-N"
+  r.options << "--tab-width=2"
+end

data/ReadMe.rdoc

@@ -0,0 +1,36 @@
+= Universal Container Format (UCF) Ruby Library
+
+Authors::     Robert Haines
+Contact::     mailto:support@mygrid.org.uk
+URL::         http://www.taverna.org.uk/
+Licence::     BSD (See Licence file or http://www.opensource.org/licenses/bsd-license.php)
+Copyright::   (c) 2013 The University of Manchester, UK
+
+
+== Synopsis
+
+This is a Ruby library for working with UCF files.
+
+See https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format
+
+This library is a work in progress!
+
+Examples are provided in the examples directory.
+
+== What this library can not do yet
+
+The basic requirements of a UCF file 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 files that
+  are resident on disk.
+* 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).
+* Encryption (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

@@ -0,0 +1,58 @@
+# 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
+
+require 'rubygems'
+require 'ucf'
+
+ZIP_FILE = "example.zip"
+file = ARGV.length > 0 ? ARGV[0] : ZIP_FILE
+
+File.delete(file) if File.exists?(file)
+
+begin
+  UCF::Container.create(file) do |c|
+
+    # Add a cheery greeting file from a string.
+    c.file.open("greeting.txt", "w") do |f|
+      f.puts "Hello, World!"
+    end
+
+    # Create a subdirectory.
+    c.dir.mkdir("dir")
+
+    # Copy this example code in straight from a file.
+    c.add("dir/code.rb", __FILE__)
+  end
+rescue UCF::MalformedUCFError, Zip::ZipError => err
+  puts err.to_s
+  exit 1
+end

data/examples/verify_ucf.rb

@@ -0,0 +1,44 @@
+# 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
+
+require 'rubygems'
+require 'ucf'
+
+ZIP_FILE = "example.zip"
+file = ARGV.length > 0 ? ARGV[0] : ZIP_FILE
+
+begin
+  UCF::Container.verify!(file)
+rescue UCF::MalformedUCFError, Zip::ZipError => err
+  puts err.to_s
+  exit 1
+end

data/lib/ucf/container.rb

@@ -0,0 +1,344 @@
+# 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
+
+require 'forwardable'
+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
+  # 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
+  #
+  # There are code examples available with the source code of this library.
+  class Container
+
+    extend Forwardable
+    def_delegators :@zipfile, :add, :close, :comment, :commit, :dir, :extract,
+      :file, :find_entry, :get_entry, :get_input_stream, :get_output_stream,
+      :glob, :mkdir, :name, :read
+
+    private_class_method :new
+
+    # The mime-type of this UCF file. By default this is
+    # "application/epub+zip".
+    attr_reader :mimetype
+
+    # :stopdoc:
+    DEFAULT_MIMETYPE = "application/epub+zip"
+    MIMETYPE_FILE = "mimetype"
+
+    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)
+
+      @mimetype = read_mimetype
+    end
+    # :startdoc:
+
+    # :call-seq:
+    #   Container.create(filename, mimetype = "application/epub+zip") -> container
+    #   Container.create(filename, mimetype = "application/epub+zip") {|container| ...}
+    #
+    # Create a new UCF file 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
+
+      Container.open(filename, &block)
+    end
+
+    # :call-seq:
+    #   Container.open(filename) -> container
+    #   Container.open(filename) {|container| ...}
+    #
+    # Open an existing UCF file 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 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.
+    def Container.verify(filename)
+      begin
+        Container.verify!(filename)
+      rescue
+        return false
+      end
+
+      true
+    end
+
+    # :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).
+    def Container.verify!(filename)
+      new(filename)
+      nil
+    end
+
+    # :call-seq:
+    #   remove(entry)
+    #
+    # Removes the specified entry. If asked to remove the special mimetype
+    # header file this method will do nothing.
+    def remove(entry)
+      return if mimetype_entry?(entry)
+      @zipfile.remove(entry)
+    end
+
+    # :call-seq:
+    #   rename(entry, new_name, &continueOnExistsProc)
+    #
+    # Renames the specified entry. If asked to rename the special mimetype
+    # header file this method will do nothing. See the rubyzip documentation
+    # for details of the +continue_on_exists_proc+ parameter.
+    def rename(entry, new_name, &continue_on_exists_proc)
+      return if mimetype_entry?(entry)
+      @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 the special mimetype header file this
+    # method will do nothing.
+    def replace(entry, src_path)
+      return if mimetype_entry?(entry)
+      @zipfile.replace(entry, src_path)
+    end
+
+    # :call-seq:
+    #   to_s -> String
+    #
+    # Return a String representation of this UCF file.
+    def to_s
+      @zipfile.to_s + " - #{@mimetype}"
+    end
+
+    private
+
+    def open_and_check_ucf(filename)
+      file = ::Zip::ZipFile.new(filename)
+
+      # 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
+      if entry.compression_method != ::Zip::ZipEntry::STORED
+        raise MalformedUCFError.new(ERR_MT_BAD_COMP)
+      end
+
+      file
+    end
+
+    def read_mimetype
+      @zipfile.read(MIMETYPE_FILE)
+    end
+
+    def mimetype_entry?(entry)
+      name = entry.kind_of?(ZipEntry) ? entry.name : entry
+      name == MIMETYPE_FILE
+    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.
+
+    ##
+    # :method: commit
+    # :call-seq:
+    #   commit
+    #
+    # Commits changes that have been made since the previous commit to the
+    # UCF file.
+
+    ##
+    # :method: dir
+    # :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 file on which this method is
+    # invoked.
+    #
+    # See the rubyzip documentation for details.
+
+    ##
+    # :method: extract
+    # :call-seq:
+    #   extract(entry, dest_path, &on_exists_proc)
+    #
+    # Extracts the specified entry 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+.
+
+    ##
+    # :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.
+
+    ##
+    # :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: 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.
+    #
+    # 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.
+
+    ##
+    # :method: read
+    # :call-seq:
+    #   read(entry) -> String
+    #
+    # Returns a string containing the contents of the specified entry.
+
+  end
+end

data/lib/ucf.rb

@@ -0,0 +1,61 @@
+# 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
+
+require 'yaml'
+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.
+module UCF
+
+  # Library version information.
+  module Version
+    # Version information in a Hash
+    INFO = YAML.load_file(File.join(File.dirname(__FILE__), "..",
+      "version.yml"))
+
+    # Version number as a String
+    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

@@ -0,0 +1,104 @@
+# 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
+
+require 'tmpdir'
+require 'ucf'
+
+class TestCreation < Test::Unit::TestCase
+
+  # Check creation of standard empty ucf files.
+  def test_create_standard_file
+    Dir.mktmpdir do |dir|
+      filename = File.join(dir, "test.ucf")
+
+      assert_nothing_raised do
+        UCF::Container.create(filename) do |c|
+          assert(c.find_entry("mimetype").localHeaderOffset == 0)
+        end
+      end
+
+      assert_nothing_raised(UCF::MalformedUCFError, Zip::ZipError) do
+        UCF::Container.verify!(filename)
+      end
+    end
+  end
+
+  # Check creation of empty ucf files with a different mimetype.
+  def test_create_mimetype_file
+    mimetype = "application/x-something-really-odd"
+
+    Dir.mktmpdir do |dir|
+      filename = File.join(dir, "test.ucf")
+
+      assert_nothing_raised do
+        UCF::Container.create(filename) do |c|
+          assert(c.find_entry("mimetype").localHeaderOffset == 0)
+        end
+      end
+
+      assert_nothing_raised(UCF::MalformedUCFError, Zip::ZipError) do
+        UCF::Container.verify!(filename)
+      end
+    end
+  end
+
+  # Check creation of stuff in ucf files.
+  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|
+          ucf.file.open("test.txt", "w") do |f|
+            f.print "testing"
+          end
+
+          ucf.dir.mkdir("dir1")
+          ucf.mkdir("dir2")
+        end
+      end
+
+      assert_nothing_raised(UCF::MalformedUCFError, Zip::ZipError) do
+        UCF::Container.open(filename) do |ucf|
+          assert(ucf.file.exists?("test.txt"))
+          assert(ucf.file.exists?("dir1"))
+          assert(ucf.file.exists?("dir2"))
+          assert(!ucf.file.exists?("dir3"))
+
+          text = ucf.file.read("test.txt")
+          assert_equal("testing", text)
+        end
+      end
+    end
+  end
+
+end

data/test/tc_read.rb

@@ -0,0 +1,99 @@
+# 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
+
+require 'ucf'
+
+class TestRead < Test::Unit::TestCase
+
+  # Check that the null file does not verify.
+  def test_verify_null_file
+    assert_raise(Zip::ZipError) do
+      UCF::Container.verify!($file_null)
+    end
+
+    assert(!UCF::Container.verify($file_null))
+  end
+
+  # Check that the empty ucf file does verify.
+  def test_verify_empty_ucf
+    assert_nothing_raised(UCF::MalformedUCFError, Zip::ZipError) do
+      UCF::Container.verify!($ucf_empty)
+    end
+
+    assert(UCF::Container.verify($ucf_empty))
+  end
+
+  # Check that the empty zip file does not verify.
+  def test_verify_empty_zip
+    assert_raise(UCF::MalformedUCFError) do
+      UCF::Container.verify!($zip_empty)
+    end
+
+    assert(!UCF::Container.verify($zip_empty))
+  end
+
+  # Check that a compressed mimetype file is detected.
+  def test_verify_compressed_mimetype
+    assert_raise(UCF::MalformedUCFError) do
+      UCF::Container.verify!($ucf_compressed_mimetype)
+    end
+
+    assert(!UCF::Container.verify($ucf_compressed_mimetype))
+  end
+
+  # Check the raw mimetype bytes
+  def test_raw_mimetypes
+    empty_ucf = File.read($ucf_empty)
+    assert_equal("application/epub+zip", empty_ucf[38..57])
+
+    compressed_mimetype = File.read($ucf_compressed_mimetype)
+    assert_not_equal("application/epub+zip", compressed_mimetype[38..57])
+  end
+
+  # Check reading files out of a ucf file.
+  def test_read_files_from_ucf
+    assert_nothing_raised(UCF::MalformedUCFError, Zip::ZipError) do
+      UCF::Container.open($ucf_example) do |ucf|
+        assert(ucf.file.exists?("greeting.txt"))
+
+        greeting = ucf.file.read("greeting.txt")
+        assert_equal("Hello, World!\n", greeting)
+
+        assert(ucf.file.exists?("dir"))
+        assert(ucf.file.directory?("dir"))
+
+        assert(ucf.file.exists?("dir/code.rb"))
+      end
+    end
+  end
+
+end

data/test/ts_ucf.rb

@@ -0,0 +1,44 @@
+# 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
+
+require 'test/unit'
+require 'ucf'
+
+$file_null = "test/data/null.file"
+$ucf_empty = "test/data/empty.ucf"
+$zip_empty = "test/data/empty.zip"
+$ucf_compressed_mimetype = "test/data/compressed_mimetype.ucf"
+$ucf_example = "test/data/example.ucf"
+
+# Run test cases.
+require 'tc_create'
+require 'tc_read'

data/ucf.gemspec

@@ -0,0 +1,68 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "ucf"
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Robert Haines"]
+  s.date = "2013-05-24"
+  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 = [
+    "Changes.rdoc",
+    "Licence.rdoc",
+    "ReadMe.rdoc"
+  ]
+  s.files = [
+    "Changes.rdoc",
+    "Licence.rdoc",
+    "Rakefile",
+    "ReadMe.rdoc",
+    "examples/create_ucf.rb",
+    "examples/verify_ucf.rb",
+    "lib/ucf.rb",
+    "lib/ucf/container.rb",
+    "test/data/compressed_mimetype.ucf",
+    "test/data/empty.ucf",
+    "test/data/empty.zip",
+    "test/data/example.ucf",
+    "test/data/null.file",
+    "test/tc_create.rb",
+    "test/tc_read.rb",
+    "test/ts_ucf.rb",
+    "ucf.gemspec",
+    "version.yml"
+  ]
+  s.homepage = "http://www.taverna.org.uk/"
+  s.rdoc_options = ["-N", "--tab-width=2", "--main=ReadMe.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.21"
+  s.summary = "Universal Container Format (UCF) Ruby Library"
+  s.test_files = ["test/ts_ucf.rb"]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rake>, ["~> 10.0.4"])
+      s.add_development_dependency(%q<rdoc>, ["~> 4.0.1"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
+      s.add_runtime_dependency(%q<rubyzip>, ["~> 0.9.9"])
+    else
+      s.add_dependency(%q<rake>, ["~> 10.0.4"])
+      s.add_dependency(%q<rdoc>, ["~> 4.0.1"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
+      s.add_dependency(%q<rubyzip>, ["~> 0.9.9"])
+    end
+  else
+    s.add_dependency(%q<rake>, ["~> 10.0.4"])
+    s.add_dependency(%q<rdoc>, ["~> 4.0.1"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
+    s.add_dependency(%q<rubyzip>, ["~> 0.9.9"])
+  end
+end
+

data/version.yml

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

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: ucf
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Robert Haines
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.0.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.0.4
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.4
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+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.
+email:
+- support@mygrid.org.uk
+executables: []
+extensions: []
+extra_rdoc_files:
+- Changes.rdoc
+- Licence.rdoc
+- ReadMe.rdoc
+files:
+- Changes.rdoc
+- Licence.rdoc
+- Rakefile
+- ReadMe.rdoc
+- examples/create_ucf.rb
+- examples/verify_ucf.rb
+- lib/ucf.rb
+- lib/ucf/container.rb
+- test/data/compressed_mimetype.ucf
+- test/data/empty.ucf
+- test/data/empty.zip
+- test/data/example.ucf
+- test/data/null.file
+- test/tc_create.rb
+- test/tc_read.rb
+- test/ts_ucf.rb
+- ucf.gemspec
+- version.yml
+homepage: http://www.taverna.org.uk/
+licenses: []
+post_install_message: 
+rdoc_options:
+- -N
+- --tab-width=2
+- --main=ReadMe.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: Universal Container Format (UCF) Ruby Library
+test_files:
+- test/ts_ucf.rb