ucf 0.1.0 → 0.5.0

data/lib/ucf/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 UCF
+
+  # 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 MalformedUCFError is raised if it does not pass verification.
+    def verify!
+      super
+      unless (exists? ? validate : true)
+        raise MalformedUCFError.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/ucf/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 UCF
+
+  # 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

data/lib/ucf/entries/reserved.rb

@@ -0,0 +1,88 @@
+# 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 UCF
+
+  # This module provides support for reserved names.
+  module ReservedNames
+
+    # :call-seq:
+    #   reserved_names -> Array
+    #
+    # Return a list of reserved file and directory names for this UCF
+    # document.
+    #
+    # Reserved files and directories must be accessed directly by methods
+    # within Container (or subclasses of Container). This is because they are
+    # fundamental to the format and might need to exhibit certain properties
+    # (such as no compression) that must be preserved. The "mimetype" file is
+    # an example of such a reserved entry.
+    #
+    # To add a reserved name to a subclass of Container simply add it to the
+    # list in the constructor (you must call the super constructor first!):
+    #
+    #  class MyContainer < UCF::Container
+    #    def initialize(filename)
+    #      super(filename)
+    #
+    #      register_reserved_name("my_reserved_name")
+    #    end
+    #  end
+    def reserved_names
+      @reserved_names ||= []
+    end
+
+    # :call-seq:
+    #   reserved_entry?(entry) -> boolean
+    #
+    # Is the given entry in the reserved list of names? A String or a
+    # Zip::ZipEntry object can be passed in here.
+    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
+
+    protected
+
+    # :call-seq:
+    #   register_reserved_name(name)
+    #
+    # Add a reserved name to the list.
+    def register_reserved_name(name)
+      @reserved_names ||= []
+      @reserved_names << name unless @reserved_names.include? name
+    end
+  end
+end

data/lib/ucf/exceptions.rb

@@ -30,6 +30,7 @@
 #
 # Author: Robert Haines
 
+#
 module UCF
 
   # The base class of all other exceptions raised by this library.
@@ -53,7 +54,8 @@ module UCF
     end
   end
 
-  # This exception is raised when a clash occurs with a reserved name.
+  # This exception is raised when a clash occurs with a reserved or managed
+  # name.
   class ReservedNameClashError < UCFError
 
     # :call-seq:

data/lib/ucf/meta-inf.rb

@@ -0,0 +1,52 @@
+# 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
+
+  # This is a subclass of ManagedDirectory to represent the META-INF directory
+  # in a basic UCF Document.
+  class MetaInf < ManagedDirectory
+
+    # :call-seq:
+    #   new -> MetaInf
+    #
+    # Create a standard META-INF ManagedDirectory.
+    def initialize
+      super("META-INF", false,
+        [ManagedFile.new("container.xml"), ManagedFile.new("manifest.xml"),
+          ManagedFile.new("metadata.xml"), ManagedFile.new("signatures.xml"),
+          ManagedFile.new("encryption.xml"), ManagedFile.new("rights.xml")])
+    end
+
+  end
+end

data/test/tc_managed_entries.rb

