class UCF::Container

This class represents a UCF file in PK Zip format. See learn.adobe.com/wiki/display/PDFNAV/Universal+Container+Format for more details.

This class mostly provides all the facilities of the Zip::ZipFile class in the rubyzip gem. Please also consult the rubyzip documentation: rubydoc.info/gems/rubyzip/0.9.9/frames

There are code examples available with the source code of this library.

Attributes

mimetype[R]

The mime-type of this UCF file. By default this is “application/epub+zip”.

Public Class Methods

create(filename, mimetype = "application/epub+zip") → container click to toggle source

create(filename, mimetype = "application/epub+zip") {|container| ...}

Create a new UCF file on disk with the specified mimetype.

# File lib/ucf/container.rb, line 85
def Container.create(filename, mimetype = DEFAULT_MIMETYPE, &block)
  ::Zip::ZipOutputStream.open(filename) do |stream|
    stream.put_next_entry(MIMETYPE_FILE, nil, nil, ::Zip::ZipEntry::STORED)
    stream.write mimetype
  end

  Container.open(filename, &block)
end

each_entry → Enumerator click to toggle source

each_entry {|entry| ...}

Iterate over the entries in the UCF document. The entry objects returned by this method are Zip::ZipEntry objects. Please see the rubyzip documentation for details.

# File lib/ucf/container.rb, line 101
def Container.each_entry(filename, &block)
  c = new(filename)

  if block_given?
    begin
      c.each(&block)
    ensure
      c.close
    end
  end

  c.each
end

open(filename) → container click to toggle source

open(filename) {|container| ...}

Open an existing UCF file from disk. It will be checked for conformance to the UCF specification upon first access.

# File lib/ucf/container.rb, line 121
def Container.open(filename, &block)
  c = new(filename)

  if block_given?
    begin
      yield c
    ensure
      c.close
    end
  end

  c
end

verify(filename) → boolean click to toggle source

Verify that the specified UCF file conforms to the UCF specification. This method returns false if there are any problems at all with the file (including if it can’t be found) or true if it conforms.

# File lib/ucf/container.rb, line 141
def Container.verify(filename)
  begin
    Container.verify!(filename)
  rescue
    return false
  end

  true
end

verify!(filename) click to toggle source

Verify that the specified UCF file conforms to the UCF specification. This method raises exceptions when errors are found or if there is something fundamental wrong with the file itself (e.g. not found).

# File lib/ucf/container.rb, line 157
def Container.verify!(filename)
  new(filename).close
  nil
end

Public Instance Methods

add(entry, src_path, &continue_on_exists_proc) click to toggle source

Convenience method for adding the contents of a file to the UCF file.

See the rubyzip documentation for details of the continue_on_exists_proc parameter.

# File lib/ucf/container.rb, line 244

close click to toggle source

Closes the UCF file committing any changes that have been made.

# File lib/ucf/container.rb, line 251

comment → String click to toggle source

Returns the UCF file comment, if it has one.

# File lib/ucf/container.rb, line 258

commit click to toggle source

Commits changes that have been made since the previous commit to the UCF file.

# File lib/ucf/container.rb, line 266

dir → Zip::ZipFsDir click to toggle source

Returns an object which can be used like ruby’s built in Dir (class) object, except that it works on the UCF file on which this method is invoked.

See the rubyzip documentation for details.

# File lib/ucf/container.rb, line 277

each → Enumerator click to toggle source

each {|entry| ...}

Iterate over the entries in the UCF document. The entry objects returned by this method are Zip::ZipEntry objects. Please see the rubyzip documentation for details.

# File lib/ucf/container.rb, line 287

extract(entry, dest_path, &on_exists_proc) click to toggle source

Extracts the specified entry to dest_path.

See the rubyzip documentation for details of the on_exists_proc parameter.

# File lib/ucf/container.rb, line 297

dir → Zip::ZipFsFile click to toggle source

Returns an object which can be used like ruby’s built in File (class) object, except that it works on the UCF file on which this method is invoked.

See the rubyzip documentation for details.

# File lib/ucf/container.rb, line 308

find_entry(entry) → Zip::ZipEntry click to toggle source

Searches for entries with the specified name. Returns nil if no entry is found. See also get_entry.

# File lib/ucf/container.rb, line 316

get_entry(entry) → Zip::ZipEntry click to toggle source

Searches for an entry like find_entry, but throws +Errno::ENOENT+ if no entry is found.

# File lib/ucf/container.rb, line 324

get_input_stream(entry) → stream click to toggle source

get_input_stream(entry) {|stream| ...}

Returns an input stream to the specified entry. If a block is passed the stream object is passed to the block and the stream is automatically closed afterwards just as with ruby’s built in File.open method.

# File lib/ucf/container.rb, line 334

get_output_stream(entry, permission_int = nil) → stream click to toggle source

get_output_stream(entry, permission_int = nil) {|stream| ...}

Returns an output stream to the specified entry. If a block is passed the stream object is passed to the block and the stream is automatically closed afterwards just as with ruby’s built-in File.open method.

See the rubyzip documentation for details of the permission_int parameter.

# File lib/ucf/container.rb, line 347

glob(*args) → Array of Zip::ZipEntry click to toggle source

glob(*args) {|entry| ...}

Searches for entries given a glob.

See the rubyzip documentation for details of the parameters that can be passed in.

# File lib/ucf/container.rb, line 358

mkdir(entryName, permission_int = 0755) click to toggle source

Creates a directory.

See the rubyzip documentation for details of the permission_int parameter.

# File lib/ucf/container.rb, line 368

name → String click to toggle source

Returns the filename of this UCF file.

# File lib/ucf/container.rb, line 375

read(entry) → String click to toggle source

Returns a string containing the contents of the specified entry.

# File lib/ucf/container.rb, line 382

remove(entry) click to toggle source

Removes the specified entry. If asked to remove any reserved files such as the special mimetype header file this method will do nothing.

# File lib/ucf/container.rb, line 167
def remove(entry)
  return if reserved_entry?(entry)
  @zipfile.remove(entry)
end

rename(entry, new_name, &continueOnExistsProc) click to toggle source

Renames the specified entry. If asked to rename any reserved files such as the special mimetype header file this method will do nothing. See the rubyzip documentation for details of the continue_on_exists_proc parameter.

# File lib/ucf/container.rb, line 179
def rename(entry, new_name, &continue_on_exists_proc)
  return if reserved_entry?(entry)
  @zipfile.rename(entry, new_name, continue_on_exists_proc)
end

replace(entry, src_path) click to toggle source

Replaces the specified entry with the contents of src_path (from the file system). If asked to replace any reserved files such as the special mimetype header file this method will do nothing.

# File lib/ucf/container.rb, line 190
def replace(entry, src_path)
  return if reserved_entry?(entry)
  @zipfile.replace(entry, src_path)
end

size → int click to toggle source

Returns the number of entries in the UCF document.

# File lib/ucf/container.rb, line 389

to_s → String click to toggle source

Return a String representation of this UCF file.

# File lib/ucf/container.rb, line 199
def to_s
  @zipfile.to_s + " - #{@mimetype}"
end