class ZipContainer::File
This class represents a ZipContainer
file in PK Zip format. See the OCF and UCF specifications for more details.
This class provides most of the facilities of the Zip::File
class in the rubyzip gem. Please also consult the rubyzip documentation alongside these pages.
There are code examples available with the source code of this library.
Public Class Methods
Create a new ZipContainer
file on disk with the specified mimetype.
# File lib/zip-container/file.rb, line 77 def self.create(filename, mimetype) ::Zip::OutputStream.open(filename) do |stream| stream.put_next_entry(MIMETYPE_FILE, nil, nil, ::Zip::Entry::STORED) stream.write mimetype end # Now open the newly created container. c = new(filename) if block_given? begin yield c ensure c.close end end c end
Iterate over the entries in the ZipContainer
file. The entry objects returned by this method are Zip::Entry objects. Please see the rubyzip documentation for details.
# File lib/zip-container/file.rb, line 104 def self.each_entry(filename, &block) c = new(filename) if block_given? begin c.each(&block) ensure c.close end end c.each end
Public Instance Methods
Convenience method for adding the contents of a file to the ZipContainer
file. If asked to add a file with a reserved name, such as the special mimetype header file, this method will raise a ReservedNameClashError
.
See the rubyzip documentation for details of the continue_on_exists_proc
parameter.
# File lib/zip-container/file.rb, line 128 def add(entry, src_path, &continue_on_exists_proc) if reserved_entry?(entry) || managed_directory?(entry) raise ReservedNameClashError, entry.to_s end @container.add(entry, src_path, &continue_on_exists_proc) end
Returns the ZipContainer
file comment, if it has one.
# File lib/zip-container/file.rb, line 375
Set the ZipContainer
file comment to the new value.
# File lib/zip-container/file.rb, line 382
Commits changes that have been made since the previous commit to the ZipContainer
file. Returns true
if anything was actually done, false
otherwise.
# File lib/zip-container/file.rb, line 143 def commit return false unless commit_required? @container.commit if on_disk? end
Returns true
if any changes have been made to this ZipContainer
file since the last commit, false
otherwise.
# File lib/zip-container/file.rb, line 389
Returns an object which can be used like ruby's built in Dir
(class) object, except that it works on the ZipContainer
file on which this method is invoked.
See the rubyzip documentation for details.
# File lib/zip-container/file.rb, line 159 def dir @fs_dir end
Iterate over the entries in the ZipContainer
file. The entry objects returned by this method are Zip::Entry objects. Please see the rubyzip documentation for details.
# File lib/zip-container/file.rb, line 397
Returns an Enumerable containing all the entries in the ZipContainer
file The entry objects returned by this method are Zip::Entry objects. Please see the rubyzip documentation for details.
# File lib/zip-container/file.rb, line 407
Extracts the specified entry of the ZipContainer
file to dest_path
.
See the rubyzip documentation for details of the on_exists_proc
parameter.
# File lib/zip-container/file.rb, line 416
Returns an object which can be used like ruby's built in File
(class) object, except that it works on the ZipContainer
file on which this method is invoked.
See the rubyzip documentation for details.
# File lib/zip-container/file.rb, line 171 def file @fs_file end
Searches for the entry with the specified name. Returns nil
if no entry is found or if the specified entry is hidden for normal use. You can specify :include_hidden => true
to include hidden entries in the search.
# File lib/zip-container/file.rb, line 182 def find_entry(entry_name, options = {}) options = { include_hidden: false }.merge(options) unless options[:include_hidden] return if hidden_entry?(entry_name) end @container.find_entry(entry_name) end
Searches for an entry like find_entry
, but throws Errno::ENOENT if no entry is found or if the specified entry is hidden for normal use. You can specify :include_hidden => true
to include hidden entries in the search.
# File lib/zip-container/file.rb, line 199 def get_entry(entry, options = {}) options = { include_hidden: false }.merge(options) unless options[:include_hidden] raise Errno::ENOENT, entry if hidden_entry?(entry) end @container.get_entry(entry) end
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/zip-container/file.rb, line 442
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/zip-container/file.rb, line 219 def get_output_stream(entry, permission = nil, &block) if reserved_entry?(entry) || managed_directory?(entry) raise ReservedNameClashError, entry.to_s end @container.get_output_stream(entry, permission, &block) end
Searches for entries given a glob. Hidden files are ignored by default.
The parameters that can be supplied are:
-
flags
- A bitwise OR of theFNM_xxx
parameters defined in File::Constants. The default value is::File::FNM_PATHNAME | ::File::FNM_DOTMATCH
-
options
-:include_hidden => true
will include hidden entries in the search.
# File lib/zip-container/file.rb, line 241 def glob(pattern, *params) flags = ::File::FNM_PATHNAME | ::File::FNM_DOTMATCH options = { include_hidden: false } params.each do |param| case param when Hash options = options.merge(param) else flags = param end end entries.map do |entry| next if !options[:include_hidden] && hidden_entry?(entry) next unless ::File.fnmatch(pattern, entry.name.chomp('/'), flags) yield(entry) if block_given? entry end.compact end
Is this ZipContainer
file memory resident as opposed to stored on disk?
# File lib/zip-container/file.rb, line 267 def in_memory? !@on_disk end
Creates a directory in the ZipContainer
file. If asked to create a directory with a name reserved for use by a file this method will raise a ReservedNameClashError
.
The new directory will be created with the supplied unix-style permissions. The default (0755
) is owner read, write and list; group read and list; and world read and list.
# File lib/zip-container/file.rb, line 281 def mkdir(name, permission = 0o0755) if reserved_entry?(name) || managed_file?(name) raise ReservedNameClashError, name end @container.mkdir(name, permission) end
Returns the filename of this ZipContainer
file.
# File lib/zip-container/file.rb, line 464
Is this ZipContainer
file stored on disk as opposed to memory resident?
# File lib/zip-container/file.rb, line 293 def on_disk? @on_disk end
Returns a string containing the contents of the specified entry.
# File lib/zip-container/file.rb, line 471
Removes the specified entry from the ZipContainer
file. If asked to remove any reserved files such as the special mimetype header file this method will do nothing.
# File lib/zip-container/file.rb, line 303 def remove(entry) return if reserved_entry?(entry) @container.remove(entry) end
Renames the specified entry in the ZipContainer
file. If asked to rename any reserved files such as the special mimetype header file this method will do nothing. If asked to rename a file to one of the reserved names a ReservedNameClashError
is raised.
See the rubyzip documentation for details of the continue_on_exists_proc
parameter.
# File lib/zip-container/file.rb, line 319 def rename(entry, new_name, &continue_on_exists_proc) return if reserved_entry?(entry) raise ReservedNameClashError, new_name if reserved_entry?(new_name) @container.rename(entry, new_name, &continue_on_exists_proc) end
Replaces the specified entry of the ZipContainer
file 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/zip-container/file.rb, line 333 def replace(entry, src_path) return if reserved_entry?(entry) @container.replace(entry, src_path) end
Returns the number of entries in the ZipContainer
file.
# File lib/zip-container/file.rb, line 478
Return a textual summary of this ZipContainer
file.
# File lib/zip-container/file.rb, line 343 def to_s @container.to_s + " - #{@mimetype}" end
Private Instance Methods
# File lib/zip-container/file.rb, line 349 def open_container(document) ::Zip::File.new(document) end
# File lib/zip-container/file.rb, line 366 def read_mimetype @container.read(MIMETYPE_FILE) end
# File lib/zip-container/file.rb, line 353 def verify_mimetype # Check mimetype file is present and correct. entry = @container.find_entry(MIMETYPE_FILE) return "'mimetype' file is missing." if entry.nil? if entry.local_header_offset != 0 return "'mimetype' file is not at offset 0 in the archive." end if entry.compression_method != ::Zip::Entry::STORED return "'mimetype' file is compressed." end end