ucf

Universal Container Format (UCF) Ruby Library

Robert Haines

A Ruby library for creating, editing and validating UCF files.

Synopsis

This is a Ruby library for working with UCF documents. See the specification for more details. UCF is a type of EPUB and very similar to the EPUB Open Container Format (OCF).

Most of this library's API is provided by the underlying zip-container gem so you will need to consult that documentation as well in addition to this.

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.

Usage

This library has two entry points.

The main UCF::File class is a specialization of ZipContainer::File which largely mimics the rubyzip Zip::File and Zip::FileSystem APIs.

The UCF::Dir class is a based upon the ZipContainer::Dir class which mimics, where possible, the core ruby Dir API.

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.

Files in the META-INF directory

The UCF specification requires that files in the META-INF directory are validated against a schema if they are present. If the nokogiri gem is available then this library will use it to validate the contents of the container.xml and manifest.xml files. This functionality is not enforced on the user in case they are not using the META-INF directory and so would not need the extra dependency on nokogiri.

Ruby version requirements and nokogiri

When used on its own the UCF library requires Ruby version >=3.0, however, if you are using nokogiri for schema validation then you need to use Ruby version >=3.1 to satisfy its version constraints.

What this library can not do yet

The basic requirements of a UCF document are all implemented but there are a number of optional features that are not yet provided.

• Validation of all file contents in the META-INF directory. The container.xml and manifest.xml files are validated but others are not 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).
• Encryption (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).

Library versions

From version 1.0.0 onwards, the principles of semantic versioning are applied when numbering releases with new features or breaking changes.

Developing Ruby UCF

Please see our Code of Conduct and our contributor guidelines.

Licence

BSD (See LICENCE file or http://www.opensource.org/licenses/bsd-license.php).