Class: Zip::File
- Inherits:
-
Object
- Object
- Zip::File
- Extended by:
- Forwardable, FileSplit
- Includes:
- FileSystem
- Defined in:
- lib/zip/file.rb,
lib/zip/filesystem.rb
Overview
Zip::File is modeled after java.util.zip.ZipFile from the Java SDK. The most important methods are those for accessing information about the entries in the archive and methods such as ‘get_input_stream` and `get_output_stream` for reading from and writing entries to the archive. The class includes a few convenience methods such as `extract` for extracting entries to the filesystem, and `remove`, `replace`, `rename` and `mkdir` for making simple modifications to the archive.
Modifications to a zip archive are not committed until ‘commit` or `close` is called. The method `open` accepts a block following the pattern from ::File.open offering a simple way to automatically close the archive when the block returns.
The following example opens zip archive ‘my.zip` (creating it if it doesn’t exist) and adds an entry ‘first.txt` and a directory entry `a_dir` to it.
“‘ require ’zip’
Zip::File.open(‘my.zip’, create: true) do |zipfile|
zipfile.get_output_stream('first.txt') { |f| f.puts 'Hello from Zip::File' }
zipfile.mkdir('a_dir')
end “‘
The next example reopens ‘my.zip`, writes the contents of `first.txt` to standard out and deletes the entry from the archive.
“‘ require ’zip’
Zip::File.open(‘my.zip’, create: true) do |zipfile|
puts zipfile.read('first.txt')
zipfile.remove('first.txt')
end
Zip::FileSystem offers an alternative API that emulates ruby’s interface for accessing the filesystem, ie. the ::File and ::Dir classes.
Constant Summary collapse
- IO_METHODS =
[:tell, :seek, :read, :eof, :close].freeze
Constants included from FileSplit
Zip::FileSplit::DATA_BUFFER_SIZE, Zip::FileSplit::MAX_SEGMENT_SIZE, Zip::FileSplit::MIN_SEGMENT_SIZE
Instance Attribute Summary collapse
-
#name ⇒ Object
readonly
Returns the value of attribute name.
-
#restore_ownership ⇒ Object
default -> false.
-
#restore_permissions ⇒ Object
default -> true.
-
#restore_times ⇒ Object
default -> true.
Class Method Summary collapse
-
.count_entries(path_or_io) ⇒ Object
Count the entries in a zip archive without reading the whole set of entry data into memory.
-
.foreach(zip_file_name, &block) ⇒ Object
Iterates over the contents of the ZipFile.
-
.open(file_name, create: false, **options) ⇒ Object
Similar to ::new.
-
.open_buffer(io = ::StringIO.new, create: false, **options) {|zf| ... } ⇒ Object
Like #open, but reads zip archive contents from a String or open IO stream, and outputs data to a buffer.
Instance Method Summary collapse
-
#add(entry, src_path, &continue_on_exists_proc) ⇒ Object
Convenience method for adding the contents of a file to the archive.
-
#add_stored(entry, src_path, &continue_on_exists_proc) ⇒ Object
Convenience method for adding the contents of a file to the archive in Stored format (uncompressed).
-
#close ⇒ Object
Closes the zip file committing any changes that has been made.
-
#commit ⇒ Object
Commits changes that has been made since the previous commit to the zip archive.
-
#commit_required? ⇒ Boolean
Returns true if any changes has been made to this archive since the previous commit.
-
#extract(entry, entry_path = nil, destination_directory: '.', &block) ⇒ Object
Extracts ‘entry` to a file at `entry_path`, with `destination_directory` as the base location in the filesystem.
-
#find_entry(entry_name) ⇒ Object
Searches for entry with the specified name.
-
#get_entry(entry) ⇒ Object
Searches for an entry just as find_entry, but throws Errno::ENOENT if no entry is found.
-
#get_input_stream(entry, &a_proc) ⇒ Object
Returns an input stream to the specified entry.
-
#get_output_stream(entry, permissions: nil, comment: nil, extra: nil, compressed_size: nil, crc: nil, compression_method: nil, compression_level: nil, size: nil, time: nil, &a_proc) ⇒ Object
Returns an output stream to the specified entry.
-
#initialize(path_or_io, create: false, buffer: false, **options) ⇒ File
constructor
Opens a zip archive.
-
#mkdir(entry_name, permission = 0o755) ⇒ Object
Creates a directory.
-
#read(entry) ⇒ Object
Returns a string containing the contents of the specified entry.
-
#remove(entry) ⇒ Object
Removes the specified entry.
-
#rename(entry, new_name, &continue_on_exists_proc) ⇒ Object
Renames the specified entry.
-
#replace(entry, src_path) ⇒ Object
Replaces the specified entry with the contents of src_path (from the file system).
-
#to_s ⇒ Object
Returns the name of the zip archive.
-
#write_buffer(io = ::StringIO.new) ⇒ Object
Write buffer write changes to buffer and return.
Methods included from FileSplit
get_partial_zip_file_name, get_segment_count_for_split, get_segment_size_for_split, put_split_signature, save_splited_part, split
Methods included from FileSystem
Constructor Details
#initialize(path_or_io, create: false, buffer: false, **options) ⇒ File
Opens a zip archive. Pass create: true to create a new archive if it doesn’t exist already.
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 |
# File 'lib/zip/file.rb', line 72 def initialize(path_or_io, create: false, buffer: false, **) super() = DEFAULT_RESTORE_OPTIONS .merge(compression_level: ::Zip.default_compression) .merge() @name = path_or_io.respond_to?(:path) ? path_or_io.path : path_or_io @create = create ? true : false # allow any truthy value to mean true initialize_cdir(path_or_io, buffer: buffer) @restore_ownership = [:restore_ownership] @restore_permissions = [:restore_permissions] @restore_times = [:restore_times] @compression_level = [:compression_level] end |
Instance Attribute Details
#name ⇒ Object (readonly)
Returns the value of attribute name.
57 58 59 |
# File 'lib/zip/file.rb', line 57 def name @name end |
#restore_ownership ⇒ Object
default -> false.
60 61 62 |
# File 'lib/zip/file.rb', line 60 def restore_ownership @restore_ownership end |
#restore_permissions ⇒ Object
default -> true.
63 64 65 |
# File 'lib/zip/file.rb', line 63 def @restore_permissions end |
#restore_times ⇒ Object
default -> true.
66 67 68 |
# File 'lib/zip/file.rb', line 66 def restore_times @restore_times end |
Class Method Details
.count_entries(path_or_io) ⇒ Object
Count the entries in a zip archive without reading the whole set of entry data into memory.
141 142 143 144 145 146 147 148 149 150 151 |
# File 'lib/zip/file.rb', line 141 def count_entries(path_or_io) cdir = ::Zip::CentralDirectory.new if path_or_io.kind_of?(String) ::File.open(path_or_io, 'rb') do |f| cdir.count_entries(f) end else cdir.count_entries(path_or_io) end end |
.foreach(zip_file_name, &block) ⇒ Object
Iterates over the contents of the ZipFile. This is more efficient than using a ZipInputStream since this methods simply iterates through the entries in the central directory structure in the archive whereas ZipInputStream jumps through the entire archive accessing the local entry headers (which contain the same information as the central directory).
133 134 135 136 137 |
# File 'lib/zip/file.rb', line 133 def foreach(zip_file_name, &block) ::Zip::File.open(zip_file_name) do |zip_file| zip_file.each(&block) end end |
.open(file_name, create: false, **options) ⇒ Object
Similar to ::new. If a block is passed the Zip::File object is passed to the block and is automatically closed afterwards, just as with ruby’s builtin File::open method.
92 93 94 95 96 97 98 99 100 101 |
# File 'lib/zip/file.rb', line 92 def open(file_name, create: false, **) zf = ::Zip::File.new(file_name, create: create, **) return zf unless block_given? begin yield zf ensure zf.close end end |
.open_buffer(io = ::StringIO.new, create: false, **options) {|zf| ... } ⇒ Object
Like #open, but reads zip archive contents from a String or open IO stream, and outputs data to a buffer. (This can be used to extract data from a downloaded zip archive without first saving it to disk.)
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 |
# File 'lib/zip/file.rb', line 107 def open_buffer(io = ::StringIO.new, create: false, **) unless IO_METHODS.map { |method| io.respond_to?(method) }.all? || io.kind_of?(String) raise 'Zip::File.open_buffer expects a String or IO-like argument' \ "(responds to #{IO_METHODS.join(', ')}). Found: #{io.class}" end io = ::StringIO.new(io) if io.kind_of?(::String) zf = ::Zip::File.new(io, create: create, buffer: true, **) return zf unless block_given? yield zf begin zf.write_buffer(io) rescue IOError => e raise unless e. == 'not opened for writing' end end |
Instance Method Details
#add(entry, src_path, &continue_on_exists_proc) ⇒ Object
Convenience method for adding the contents of a file to the archive
203 204 205 206 207 208 209 210 211 212 213 214 215 216 |
# File 'lib/zip/file.rb', line 203 def add(entry, src_path, &continue_on_exists_proc) continue_on_exists_proc ||= proc { ::Zip.continue_on_exists_proc } check_entry_exists(entry, continue_on_exists_proc, 'add') new_entry = if entry.kind_of?(::Zip::Entry) entry else ::Zip::Entry.new( @name, entry.to_s, compression_level: @compression_level ) end new_entry.gather_fileinfo_from_srcpath(src_path) @cdir << new_entry end |
#add_stored(entry, src_path, &continue_on_exists_proc) ⇒ Object
Convenience method for adding the contents of a file to the archive in Stored format (uncompressed)
220 221 222 223 224 225 |
# File 'lib/zip/file.rb', line 220 def add_stored(entry, src_path, &continue_on_exists_proc) entry = ::Zip::Entry.new( @name, entry.to_s, compression_method: ::Zip::Entry::STORED ) add(entry, src_path, &continue_on_exists_proc) end |
#close ⇒ Object
Closes the zip file committing any changes that has been made.
290 291 292 |
# File 'lib/zip/file.rb', line 290 def close commit end |
#commit ⇒ Object
Commits changes that has been made since the previous commit to the zip archive.
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 |
# File 'lib/zip/file.rb', line 263 def commit return if name.kind_of?(StringIO) || !commit_required? on_success_replace do |tmp_file| ::Zip::OutputStream.open(tmp_file) do |zos| @cdir.each do |e| e.write_to_zip_output_stream(zos) e.clean_up end zos.comment = comment end true end initialize_cdir(@name) end |
#commit_required? ⇒ Boolean
Returns true if any changes has been made to this archive since the previous commit
296 297 298 299 300 301 302 303 304 |
# File 'lib/zip/file.rb', line 296 def commit_required? return true if @create || @cdir.dirty? @cdir.each do |e| return true if e.dirty? end false end |
#extract(entry, entry_path = nil, destination_directory: '.', &block) ⇒ Object
Extracts ‘entry` to a file at `entry_path`, with `destination_directory` as the base location in the filesystem.
NB: The caller is responsible for making sure ‘destination_directory` is safe, if it is passed.
254 255 256 257 258 259 |
# File 'lib/zip/file.rb', line 254 def extract(entry, entry_path = nil, destination_directory: '.', &block) block ||= proc { ::Zip.on_exists_proc } found_entry = get_entry(entry) entry_path ||= found_entry.name found_entry.extract(entry_path, destination_directory: destination_directory, &block) end |
#find_entry(entry_name) ⇒ Object
Searches for entry with the specified name. Returns nil if no entry is found. See also get_entry
308 309 310 311 312 313 314 315 316 |
# File 'lib/zip/file.rb', line 308 def find_entry(entry_name) selected_entry = @cdir.find_entry(entry_name) return if selected_entry.nil? selected_entry.restore_ownership = @restore_ownership selected_entry. = @restore_permissions selected_entry.restore_times = @restore_times selected_entry end |
#get_entry(entry) ⇒ Object
Searches for an entry just as find_entry, but throws Errno::ENOENT if no entry is found.
320 321 322 323 324 325 |
# File 'lib/zip/file.rb', line 320 def get_entry(entry) selected_entry = find_entry(entry) raise Errno::ENOENT, entry if selected_entry.nil? selected_entry end |
#get_input_stream(entry, &a_proc) ⇒ Object
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 builtin File.open method.
157 158 159 |
# File 'lib/zip/file.rb', line 157 def get_input_stream(entry, &a_proc) get_entry(entry).get_input_stream(&a_proc) end |
#get_output_stream(entry, permissions: nil, comment: nil, extra: nil, compressed_size: nil, crc: nil, compression_method: nil, compression_level: nil, size: nil, time: nil, &a_proc) ⇒ Object
Returns an output stream to the specified entry. If entry is not an instance of Zip::Entry, a new Zip::Entry will be initialized using the arguments specified. 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 builtin File.open method.
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 |
# File 'lib/zip/file.rb', line 166 def get_output_stream(entry, permissions: nil, comment: nil, extra: nil, compressed_size: nil, crc: nil, compression_method: nil, compression_level: nil, size: nil, time: nil, &a_proc) new_entry = if entry.kind_of?(Entry) entry else Entry.new( @name, entry.to_s, comment: comment, extra: extra, compressed_size: compressed_size, crc: crc, size: size, compression_method: compression_method, compression_level: compression_level, time: time ) end if new_entry.directory? raise ArgumentError, "cannot open stream to directory entry - '#{new_entry}'" end new_entry.unix_perms = zip_streamable_entry = StreamableStream.new(new_entry) @cdir << zip_streamable_entry zip_streamable_entry.get_output_stream(&a_proc) end |
#mkdir(entry_name, permission = 0o755) ⇒ Object
Creates a directory
328 329 330 331 332 333 334 |
# File 'lib/zip/file.rb', line 328 def mkdir(entry_name, = 0o755) raise Errno::EEXIST, "File exists - #{entry_name}" if find_entry(entry_name) entry_name = entry_name.dup.to_s entry_name << '/' unless entry_name.end_with?('/') @cdir << ::Zip::StreamableDirectory.new(@name, entry_name, nil, ) end |
#read(entry) ⇒ Object
Returns a string containing the contents of the specified entry
198 199 200 |
# File 'lib/zip/file.rb', line 198 def read(entry) get_input_stream(entry, &:read) end |
#remove(entry) ⇒ Object
Removes the specified entry.
228 229 230 |
# File 'lib/zip/file.rb', line 228 def remove(entry) @cdir.delete(get_entry(entry)) end |
#rename(entry, new_name, &continue_on_exists_proc) ⇒ Object
Renames the specified entry.
233 234 235 236 237 238 239 |
# File 'lib/zip/file.rb', line 233 def rename(entry, new_name, &continue_on_exists_proc) found_entry = get_entry(entry) check_entry_exists(new_name, continue_on_exists_proc, 'rename') @cdir.delete(found_entry) found_entry.name = new_name @cdir << found_entry end |
#replace(entry, src_path) ⇒ Object
Replaces the specified entry with the contents of src_path (from the file system).
243 244 245 246 247 |
# File 'lib/zip/file.rb', line 243 def replace(entry, src_path) check_file(src_path) remove(entry) add(entry, src_path) end |
#to_s ⇒ Object
Returns the name of the zip archive
193 194 195 |
# File 'lib/zip/file.rb', line 193 def to_s @name end |
#write_buffer(io = ::StringIO.new) ⇒ Object
Write buffer write changes to buffer and return
280 281 282 283 284 285 286 287 |
# File 'lib/zip/file.rb', line 280 def write_buffer(io = ::StringIO.new) return unless commit_required? ::Zip::OutputStream.write_buffer(io) do |zos| @cdir.each { |e| e.write_to_zip_output_stream(zos) } zos.comment = comment end end |