ucf 0.1.0 → 0.5.0

data/Changes.rdoc

@@ -1,5 +1,16 @@
 = Changes log for the UCF Ruby Gem
 
+== Version 0.5.0
+
+* Add support for managed entries in the container.
+* Verify and "optional" functionality for ManagedEntry.
+* Use reserved and managed entry mixins for managed directories.
+* Better initialization of managed entry support.
+* Fix creation of subclassed Container objects.
+* Add extra tests for managed entries.
+* Make file validation more flexible.
+* Fix the source of failing validation messages.
+
 == Version 0.1.0
 
 * Improvements to the reserved names code to allow sub-classing.

data/ReadMe.rdoc

@@ -33,8 +33,9 @@ number of optional features that are not yet provided.
   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.
+* Validation of file contents in the META-INF directory. Most of the machinery
+  for this has been implemented but files are not validated against the schema
+  yet.
 * 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/lib/ucf.rb

@@ -32,6 +32,12 @@
 
 require 'yaml'
 require 'ucf/exceptions'
+require 'ucf/entries/reserved'
+require 'ucf/entries/managed'
+require 'ucf/entries/entry'
+require 'ucf/entries/file'
+require 'ucf/entries/directory'
+require 'ucf/meta-inf'
 require 'ucf/container'
 
 # This is a ruby library to read and write UCF files in PK Zip format. See the

data/lib/ucf/container.rb

@@ -46,11 +46,13 @@ module UCF
   #
   # There are code examples available with the source code of this library.
   class Container
+    include ReservedNames
+    include ManagedEntries
 
     extend Forwardable
     def_delegators :@zipfile, :comment, :comment=, :commit_required?, :each,
-      :extract, :find_entry, :get_entry, :get_input_stream, :glob, :name,
-      :read, :size
+      :entries, :extract, :find_entry, :get_entry, :get_input_stream, :glob,
+      :name, :read, :size
 
     private_class_method :new
 
@@ -61,17 +63,22 @@ module UCF
     # :stopdoc:
     DEFAULT_MIMETYPE = "application/epub+zip"
 
-    # Reserved file and directory names for standard UCF documents.
+    # The reserved mimetype file name for standard UCF documents.
     MIMETYPE_FILE = "mimetype"
-    META_INF_DIR = "META-INF"
 
     def initialize(document)
       @zipfile = open_document(document)
-      check_document!
+      check_mimetype!
 
       @mimetype = read_mimetype
       @on_disk = true
 
+      # Reserved entry names. Just the mimetype file by default.
+      register_reserved_name(MIMETYPE_FILE)
+
+      # Initialize the managed entries and register the META-INF directory.
+      initialize_managed_entries(MetaInf.new)
+
       # Here we fake up the connection to the rubyzip filesystem classes so
       # that they also respect the reserved names that we define.
       mapped_zip = ::Zip::ZipFileSystem::ZipFileNameMapper.new(self)
@@ -93,7 +100,18 @@ module UCF
         stream.write mimetype
       end
 
-      Container.open(filename, &block)
+      # Now open the newly created container.
+      c = new(filename)
+
+      if block_given?
+        begin
+          yield c
+        ensure
+          c.close
+        end
+      end
+
+      c
     end
 
     # :call-seq:
@@ -145,7 +163,7 @@ module UCF
     # all with the file (including if it cannot be found).
     def Container.verify(filename)
       begin
-        Container.verify!(filename)
+        new(filename).verify!
       rescue
         return false
       end
@@ -161,8 +179,7 @@ module UCF
     # there is something fundamental wrong with the file itself (e.g. it
     # cannot be found).
     def Container.verify!(filename)
-      new(filename).close
-      nil
+      new(filename).verify!
     end
 
     # :call-seq:
@@ -176,7 +193,9 @@ module UCF
     # 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)
+      if reserved_entry?(entry) || managed_directory?(entry)
+        raise ReservedNameClashError.new(entry.to_s)
+      end
 
       @zipfile.add(entry, src_path, &continue_on_exists_proc)
     end
@@ -233,7 +252,9 @@ module UCF
     # 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)
+      if reserved_entry?(entry) || managed_directory?(entry)
+        raise ReservedNameClashError.new(entry.to_s)
+      end
 
       @zipfile.get_output_stream(entry, permission, &block)
     end
@@ -256,7 +277,9 @@ module UCF
     # 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)
+      if reserved_entry?(name) || managed_file?(name)
+        raise ReservedNameClashError.new(name)
+      end
 
       @zipfile.mkdir(name, permission)
     end
@@ -309,50 +332,6 @@ module UCF
       @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
     #
@@ -361,13 +340,22 @@ module UCF
       @zipfile.to_s + " - #{@mimetype}"
     end
 
