ucf 0.0.1 → 0.0.2

data/Changes.rdoc

@@ -1,5 +1,22 @@
 = Changes log for the UCF Ruby Gem
 
+== Version 0.0.2
+
+* Update the main ReadMe file.
+* Add support for multiple reserved names and fix checks.
+* Ensure UCF document is closed after verifying it.
+* Expose the "each" method for enumerating UCF entries.
+* Expose the "size" method to count UCF entries.
+* Add an example program to list UCF contents.
+* Add a method to directly iterate over UCF entries.
+
+== Version 0.0.1
+
+* Very basic UCF facilities complete (plus examples).
+* Two ways of verifying UCF files.
+* API documentation added.
+* Add tests.
+
 == About this Changes file
 
 This file is, at least in part, generated by the following command:

data/Rakefile

@@ -48,7 +48,7 @@ Jeweler::Tasks.new do |s|
   s.version          = UCF::Version::STRING
   s.authors          = ["Robert Haines"]
   s.email            = ["support@mygrid.org.uk"]
-  s.homepage         = "http://www.taverna.org.uk/"
+  s.homepage         = "http://mygrid.github.io/ruby-ucf/"
   s.platform         = Gem::Platform::RUBY
   s.summary          = "Universal Container Format (UCF) Ruby Library"
   s.description      = "A Ruby library for working with Universal Container "\

data/ReadMe.rdoc

@@ -2,28 +2,34 @@
 
 Authors::     Robert Haines
 Contact::     mailto:support@mygrid.org.uk
-URL::         http://www.taverna.org.uk/
+Homepage::    http://mygrid.github.io/ruby-ucf
+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
 
 
 == Synopsis
 
-This is a Ruby library for working with UCF files.
+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.
 
-See https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format
+<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
+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.
 
-This library is a work in progress!
-
-Examples are provided in the examples directory.
+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.
 
 == What this library can not do yet
 
-The basic requirements of a UCF file are all implemented but there are a
+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 files that
-  are resident on disk.
+* In memory operation. Presently all operations are performed on documents
+  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

data/examples/ucfinfo

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# 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'
+
+def usage
+  puts "ucfinfo ucf-file"
+  exit 1
+end
+
+usage unless ARGV.length == 1
+
+ucffile = ARGV[0]
+
+begin
+  ucf = UCF::Container.open(ucffile)
+rescue UCF::MalformedUCFError, Zip::ZipError => err
+  puts err.to_s
+  exit 1
+end
+
+puts "Archive: #{ucf.to_s}"
+puts "UCF file size: #{File.size(ucffile)} bytes, number of entries: #{ucf.size}"
+
+total_size = 0
+total_comp = 0
+
+ucf.each do |entry|
+  total_size += entry.size
+  total_comp += entry.compressed_size
+  comp = entry.compression_method == 0 ? "stor" : "defN"
+  size = entry.size.to_s.rjust(8)
+  puts "#{size} #{comp} #{entry.time} #{entry.name}"
+end
+
+ratio = ((total_size - total_comp) / total_size.to_f) * 100
+puts "%d files, %d bytes uncompressed, %d bytes compressed: %.1f%%" %
+  [ucf.size, total_size, total_comp, ratio]

data/lib/ucf/container.rb

@@ -47,9 +47,9 @@ module UCF
   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
+    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
 
     private_class_method :new
 
@@ -59,7 +59,12 @@ module UCF
 
     # :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.
     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."
@@ -86,6 +91,27 @@ module UCF
       Container.open(filename, &block)
     end
 
+    # :call-seq:
+    #   Container.each_entry -> Enumerator
+    #   Container.each_entry {|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.
+    def Container.each_entry(filename, &block)
+      c = new(filename)
+
+      if block_given?
+        begin
+          c.each(&block)
+        ensure
+          c.close
+        end
+      end
+
+      c.each
+    end
+
     # :call-seq:
     #   Container.open(filename) -> container
     #   Container.open(filename) {|container| ...}
@@ -129,28 +155,29 @@ module UCF
     # 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)
+      new(filename).close
       nil
     end
 
     # :call-seq:
     #   remove(entry)
     #
-    # Removes the specified entry. If asked to remove the special mimetype
-    # header file this method will do nothing.
+    # Removes the specified entry. If asked to remove any reserved files such
+    # as the special mimetype header file this method will do nothing.
     def remove(entry)
-      return if mimetype_entry?(entry)
+      return if reserved_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.
+    # 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.
     def rename(entry, new_name, &continue_on_exists_proc)