@@ -0,0 +1,206 @@
+# 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'
+
+# Classes to test managed entries.
+class ManagedUCF < UCF::Container
+
+  private_class_method :new
+
+  def initialize(filename)
+    super(filename)
+    register_managed_entry(UCF::ManagedDirectory.new("src", true))
+    register_managed_entry(UCF::ManagedDirectory.new("test"))
+    register_managed_entry(UCF::ManagedDirectory.new("lib"))
+    register_managed_entry(UCF::ManagedFile.new("index.html", true))
+  end
+
+end
+
+class ExampleUCF < UCF::Container
+
+  private_class_method :new
+
+  def initialize(filename)
+    super(filename)
+    register_managed_entry(UCF::ManagedDirectory.new("dir", true))
+    register_managed_entry(UCF::ManagedFile.new("greeting.txt", true))
+  end
+
+end
+
+class ExampleUCF2 < UCF::Container
+
+  private_class_method :new
+
+  def initialize(filename)
+    super(filename)
+
+    valid = Proc.new { |contents| contents.match(/[Hh]ello/) }
+    register_managed_entry(UCF::ManagedFile.new("greeting.txt", true, valid))
+  end
+
+end
+
+class TestManagedEntries < Test::Unit::TestCase
+
+  # Check that the example UCF document does not validate as a ManagedUCF.
+  def test_fail_verification
+    refute(ManagedUCF.verify($ucf_example))
+
+    assert_raises(UCF::MalformedUCFError) do
+      ManagedUCF.verify!($ucf_example)
+    end
+  end
+
+  # Check that the example UCF document does validate as an ExampleUCF.
+  def test_pass_verification
+    assert(ExampleUCF.verify($ucf_example))
+
+    assert_nothing_raised(UCF::MalformedUCFError) do
+      ExampleUCF.verify!($ucf_example)
+    end
+  end
+
+  # Check that the example UCF document does validate as an ExampleUCF2.
+  def test_pass_verification_2
+    assert(ExampleUCF2.verify($ucf_example))
+
+    assert_nothing_raised(UCF::MalformedUCFError) do
+      ExampleUCF2.verify!($ucf_example)
+    end
+  end
+
+  # Check that a standard Container can be created
+  def test_create_standard_container
+    Dir.mktmpdir do |dir|
+      filename = File.join(dir, "test.ucf")
+
+      assert_nothing_raised do
+        UCF::Container.create(filename) do |c|
+          c.mkdir("META-INF")
+          assert(c.file.exists?("META-INF"))
+
+          c.file.open("META-INF/container.xml", "w") do |f|
+            f.puts "<?xml version=\"1.0\"?>"
+          end
+          assert(c.file.exists?("META-INF/container.xml"))
+        end
+      end
+
+      assert_nothing_raised(UCF::MalformedUCFError) do
+        UCF::Container.verify!(filename)
+      end
+    end
+  end
+
+  # Check that a ManagedUCF does not verify immediately after creation.
+  def test_create_bad_subclassed_container
+    Dir.mktmpdir do |dir|
+      filename = File.join(dir, "test.ucf")
+
+      assert_nothing_raised do
+        ManagedUCF.create(filename) do |c|
+          assert_raises(UCF::MalformedUCFError) do
+            c.verify!
+          end
+        end
+      end
+
+      refute(ManagedUCF.verify(filename))
+      assert_raises(UCF::MalformedUCFError) do
+        ManagedUCF.verify!(filename)
+      end
+    end
+  end
+
+  # Check that a ManagedUCF does verify when required objects are added.
+  def test_create_subclassed_container
+    Dir.mktmpdir do |dir|
+      filename = File.join(dir, "test.ucf")
+
+      assert_nothing_raised do
+        ManagedUCF.create(filename) do |c|
+          c.dir.mkdir("src")
+          c.file.open("index.html", "w") do |f|
+            f.puts "<html />"
+          end
+        end
+      end
+
+      assert(ManagedUCF.verify(filename))
+      assert_nothing_raised(UCF::MalformedUCFError) do
+        ManagedUCF.verify!(filename)
+      end
+    end
+  end
+
+  # Check that a ExampleUCF2 will only verify when required objects are added
+  # with the correct contents.
+  def test_create_subclassed_container_with_content_verification
+    Dir.mktmpdir do |dir|
+      filename = File.join(dir, "test.ucf")
+
+      assert_nothing_raised do
+        ExampleUCF2.create(filename) do |c|
+          assert_raises(UCF::MalformedUCFError) do
+            c.verify!
+          end
+
+          c.file.open("greeting.txt", "w") do |f|
+            f.puts "Goodbye!"
+          end
+
+          assert_raises(UCF::MalformedUCFError) do
+            c.verify!
+          end
+
+          c.file.open("greeting.txt", "w") do |f|
+            f.puts "Hello, Y'All!"
+          end
+
+          assert_nothing_raised(UCF::MalformedUCFError) do
+            c.verify!
+          end
+        end
+      end
+
+      assert(ExampleUCF2.verify(filename))
+      assert_nothing_raised(UCF::MalformedUCFError) do
+        ExampleUCF2.verify!(filename)
+      end
+    end
+  end
+
+end