+    # :call-seq:
+    #   verify!
+    #
+    # Verify the contents of this UCF document. All managed files and
+    # directories are checked to make sure that they exist, if required.
+    def verify!
+      verify_managed_entries!
+    end
+
     private
 
     def open_document(document)
       ::Zip::ZipFile.new(document)
     end
 
-    def check_document!
+    def check_mimetype!
       # Check mimetype file is present and correct.
       entry = @zipfile.find_entry(MIMETYPE_FILE)
 
@@ -422,6 +410,15 @@ module UCF
     # by this method are Zip::ZipEntry objects. Please see the rubyzip
     # documentation for details.
 
+    ##
+    # :method:
+    # :call-seq:
+    #   entries -> Enumerable
+    #
+    # Returns an Enumerable containing all the entries in the UCF Document.
+    # The entry objects returned by this method are Zip::ZipEntry objects.
+    # Please see the rubyzip documentation for details.
+
     ##
     # :method: extract
     # :call-seq:

data/lib/ucf/entries/directory.rb

@@ -0,0 +1,71 @@
+# 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
+
+  # A ManagedDirectory acts as the interface to a set of (possibly) managed
+  # files within it and also reserves the directory name in the Container
+  # namespace.
+  #
+  # Once a ManagedDirectory is registered in a Container then only it can be
+  # used to write to its contents.
+  class ManagedDirectory < ManagedEntry
+    include ReservedNames
+    include ManagedEntries
+
+    # :call-seq:
+    #   new(name, required = false) -> ManagedDirectory
+    #
+    # Create a new ManagedDirectory with the supplied name and whether it is
+    # required to exist or not. Any ManagedFile or ManagedDirectory objects
+    # that are within this directory can also be given if required.
+    def initialize(name, required = false, entries = [])
+      super(name, required)
+
+      initialize_managed_entries(entries)
+    end
+
+    # :call-seq:
+    #   verify!
+    #
+    # Verify this ManagedDirectory for correctness. ManagedFiles registered
+    # within it are verified recursively.
+    #
+    # A MalformedUCFError is raised if it does not pass verification.
+    def verify!
+      super
+      @files.values.each { |f| f.verify! }
+    end
+
+  end
+end

data/lib/ucf/entries/entry.rb

@@ -0,0 +1,134 @@
+# 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
+
+  # ManagedEntry is the superclass of ManagedDirectory and ManagedFile. It
+  # should not be used directly but may be subclassed if necessary.
+  class ManagedEntry
+
+    # The name of the ManagedEntry. For the full path name of this entry use
+    # full_name.
+    attr_reader :name
+
+    # :call-seq:
+    #   new(name, required) -> ManagedEntry
+    #
+    # Create a new ManagedEntry with the supplied name. The entry should also
+    # be marked as required or not.
+    def initialize(name, required)
+      @parent = nil
+      @name = name
+      @required = required
+    end
+
+    # :call-seq:
+    #   full_name -> string
+    #
+    # The fully qualified name of this ManagedEntry.
+    def full_name
+      @parent.is_a?(Container) ? @name : "#{@parent.name}/#{@name}"
+    end
+
+    # :call-seq:
+    #   required? -> true or false
+    #
+    # Is this ManagedEntry required to be present according to the
+    # specification of its Container?
+    def required?
+      @required
+    end
+
+    # :call-seq:
+    #   exists? -> true or false
+    #
+    # Does this ManagedEntry exist in the Container?
+    def exists?
+      container.entries.each do |entry|
+        test = (entry.ftype == :directory) ? "#{full_name}/" : full_name
+        return true if entry.name == test
+      end
+
+      false
+    end
+
+    # :stopdoc:
+    # Allows the object in which this entry has been registered in to tell it
+    # who it is.
+    def parent=(parent)
+      @parent = parent
+    end
+    # :startdoc:
+
+    # :call-seq:
+    #   verify -> true or false
+    #
+    # Verify this ManagedEntry by checking that it exists if it is required
+    # according to its Container specification and validating its contents if
+    # necessary.
+    def verify
+      begin
+        verify!
+      rescue
+        return false
+      end
+
+      true
+    end
+
+    protected
+
+    # :call-seq:
+    #   verify!
+    #
+    # Verify this ManagedEntry raising a MalformedUCFError if it fails.
+    #
+    # Subclasses should override this method if they require more complex
+    # verification to be done.
+    def verify!
+      unless !@required || exists?
+        raise MalformedUCFError.new("Entry '#{full_name}' is required but "\
+          "missing.")
+      end
+    end
+
+    # :call-seq:
+    #   container -> Container
+    #
+    # Return the Container that this ManagedEntry resides in.
+    def container
+      @parent.is_a?(Container) ? @parent : @parent.container
+    end
+
+  end
+end