Class: Zip::File
- Inherits:
-
CentralDirectory
- Object
- CentralDirectory
- Zip::File
- Includes:
- FileSystem
- Defined in:
- lib/zip/file.rb,
lib/zip/filesystem.rb
Overview
ZipFile is modeled after java.util.zip.ZipFile from the Java SDK. The most important methods are those inherited from ZipCentralDirectory 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'
Zip::ZipFile.open("my.zip", Zip::ZipFile::CREATE) {
|zipfile|
zipfile.get_output_stream("first.txt") { |f| f.puts "Hello from ZipFile" }
zipfile.mkdir("a_dir")
}
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'
Zip::ZipFile.open("my.zip", Zip::ZipFile::CREATE) {
|zipfile|
puts zipfile.read("first.txt")
zipfile.remove("first.txt")
}
ZipFileSystem offers an alternative API that emulates ruby’s interface for accessing the filesystem, ie. the File and Dir classes.
Constant Summary collapse
- CREATE =
1
- SPLIT_SIGNATURE =
0x08074b50
- MAX_SEGMENT_SIZE =
3221225472
- MIN_SEGMENT_SIZE =
65536
- DATA_BUFFER_SIZE =
8192
Constants inherited from CentralDirectory
CentralDirectory::END_OF_CENTRAL_DIRECTORY_SIGNATURE, CentralDirectory::MAX_END_OF_CENTRAL_DIRECTORY_STRUCTURE_SIZE, CentralDirectory::STATIC_EOCD_SIZE
Instance Attribute Summary collapse
-
#comment ⇒ Object
Returns the zip files comment, if it has one.
-
#name ⇒ Object
readonly
Returns the value of attribute name.
-
#restore_ownership ⇒ Object
default -> false.
-
#restore_permissions ⇒ Object
default -> false.
-
#restore_times ⇒ Object
default -> true.
Class Method Summary collapse
-
.add_buffer {|zf| ... } ⇒ Object
Same as #open.
-
.foreach(aZipFileName, &block) ⇒ Object
Iterates over the contents of the ZipFile.
- .get_partial_zip_file_name(zip_file_name, partial_zip_file_name) ⇒ Object
- .get_segment_count_for_split(zip_file_size, segment_size) ⇒ Object
- .get_segment_size_for_split(segment_size) ⇒ Object
-
.open(fileName, create = nil) ⇒ Object
Same as #new.
-
.open_buffer(io) {|zf| ... } ⇒ Object
Like #open, but reads zip archive contents from a String or open IO stream, and outputs data to a buffer.
- .put_split_signature(szip_file, segment_size) ⇒ Object
-
.save_splited_part(zip_file, partial_zip_file_name, zip_file_size, szip_file_index, segment_size, segment_count) ⇒ Object
TODO: Make the code more understandable.
-
.split(zip_file_name, segment_size = MAX_SEGMENT_SIZE, delete_zip_file = true, partial_zip_file_name = nil) ⇒ Object
Splits an archive into parts with segment size.
Instance Method Summary collapse
-
#add(entry, srcPath, &continue_on_exists_proc) ⇒ Object
Convenience method for adding the contents of a file to the archive.
-
#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, dest_path, &block) ⇒ Object
Extracts entry to file dest_path.
-
#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, &aProc) ⇒ Object
Returns an input stream to the specified entry.
-
#get_output_stream(entry, permissionInt = nil, &aProc) ⇒ Object
Returns an output stream to the specified entry.
-
#glob(*args, &block) ⇒ Object
Searches for entries given a glob.
-
#initialize(fileName, create = nil, buffer = false) ⇒ File
constructor
Opens a zip archive.
-
#mkdir(entryName, permissionInt = 0755) ⇒ 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, srcPath) ⇒ Object
Replaces the specified entry with the contents of srcPath (from the file system).
-
#to_s ⇒ Object
Returns the name of the zip archive.
-
#write_buffer ⇒ Object
Write buffer write changes to buffer and return.
Methods included from FileSystem
Methods inherited from CentralDirectory
#==, #each, #entries, #get_e_o_c_d, #read_central_directory_entries, #read_e_o_c_d, #read_from_stream, read_from_stream, #size, #write_to_stream
Constructor Details
#initialize(fileName, create = nil, buffer = false) ⇒ File
Opens a zip archive. Pass true as the second parameter to create a new archive if it doesn’t exist already.
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 |
# File 'lib/zip/file.rb', line 64 def initialize(fileName, create = nil, buffer = false) super() @name = fileName @comment = "" @create = create case when ::File.exists?(fileName) && !buffer @create = nil ::File.open(name, "rb") do |f| read_from_stream(f) end when create @entry_set = EntrySet.new else raise ZipError, "File #{fileName} not found" end @storedEntries = @entry_set.dup @storedComment = @comment @restore_ownership = false @restore_permissions = false @restore_times = true end |
Instance Attribute Details
#comment ⇒ Object
Returns the zip files comment, if it has one
217 218 219 |
# File 'lib/zip/file.rb', line 217 def comment @comment end |
#name ⇒ Object (readonly)
Returns the value of attribute name.
53 54 55 |
# File 'lib/zip/file.rb', line 53 def name @name end |
#restore_ownership ⇒ Object
default -> false
56 57 58 |
# File 'lib/zip/file.rb', line 56 def restore_ownership @restore_ownership end |
#restore_permissions ⇒ Object
default -> false
58 59 60 |
# File 'lib/zip/file.rb', line 58 def @restore_permissions end |
#restore_times ⇒ Object
default -> true
60 61 62 |
# File 'lib/zip/file.rb', line 60 def restore_times @restore_times end |
Class Method Details
.add_buffer {|zf| ... } ⇒ Object
Same as #open. But outputs data to a buffer instead of a file
105 106 107 108 109 |
# File 'lib/zip/file.rb', line 105 def add_buffer zf = ::Zip::File.new('', true, true) yield zf zf.write_buffer end |
.foreach(aZipFileName, &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).
135 136 137 138 139 |
# File 'lib/zip/file.rb', line 135 def foreach(aZipFileName, &block) open(aZipFileName) do |zipFile| zipFile.each(&block) end end |
.get_partial_zip_file_name(zip_file_name, partial_zip_file_name) ⇒ Object
152 153 154 155 156 157 |
# File 'lib/zip/file.rb', line 152 def get_partial_zip_file_name(zip_file_name, partial_zip_file_name) partial_zip_file_name = zip_file_name.sub(/#{::File.basename(zip_file_name)}\z/, partial_zip_file_name + ::File.extname(zip_file_name)) unless partial_zip_file_name.nil? partial_zip_file_name ||= zip_file_name partial_zip_file_name end |
.get_segment_count_for_split(zip_file_size, segment_size) ⇒ Object
159 160 161 |
# File 'lib/zip/file.rb', line 159 def get_segment_count_for_split(zip_file_size, segment_size) (zip_file_size / segment_size).to_i + (zip_file_size % segment_size == 0 ? 0 : 1) end |
.get_segment_size_for_split(segment_size) ⇒ Object
141 142 143 144 145 146 147 148 149 150 |
# File 'lib/zip/file.rb', line 141 def get_segment_size_for_split(segment_size) case when MIN_SEGMENT_SIZE > segment_size MIN_SEGMENT_SIZE when MAX_SEGMENT_SIZE < segment_size MAX_SEGMENT_SIZE else segment_size end end |
.open(fileName, create = nil) ⇒ Object
Same as #new. If a block is passed the ZipFile object is passed to the block and is automatically closed afterwards just as with ruby’s builtin File.open method.
91 92 93 94 95 96 97 98 99 100 101 102 |
# File 'lib/zip/file.rb', line 91 def open(fileName, create = nil) zf = ::Zip::File.new(fileName, create) if block_given? begin yield zf ensure zf.close end else zf end end |
.open_buffer(io) {|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.)
115 116 117 118 119 120 121 122 123 124 125 126 127 |
# File 'lib/zip/file.rb', line 115 def open_buffer(io) zf = ::Zip::File.new('', true, true) if io.is_a? IO zf.read_from_stream(io) elsif io.is_a? String require 'stringio' zf.read_from_stream(StringIO.new(io)) else raise "Zip::ZipFile.open_buffer expects an argument of class String or IO. Found: #{io.class}" end yield zf zf.write_buffer end |
.put_split_signature(szip_file, segment_size) ⇒ Object
163 164 165 166 167 |
# File 'lib/zip/file.rb', line 163 def put_split_signature(szip_file, segment_size) signature_packed = [SPLIT_SIGNATURE].pack('V') szip_file << signature_packed segment_size - signature_packed.size end |
.save_splited_part(zip_file, partial_zip_file_name, zip_file_size, szip_file_index, segment_size, segment_count) ⇒ Object
TODO: Make the code more understandable
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 |
# File 'lib/zip/file.rb', line 172 def save_splited_part(zip_file, partial_zip_file_name, zip_file_size, szip_file_index, segment_size, segment_count) ssegment_size = zip_file_size - zip_file.pos ssegment_size = segment_size if ssegment_size > segment_size szip_file_name = "#{partial_zip_file_name}.#{'%03d'%(szip_file_index)}" ::File.open(szip_file_name, 'wb') do |szip_file| if szip_file_index == 1 ssegment_size = put_split_signature(szip_file, segment_size) end chunk_bytes = 0 until ssegment_size == chunk_bytes || zip_file.eof? segment_bytes_left = ssegment_size - chunk_bytes buffer_size = segment_bytes_left < DATA_BUFFER_SIZE ? segment_bytes_left : DATA_BUFFER_SIZE chunk = zip_file.read(buffer_size) chunk_bytes += buffer_size szip_file << chunk # Info for track splitting yield segment_count, szip_file_index, chunk_bytes, ssegment_size if block_given? end end end |
.split(zip_file_name, segment_size = MAX_SEGMENT_SIZE, delete_zip_file = true, partial_zip_file_name = nil) ⇒ Object
Splits an archive into parts with segment size
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 |
# File 'lib/zip/file.rb', line 194 def split(zip_file_name, segment_size = MAX_SEGMENT_SIZE, delete_zip_file = true, partial_zip_file_name = nil) raise ZipError, "File #{zip_file_name} not found" unless ::File.exists?(zip_file_name) raise Errno::ENOENT, zip_file_name unless ::File.readable?(zip_file_name) zip_file_size = ::File.size(zip_file_name) segment_size = get_segment_size_for_split(segment_size) return if zip_file_size <= segment_size segment_count = get_segment_count_for_split(zip_file_size, segment_size) # Checking for correct zip structure self.open(zip_file_name) {} partial_zip_file_name = get_partial_zip_file_name(zip_file_name, partial_zip_file_name) szip_file_index = 0 ::File.open(zip_file_name, 'rb') do |zip_file| until zip_file.eof? szip_file_index += 1 save_splited_part(zip_file, partial_zip_file_name, zip_file_size, szip_file_index, segment_size, segment_count) end end ::File.delete(zip_file_name) if delete_zip_file szip_file_index end |
Instance Method Details
#add(entry, srcPath, &continue_on_exists_proc) ⇒ Object
Convenience method for adding the contents of a file to the archive
252 253 254 255 256 257 258 |
# File 'lib/zip/file.rb', line 252 def add(entry, srcPath, &continue_on_exists_proc) continue_on_exists_proc ||= proc { Zip.continue_on_exists_proc } check_entry_exists(entry, continue_on_exists_proc, "add") newEntry = entry.kind_of?(Entry) ? entry : Entry.new(@name, entry.to_s) newEntry.gather_fileinfo_from_srcpath(srcPath) @entry_set << newEntry end |
#close ⇒ Object
Closes the zip file committing any changes that has been made.
320 321 322 |
# File 'lib/zip/file.rb', line 320 def close commit end |
#commit ⇒ Object
Commits changes that has been made since the previous commit to the zip archive.
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 |
# File 'lib/zip/file.rb', line 291 def commit return if !commit_required? on_success_replace(name) { |tmpFile| OutputStream.open(tmpFile) { |zos| @entry_set.each { |e| e.write_to_zip_output_stream(zos) e.dirty = false } zos.comment = comment } true } initialize(name) end |
#commit_required? ⇒ Boolean
Returns true if any changes has been made to this archive since the previous commit
326 327 328 329 330 331 |
# File 'lib/zip/file.rb', line 326 def commit_required? @entry_set.each do |e| return true if e.dirty end @comment != @storedComment || @entry_set != @storedEntries || @create == File::CREATE end |
#extract(entry, dest_path, &block) ⇒ Object
Extracts entry to file dest_path.
283 284 285 286 287 |
# File 'lib/zip/file.rb', line 283 def extract(entry, dest_path, &block) block ||= proc { ::Zip.on_exists_proc } found_entry = get_entry(entry) found_entry.extract(dest_path, &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
335 336 337 |
# File 'lib/zip/file.rb', line 335 def find_entry(entry_name) @entry_set.find_entry(entry_name) end |
#get_entry(entry) ⇒ Object
Searches for an entry just as find_entry, but throws Errno::ENOENT if no entry is found.
346 347 348 349 350 351 352 353 354 355 |
# File 'lib/zip/file.rb', line 346 def get_entry(entry) selectedEntry = find_entry(entry) unless selectedEntry raise Errno::ENOENT, entry end selectedEntry.restore_ownership = @restore_ownership selectedEntry. = @restore_permissions selectedEntry.restore_times = @restore_times selectedEntry end |
#get_input_stream(entry, &aProc) ⇒ 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.
222 223 224 |
# File 'lib/zip/file.rb', line 222 def get_input_stream(entry, &aProc) get_entry(entry).get_input_stream(&aProc) end |
#get_output_stream(entry, permissionInt = nil, &aProc) ⇒ Object
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 builtin File.open method.
229 230 231 232 233 234 235 236 237 238 239 |
# File 'lib/zip/file.rb', line 229 def get_output_stream(entry, = nil, &aProc) newEntry = entry.kind_of?(Entry) ? entry : Entry.new(@name, entry.to_s) if newEntry.directory? raise ArgumentError, "cannot open stream to directory entry - '#{newEntry}'" end newEntry.unix_perms = zipStreamableEntry = StreamableStream.new(newEntry) @entry_set << zipStreamableEntry zipStreamableEntry.get_output_stream(&aProc) end |
#glob(*args, &block) ⇒ Object
Searches for entries given a glob
340 341 342 |
# File 'lib/zip/file.rb', line 340 def glob(*args, &block) @entry_set.glob(*args, &block) end |
#mkdir(entryName, permissionInt = 0755) ⇒ Object
Creates a directory
358 359 360 361 362 363 364 365 |
# File 'lib/zip/file.rb', line 358 def mkdir(entryName, = 0755) if find_entry(entryName) raise Errno::EEXIST, "File exists - #{entryName}" end entryName = entryName.dup.to_s entryName << '/' unless entryName.end_with?('/') @entry_set << StreamableDirectory.new(@name, entryName, nil, ) end |
#read(entry) ⇒ Object
Returns a string containing the contents of the specified entry
247 248 249 |
# File 'lib/zip/file.rb', line 247 def read(entry) get_input_stream(entry) { |is| is.read } end |
#remove(entry) ⇒ Object
Removes the specified entry.
261 262 263 |
# File 'lib/zip/file.rb', line 261 def remove(entry) @entry_set.delete(get_entry(entry)) end |
#rename(entry, new_name, &continue_on_exists_proc) ⇒ Object
Renames the specified entry.
266 267 268 269 270 271 272 |
# File 'lib/zip/file.rb', line 266 def rename(entry, new_name, &continue_on_exists_proc) foundEntry = get_entry(entry) check_entry_exists(new_name, continue_on_exists_proc, 'rename') @entry_set.delete(foundEntry) foundEntry.name = new_name @entry_set << foundEntry end |
#replace(entry, srcPath) ⇒ Object
Replaces the specified entry with the contents of srcPath (from the file system).
276 277 278 279 280 |
# File 'lib/zip/file.rb', line 276 def replace(entry, srcPath) check_file(srcPath) remove(entry) add(entry, srcPath) end |
#to_s ⇒ Object
Returns the name of the zip archive
242 243 244 |
# File 'lib/zip/file.rb', line 242 def to_s @name end |
#write_buffer ⇒ Object
Write buffer write changes to buffer and return
311 312 313 314 315 316 317 |
# File 'lib/zip/file.rb', line 311 def write_buffer buffer = OutputStream.write_buffer do |zos| @entry_set.each { |e| e.write_to_zip_output_stream(zos) } zos.comment = comment end return buffer end |