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 80
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

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 95
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 115
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 131
def Container.verify!(filename)
  new(filename)
  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 215

close click to toggle source

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

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

comment → String click to toggle source

Returns the UCF file comment, if it has one.

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

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 237

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 248

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 258

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 269

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 277

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 285

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 295

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 308

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 319

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 329

name → String click to toggle source

Returns the filename of this UCF file.

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

read(entry) → String click to toggle source

Returns a string containing the contents of the specified entry.

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

remove(entry) click to toggle source

Removes the specified entry. If asked to remove the special mimetype header file this method will do nothing.

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

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

Renames the specified entry. If asked to rename 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 152
def rename(entry, new_name, &continue_on_exists_proc)
  return if mimetype_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 the special mimetype header file this method will do nothing.

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

to_s → String click to toggle source

Return a String representation of this UCF file.

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