-      return if mimetype_entry?(entry)
+      return if reserved_entry?(entry)
       @zipfile.rename(entry, new_name, continue_on_exists_proc)
     end
 
@@ -158,10 +185,10 @@ module UCF
     #   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.
+    # 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 mimetype_entry?(entry)
+      return if reserved_entry?(entry)
       @zipfile.replace(entry, src_path)
     end
 
@@ -193,9 +220,11 @@ module UCF
       @zipfile.read(MIMETYPE_FILE)
     end
 
-    def mimetype_entry?(entry)
-      name = entry.kind_of?(ZipEntry) ? entry.name : entry
-      name == MIMETYPE_FILE
+    # 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
@@ -245,6 +274,16 @@ module UCF
     #
     # See the rubyzip documentation for details.
 
+    ##
+    # :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: extract
     # :call-seq:
@@ -340,5 +379,12 @@ module UCF
     #
     # 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

data/test/tc_reserved_names.rb

@@ -0,0 +1,80 @@
+# 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 TestReservedNames < Test::Unit::TestCase
+
+  # Check that nothing happens when trying to delete the mimetype file.
+  def test_delete_mimetype
+    UCF::Container.open($ucf_example) do |ucf|
+      assert(ucf.file.exists?("mimetype"))
+      assert_nil(ucf.remove("mimetype"))
+      assert(ucf.file.exists?("mimetype"))
+    end
+  end
+
+  # Check that nothing happens when trying to rename the mimetype file.
+  def test_rename_mimetype
+    UCF::Container.open($ucf_example) do |ucf|
+      assert(ucf.file.exists?("mimetype"))
+      assert_nil(ucf.rename("mimetype", "something-else"))
+      assert(ucf.file.exists?("mimetype"))
+      assert(!ucf.file.exists?("something-else"))
+    end
+  end
+
+  # Check that nothing happens when trying to replace the contents of the
+  # mimetype file.
+  def test_replace_mimetype
+    UCF::Container.open($ucf_example) do |ucf|
+      assert(ucf.file.exists?("mimetype"))
+      assert_nil(ucf.replace("mimetype", $zip_empty))
+      assert_equal("application/epub+zip", ucf.file.read("mimetype"))
+    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|
+      assert_nil(ucf.remove("META-INF"))
+    end
+  end
+
+  # Check that nothing happens when trying to rename the META-INF directory.
+  def test_rename_metainf
+    UCF::Container.open($ucf_example) do |ucf|
+      assert_nil(ucf.rename("META-INF", "something-else"))
+    end
+  end
+
+end

data/test/ts_ucf.rb

@@ -42,3 +42,4 @@ $ucf_example = "test/data/example.ucf"
 # Run test cases.
 require 'tc_create'
 require 'tc_read'
+require 'tc_reserved_names'

data/ucf.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "ucf"
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   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.date = "2013-05-29"
   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 = [
@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
     "Rakefile",
     "ReadMe.rdoc",
     "examples/create_ucf.rb",
+    "examples/ucfinfo",
     "examples/verify_ucf.rb",
     "lib/ucf.rb",
     "lib/ucf/container.rb",
@@ -33,11 +34,12 @@ Gem::Specification.new do |s|
     "test/data/null.file",
     "test/tc_create.rb",
     "test/tc_read.rb",
+    "test/tc_reserved_names.rb",
     "test/ts_ucf.rb",
     "ucf.gemspec",
     "version.yml"
   ]
-  s.homepage = "http://www.taverna.org.uk/"
+  s.homepage = "http://mygrid.github.io/ruby-ucf/"
   s.rdoc_options = ["-N", "--tab-width=2", "--main=ReadMe.rdoc"]
   s.require_paths = ["lib"]
   s.rubygems_version = "1.8.21"

data/version.yml

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ucf
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-24 00:00:00.000000000 Z
+date: 2013-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -91,6 +91,7 @@ files:
 - Rakefile
 - ReadMe.rdoc
 - examples/create_ucf.rb
+- examples/ucfinfo
 - examples/verify_ucf.rb
 - lib/ucf.rb
 - lib/ucf/container.rb
@@ -101,10 +102,11 @@ files:
 - test/data/null.file
 - test/tc_create.rb
 - test/tc_read.rb
+- test/tc_reserved_names.rb
 - test/ts_ucf.rb
 - ucf.gemspec
 - version.yml
-homepage: http://www.taverna.org.uk/
+homepage: http://mygrid.github.io/ruby-ucf/
 licenses: []
 post_install_message: 
 rdoc_options: