zip-container 0.8.0

data/Changes.rdoc

@@ -0,0 +1,59 @@
+= Changes log for the ZIP Container Ruby Gem
+
+== Version 0.8.0
+
+* Abstract out all the underlying zip functionality and turn this library
+  into a basic ZIP Container provider.
+
+== 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.
+* Move exceptions to a new source file.
+* Use a base class for UCF exceptions.
+* Standardize the MalformedUCFError exception messages.
+* Add an exception for clashes with reserved names.
+* Implement Container#add to avoid using reserved names.
+* Raise an exception if renaming to a reserved name.
+* Implement Container#mkdir to avoid using reserved names.
+* Make sure testing reserved names copes with trailing slashes.
+* Fake up the connection to ZipFileSystem.
+* Implement Container#get_output_stream to respect reserved names.
+* Can now set comments on the UCF document.
+* Implement the close and commit methods.
+* Forward the commit_required? method.
+* Separate the opening and checking of a UCF document.
+* Documentation improvements and cleanup.
+
+== 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:
+
+ $ 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,85 @@
+# 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 'zip-container'
+
+task :default => [:test]
+
+Jeweler::Tasks.new do |s|
+  s.name             = "zip-container"
+  s.version          = ZipContainer::Version::STRING
+  s.authors          = ["Robert Haines"]
+  s.email            = ["support@mygrid.org.uk"]
+  s.homepage         = "http://mygrid.github.io/ruby-zip-container/"
+  s.platform         = Gem::Platform::RUBY
+  s.summary          = "A ZIP Container for use by OCF and UCF implementations"
+  s.description      = "A Ruby library for working with ZIP Container "\
+    "Format files. See "\
+    "http://www.idpf.org/epub/30/spec/epub30-ocf.html for the OCF "\
+    "specification and "\
+    "https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format "\
+    "for the UCF specification."
+  s.require_path     = "lib"
+  s.test_file        = "test/ts_container.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_container.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 ZIP Container Format Ruby Library version " +
+    "#{ZipContainer::Version::STRING}"
+  r.options << "-N"
+  r.options << "--tab-width=2"
+end

data/ReadMe.rdoc

@@ -0,0 +1,34 @@
+= ZIP Container Format Ruby Library
+
+Authors::     Robert Haines
+Contact::     mailto:support@mygrid.org.uk
+Homepage::    http://mygrid.github.io/ruby-zip-container
+Source code:: https://github.com/myGrid/ruby-zip-container
+Licence::     BSD (See Licence file or http://www.opensource.org/licenses/bsd-license.php)
+Copyright::   (c) 2013 The University of Manchester, UK
+
+{<img src="https://codeclimate.com/github/myGrid/ruby-zip-container.png" />}[https://codeclimate.com/github/myGrid/ruby-zip-container]
+
+== Synopsis
+
+This is a Ruby library for working with ZIP Container files. See the
+{ODF}[http://www.idpf.org/epub/30/spec/epub30-ocf.html] and
+{UDF}[https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format]
+specifications for more details.
+
+<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.
+
+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 ZIP Container are all implemented but memory
+resident ZIP Container files are not yet supported. Presently all operations
+are performed on files 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].

data/examples/create-zip-container.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 'rubygems'
+require 'zip-container'
+
+ZIP_FILE = "example.zip"
+file = ARGV.length > 0 ? ARGV[0] : ZIP_FILE
+
+File.delete(file) if File.exists?(file)
+
+begin
+  ZipContainer::Container.create(file, "application/epub+zip") 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__)
+
+    # Add a explanation of this file.
+    c.comment = "This is an example Container file!"
+  end
+rescue ZipContainer::MalformedZipContainerError, Zip::ZipError => err
+  puts err.to_s
+  exit 1
+end

data/examples/verify-zip-container.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 'zip-container'
+
+ZIP_FILE = "example.zip"
+file = ARGV.length > 0 ? ARGV[0] : ZIP_FILE
+
+begin
+  ZipContainer::Container.verify!(file)
+rescue ZipContainer::MalformedZipContainerError, Zip::ZipError => err
+  puts err.to_s
+  exit 1
+end

data/examples/zip-container-info

@@ -0,0 +1,70 @@
+#!/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 'zip-container'
+
+def usage
+  puts "zip-container-info zip-container-file"
+  exit 1
+end
+
+usage unless ARGV.length == 1
+
+container_file = ARGV[0]
+
+begin
+  container = ZipContainer::Container.open(container_file)
+rescue ZipContainer::MalformedZipContainerError, Zip::ZipError => err
+  puts err.to_s
+  exit 1
+end
+
+puts "Archive: #{container.to_s}"
+puts "Container file size: #{File.size(container_file)} bytes, "\
+  "number of entries: #{container.size}"
+
+total_size = 0
+total_comp = 0
+
+container.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%%" %
+  [container.size, total_size, total_comp, ratio]

data/lib/zip-container.rb

@@ -0,0 +1,60 @@
+# 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 'zip-container/exceptions'
+require 'zip-container/entries/reserved'
+require 'zip-container/entries/managed'
+require 'zip-container/entries/entry'
+require 'zip-container/entries/file'
+require 'zip-container/entries/directory'
+require 'zip-container/container'
+
+# This is a ruby library to read and write ZIP Container Format files. See the
+# ZipContainer::Container class for more information.
+#
+# See the {OCF}[http://www.idpf.org/epub/30/spec/epub30-ocf.html] and
+# {UCF}[https://learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format]
+# specifications for more details.
+module ZipContainer
+
+  # 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
+
+end