Module | Archive::Zip::Entry |
In: |
lib/archive/zip/entry.rb
|
The Archive::Zip::Entry mixin provides classes with methods implementing many of the common features of all entry types. Some of these methods, such as dump_local_file_record and dump_central_file_record, are required by Archive::Zip in order to store the entry into an archive. Those should be left alone. Others, such as ftype and mode=, are expected to be overridden to provide sensible information for the new entry type.
A class using this mixin must provide 2 methods: extract and dump_file_data. extract should be a public method with the following signature:
def extract(options = {}) ... end
This method should extract the contents of the entry to the filesystem. options should be an optional Hash containing a mapping of option names to option values. Please refer to Archive::Zip::Entry::File#extract, Archive::Zip::Entry::Symlink#extract, and Archive::Zip::Entry::Directory#extract for examples of the options currently supported.
dump_file_data should be a private method with the following signature:
def dump_file_data(io) ... end
This method should use the write method of io to write all file data. io will be a writable, IO-like object.
The class methods from_file and parse are factories for creating the 3 kinds of concrete entries currently implemented: File, Directory, and Symlink. While it is possible to create new archives using custom entry implementations, it is not possible to load those same entries from the archive since the parse factory method does not know about them. Patches to support new entry types are welcome.
CFHRecord | = | Struct.new( :made_by_version, :extraction_version, :general_purpose_flags, :compression_method, :mtime, :crc32, :compressed_size, :uncompressed_size, :disk_number_start, :internal_file_attributes, :external_file_attributes, :local_header_position, :zip_path, :extra_fields, :comment | ||
LFHRecord | = | Struct.new( :extraction_version, :general_purpose_flags, :compression_method, :mtime, :crc32, :compressed_size, :uncompressed_size, :zip_path, :extra_fields, :compressed_data | ||
FLAG_ENCRYPTED | = | 0b0001 | When this flag is set in the general purpose flags, it indicates that the entry‘s file data is encrypted using the original (weak) algorithm. | |
FLAG_DATA_DESCRIPTOR_FOLLOWS | = | 0b1000 | When this flag is set in the general purpose flags, it indicates that the read data descriptor record for a local file record is located after the entry‘s file data. |
atime | [RW] | The last accessed time. |
comment | [RW] | The comment associated with this entry. |
compression_codec | [RW] | The selected compression codec. |
encryption_codec | [RW] | The selected encryption codec. |
expected_data_descriptor | [RW] | An Archive::Zip::DataDescriptor instance which should contain the expected CRC32 checksum, compressed size, and uncompressed size for the file data. When not nil, this is used by extract to confirm that the data extraction was successful. |
gid | [RW] | The group ID of the owner of this entry. |
mode | [RW] | The file mode/permission bits for this entry. |
mtime | [RW] | The last modified time. |
password | [RW] | The password used with the encryption codec to encrypt or decrypt the file data for an entry. |
raw_data | [RW] | The raw, possibly compressed and/or encrypted file data for an entry. |
uid | [RW] | The user ID of the owner of this entry. |
zip_path | [R] | The path for this entry in the ZIP archive. |
Cleans up and returns zip_path by eliminating . and .. references, leading and trailing /‘s, and runs of /‘s.
Creates a new Entry based upon a file, symlink, or directory. file_path points to the source item. options is a Hash optionally containing the following:
:zip_path: | The path for the entry in the archive where `/’ is the file separator character. This defaults to the basename of file_path if unspecified. |
:follow_symlinks: | When set to true (the default), symlinks are treated as the files or directories to which they point. |
:compression_codec: | Specifies a proc, lambda, or class. If a proc or lambda is used, it must take a single argument containing a zip entry and return a compression codec class to be instantiated and used with the entry. Otherwise, a compression codec class must be specified directly. When unset, the default compression codec for each entry type is used. |
:encryption_codec: | Specifies a proc, lambda, or class. If a proc or lambda is used, it must take a single argument containing a zip entry and return an encryption codec class to be instantiated and used with the entry. Otherwise, an encryption codec class must be specified directly. When unset, the default encryption codec for each entry type is used. |
Raises Archive::Zip::EntryError if processing the given file path results in a file not found error.
Creates a new, uninitialized Entry instance using the Store compression method. The zip path is initialized to zip_path. raw_data, if specified, must be a readable, IO-like object containing possibly compressed/encrypted file data for the entry. It is intended to be used primarily by the parse class method.
Creates and returns a new entry object by parsing from the current position of io. io must be a readable, IO-like object which is positioned at the start of a central file record following the signature for that record.
NOTE: For now io MUST be seekable.
Currently, the only entry objects returned are instances of Archive::Zip::Entry::File, Archive::Zip::Entry::Directory, and Archive::Zip::Entry::Symlink. Any other kind of entry will be mapped into an instance of Archive::Zip::Entry::File.
Raises Archive::Zip::EntryError for any other errors related to processing the entry.
Adds extra_field as an extra field specification to both the central file record and the local file record of this entry.
If extra_field is an instance of Archive::Zip::Entry::ExtraField::ExtendedTimestamp, the values of that field are used to set mtime and atime for this entry. If extra_field is an instance of Archive::Zip::Entry::ExtraField::Unix, the values of that field are used to set mtime, atime, uid, and gid for this entry.
Writes the central file record for this entry to io, a writable, IO-like object which provides a write method. Returns the number of bytes written.
NOTE: This method should only be called by Archive::Zip.
Writes the local file record for this entry to io, a writable, IO-like object which provides a write method. local_file_record_position is the offset within io at which writing will begin. This is used so that when writing to a non-seekable IO object it is possible to avoid calling the pos method of io. Returns the number of bytes written.
NOTE: This method should only be called by Archive::Zip.
Returns the file type of this entry as the symbol :unknown.
Override this in concrete subclasses to return an appropriate symbol.
Sets the path in the archive for this entry to zip_path after passing it through Archive::Zip::Entry.expand_path and ensuring that the result is not empty.