zip-container 0.8.0

data/lib/zip-container/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 ZipContainer
+
+  # 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 MalformedZipContainerError is raised if it does not pass verification.
+    def verify!
+      super
+      @files.values.each { |f| f.verify! }
+    end
+
+  end
+end

data/lib/zip-container/entries/entry.rb

@@ -0,0 +1,135 @@
+# 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 ZipContainer
+
+  # 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 MalformedZipContainerError if it
+    # fails.
+    #
+    # Subclasses should override this method if they require more complex
+    # verification to be done.
+    def verify!
+      unless !@required || exists?
+        raise MalformedZipContainerError.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

data/lib/zip-container/entries/file.rb

@@ -0,0 +1,101 @@
+# 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 ZipContainer
+
+  # A ManagedFile is used to reserve a filename in a Container namespace.
+  class ManagedFile < ManagedEntry
+
+    # :call-seq:
+    #   new(name, required = false, validation_proc = nil) -> ManagedFile
+    #
+    # Create a new ManagedFile with the supplied name and whether it is
+    # required to exist or not.
+    #
+    # If supplied <tt>validation_proc</tt> should be a Proc that takes a
+    # single parameter and returns +true+ or +false+ depending on whether the
+    # contents of the file were validated or not.
+    #
+    # For more complex content validation subclasses may override the validate
+    # method.
+    #
+    # The following example creates a ManagedFile that is not required to be
+    # present in the container, but if it is, its contents must be the single
+    # word "Boo!".
+    #
+    #  valid = Proc.new { |contents| contents == "Boo!" }
+    #  ManagedFile.new("Surprize.txt", false, valid)
+    def initialize(name, required = false, validation_proc = nil)
+      super(name, required)
+
+      @validation_proc = validation_proc.is_a?(Proc) ? validation_proc : nil
+    end
+
+    # :call-seq:
+    #   verify!
+    #
+    # Verify this ManagedFile for correctness. The contents are validated if
+    # required.
+    #
+    # A MalformedZipContainerError is raised if it does not pass verification.
+    def verify!
+      super
+      unless (exists? ? validate : true)
+        raise MalformedZipContainerError.new("The contents of file "\
+          "'#{full_name}' do not pass validation.")
+      end
+    end
+
+    protected
+
+    # :call-seq:
+    #   validate -> boolean
+    #
+    # Validate the contents of this ManagedFile. By default this methods uses
+    # the validation Proc supplied on object initialization if there is one.
+    # If not it simply returns true (no validation was required).
+    #
+    # For complex validations of content subclasses can override this method.
+    def validate
+      @validation_proc.nil? ? true : @validation_proc.call(contents)
+    end
+
+    private
+
+    # Grab the contents of this ManagedFile
+    def contents
+      container.read(full_name)
+    end
+
+  end
+end

data/lib/zip-container/entries/managed.rb

@@ -0,0 +1,183 @@
+# 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 'zip/zip_entry'
+
+module ZipContainer
+
+  # This module provides support for managed file and directory entries.
+  #
+  # <b>Note!</b> If you mix this module in you *must* call
+  # +initialize_managed_entries+ in your constructor to ensure that the
+  # internal lists of managed entries are correctly assigned.
+  module ManagedEntries
+
+    # :call-seq:
+    #   managed_directories -> Array
+    #
+    # Return the list of managed directories.
+    def managed_directories
+      @directories.values
+    end
+
+    # :call-seq:
+    #   managed_directory_names -> Array
+    #
+    # Return the list of managed directory names.
+    def managed_directory_names
+      expand_names(@directories.keys)
+    end
+
+    # :call-seq:
+    #   managed_directory?(entry) -> boolean
+    #
+    # Is the supplied entry/name a managed directory?
+    def managed_directory?(entry)
+      managed_entry?(entry, managed_directory_names)
+    end
+
+    # :call-seq:
+    #   managed_entries -> Array
+    #
+    # Return the list of managed files and directories.
+    def managed_entries
+      managed_files + managed_directories
+    end
+
+    # :call-seq:
+    #   managed_entry_names -> Array
+    #
+    # Return the list of managed file and directory names.
+    def managed_entry_names
+      managed_file_names + managed_directory_names
+    end
+
+    # :call-seq:
+    #   managed_entry?(entry) -> boolean
+    #
+    # Is the supplied entry/name a managed entry?
+    def managed_entry?(entry, list = managed_entry_names)
+      name = entry.kind_of?(::Zip::ZipEntry) ? entry.name : entry
+      name.chop! if name.end_with? "/"
+      list.map { |n| n.downcase }.include? name.downcase
+    end
+
+    # :call-seq:
+    #   managed_file?(entry) -> boolean
+    #
+    # Is the supplied entry/name a managed file?
+    def managed_file?(entry)
+      managed_entry?(entry, managed_file_names)
+    end
+
+    # :call-seq:
+    #   managed_files -> Array
+    #
+    # Return the list of managed files.
+    def managed_files
+      @files.values + managed_directories.map { |d| d.managed_files }.flatten
+    end
+
+    # :call-seq:
+    #   managed_file_names -> Array
+    #
+    # Return the list of managed file names.
+    def managed_file_names
+      expand_names(@files.keys) +
+        managed_directories.map { |d| d.managed_file_names }.flatten
+    end
+
+    # :call-seq:
+    #   verify_managed_entries!
+    #
+    # All managed files and directories are checked to make sure that they
+    # exist, if required.
+    def verify_managed_entries!
+      @directories.each_value do |dir|
+        dir.verify!
+      end
+
+      @files.each_value do |file|
+        file.verify!
+      end
+
+      true
+    end
+
+    protected
+
+    # :call-seq:
+    #   initialize_managed_entries
+    #   initialize_managed_entries(entry)
+    #   initialize_managed_entries(entries)
+    #
+    # Initialize the managed entries and register any that are supplied. A
+    # single ManagedFile or ManagedDirectory or a list of them can be
+    # provided.
+    def initialize_managed_entries(entries = [])
+      list = [*entries]
+      @directories ||= {}
+      @files ||= {}
+
+      list.each { |item| register_managed_entry(item) }
+    end
+
+    # :call-seq:
+    #   register_managed_entry(entry)
+    #
+    # Register a ManagedFile or ManagedDirectory.
+    #
+    # A ManagedFile is used to reserve the name of a file in the container
+    # namespace and can describe how to verify the contents of it if required.
+    #
+    # A ManagedDirectory is used to both reserve the name of a directory in
+    # the container namespace and act as an interface to the (possibly)
+    # managed files within it.
+    def register_managed_entry(entry)
+      unless entry.is_a?(ManagedDirectory) || entry.is_a?(ManagedFile)
+        raise ArgumentError.new("The supplied entry must be of type "\
+          "ManagedDirectory or ManagedFile or a subclass of either.")
+      end
+
+      entry.parent = self
+      @directories[entry.name] = entry if entry.is_a? ManagedDirectory
+      @files[entry.name] = entry if entry.is_a? ManagedFile
+    end
+
+    private
+
+    def expand_names(names)
+      names.map { |n| self.is_a?(Container) ? n : "#{name}/#{n}" }
+    end
+
+  end
+end