= 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-2015 The University of Manchester, UK

{<img src="https://badge.fury.io/rb/zip-container.svg" alt="Gem Version" />}[http://badge.fury.io/rb/zip-container]
{<img src="https://codeclimate.com/github/myGrid/ruby-zip-container.svg" />}[https://codeclimate.com/github/myGrid/ruby-zip-container]
{<img src="https://travis-ci.org/myGrid/ruby-zip-container.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/myGrid/ruby-zip-container]
{<img src="https://coveralls.io/repos/myGrid/ruby-zip-container/badge.svg?branch=master" alt="Coverage Status" />}[https://coveralls.io/r/myGrid/ruby-zip-container?branch=master]

== 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.

We follow the principles of {Semantic Versioning}[http://semver.org/] for our
releases.

== Backwards incompatibility warnings!

=== ZipContainer

The ZipContainer::Container class is now a common superclass of
ZipContainer::Dir and ZipContainer::File. You can use ZipContainer::File as a
direct replacement for ZipContainer::Container as the functionality is
preserved. The new names bring this API into closer alignment with the
underlying rubyzip API (Zip::File) and allows this library to work with
"exploded" or unpacked containers directly.

ZipContainer::Container should not be used directly from version 2.0.0
onwards.

=== ContainerError

This class has been renamed in version 3.0.0. It is now simply called Error so
that its fully qualified name is the more sensible ZipContainer::Error.

=== Rubyzip

Version 1.0.0 and up of this gem uses version 1.0.0 and up of the
{rubyzip}[https://rubygems.org/gems/rubyzip] library. This has a backwards
incompatible API that may clash with other gems that you are using. Please see
the {important note}[https://github.com/rubyzip/rubyzip/blob/master/README.md#important-note]
in the rubyzip readme for a workaround.

== Usage

This library has two entry points.

The main ZipContainer::File class largely mimics the rubyzip
{Zip::File}[http://www.rubydoc.info/gems/rubyzip/1.1.6/Zip/File] and
{Zip::FileSystem}[http://www.rubydoc.info/gems/rubyzip/1.1.6/Zip/FileSystem]
APIs so much of what you can do with them are supported for ZIP Containers.
There is also {API documentation}[http://mygrid.github.io/ruby-zip-container/]
with much more detail and any differences explained.

The ZipContainer::Dir class mimics, where possible, the core ruby
{Dir API}[http://ruby-doc.org/core-1.9.3/Dir.html].

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.