Class: Zip::ZipFile
- Inherits:
-
ZipCentralDirectory
- Object
- ZipCentralDirectory
- Zip::ZipFile
- Includes:
- ZipFileSystem
- Defined in:
- lib/zip/zip_file.rb,
lib/zip/zipfilesystem.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
Constants inherited from ZipCentralDirectory
Zip::ZipCentralDirectory::END_OF_CENTRAL_DIRECTORY_SIGNATURE, Zip::ZipCentralDirectory::MAX_END_OF_CENTRAL_DIRECTORY_STRUCTURE_SIZE, Zip::ZipCentralDirectory::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.
-
.open(fileName, create = nil) ⇒ Object
Same as #new.
Instance Method Summary collapse
-
#add(entry, srcPath, &continueOnExistsProc) ⇒ 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, destPath, &onExistsProc) ⇒ Object
Extracts entry to file destPath.
-
#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.
-
#initialize(fileName, create = nil, buffer = false) ⇒ ZipFile
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, newName, &continueOnExistsProc) ⇒ 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 ZipFileSystem
Methods inherited from ZipCentralDirectory
#==, #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) ⇒ ZipFile
Opens a zip archive. Pass true as the second parameter to create a new archive if it doesn’t exist already.
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 |
# File 'lib/zip/zip_file.rb', line 60 def initialize(fileName, create = nil, buffer = false) super() @name = fileName @comment = "" case when ::File.exists?(fileName) && !buffer ::File.open(name, "rb") do |f| read_from_stream(f) end when create @entrySet = ZipEntrySet.new else raise ZipError, "File #{fileName} not found" end @create = create @storedEntries = @entrySet.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
120 121 122 |
# File 'lib/zip/zip_file.rb', line 120 def comment @comment end |
#name ⇒ Object (readonly)
Returns the value of attribute name.
49 50 51 |
# File 'lib/zip/zip_file.rb', line 49 def name @name end |
#restore_ownership ⇒ Object
default -> false
52 53 54 |
# File 'lib/zip/zip_file.rb', line 52 def restore_ownership @restore_ownership end |
#restore_permissions ⇒ Object
default -> false
54 55 56 |
# File 'lib/zip/zip_file.rb', line 54 def @restore_permissions end |
#restore_times ⇒ Object
default -> true
56 57 58 |
# File 'lib/zip/zip_file.rb', line 56 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
100 101 102 103 104 |
# File 'lib/zip/zip_file.rb', line 100 def add_buffer zf = ZipFile.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).
112 113 114 115 116 |
# File 'lib/zip/zip_file.rb', line 112 def foreach(aZipFileName, &block) open(aZipFileName) do |zipFile| zipFile.each(&block) 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.
86 87 88 89 90 91 92 93 94 95 96 97 |
# File 'lib/zip/zip_file.rb', line 86 def open(fileName, create = nil) zf = ZipFile.new(fileName, create) if block_given? begin yield zf ensure zf.close end else zf end end |
Instance Method Details
#add(entry, srcPath, &continueOnExistsProc) ⇒ Object
Convenience method for adding the contents of a file to the archive
155 156 157 158 159 160 161 |
# File 'lib/zip/zip_file.rb', line 155 def add(entry, srcPath, &continueOnExistsProc) continueOnExistsProc ||= proc { Zip.[:continue_on_exists_proc] } check_entry_exists(entry, continueOnExistsProc, "add") newEntry = entry.kind_of?(ZipEntry) ? entry : ZipEntry.new(@name, entry.to_s) newEntry.gather_fileinfo_from_srcpath(srcPath) @entrySet << newEntry end |
#close ⇒ Object
Closes the zip file committing any changes that has been made.
223 224 225 |
# File 'lib/zip/zip_file.rb', line 223 def close commit end |
#commit ⇒ Object
Commits changes that has been made since the previous commit to the zip archive.
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 |
# File 'lib/zip/zip_file.rb', line 194 def commit return if !commit_required? on_success_replace(name) { |tmpFile| ZipOutputStream.open(tmpFile) { |zos| @entrySet.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
229 230 231 232 233 234 |
# File 'lib/zip/zip_file.rb', line 229 def commit_required? @entrySet.each do |e| return true if e.dirty end @comment != @storedComment || @entrySet != @storedEntries || @create == ZipFile::CREATE end |
#extract(entry, destPath, &onExistsProc) ⇒ Object
Extracts entry to file destPath.
186 187 188 189 190 |
# File 'lib/zip/zip_file.rb', line 186 def extract(entry, destPath, &onExistsProc) onExistsProc ||= proc { Zip.[:on_exists_proc] } foundEntry = get_entry(entry) foundEntry.extract(destPath, &onExistsProc) end |
#find_entry(entry_name) ⇒ Object
Searches for entry with the specified name. Returns nil if no entry is found. See also get_entry
238 239 240 |
# File 'lib/zip/zip_file.rb', line 238 def find_entry(entry_name) @entrySet.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.
244 245 246 247 248 249 250 251 252 253 |
# File 'lib/zip/zip_file.rb', line 244 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.
125 126 127 |
# File 'lib/zip/zip_file.rb', line 125 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.
132 133 134 135 136 137 138 139 140 141 142 |
# File 'lib/zip/zip_file.rb', line 132 def get_output_stream(entry, = nil, &aProc) newEntry = entry.kind_of?(ZipEntry) ? entry : ZipEntry.new(@name, entry.to_s) if newEntry.directory? raise ArgumentError, "cannot open stream to directory entry - '#{newEntry}'" end newEntry.unix_perms = zipStreamableEntry = ZipStreamableStream.new(newEntry) @entrySet << zipStreamableEntry zipStreamableEntry.get_output_stream(&aProc) end |
#mkdir(entryName, permissionInt = 0755) ⇒ Object
Creates a directory
256 257 258 259 260 261 262 263 |
# File 'lib/zip/zip_file.rb', line 256 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?('/') @entrySet << ZipStreamableDirectory.new(@name, entryName, nil, ) end |
#read(entry) ⇒ Object
Returns a string containing the contents of the specified entry
150 151 152 |
# File 'lib/zip/zip_file.rb', line 150 def read(entry) get_input_stream(entry) { |is| is.read } end |
#remove(entry) ⇒ Object
Removes the specified entry.
164 165 166 |
# File 'lib/zip/zip_file.rb', line 164 def remove(entry) @entrySet.delete(get_entry(entry)) end |
#rename(entry, newName, &continueOnExistsProc) ⇒ Object
Renames the specified entry.
169 170 171 172 173 174 175 |
# File 'lib/zip/zip_file.rb', line 169 def rename(entry, newName, &continueOnExistsProc) foundEntry = get_entry(entry) check_entry_exists(newName, continueOnExistsProc, "rename") @entrySet.delete(foundEntry) foundEntry.name = newName @entrySet << foundEntry end |
#replace(entry, srcPath) ⇒ Object
Replaces the specified entry with the contents of srcPath (from the file system).
179 180 181 182 183 |
# File 'lib/zip/zip_file.rb', line 179 def replace(entry, srcPath) check_file(srcPath) remove(entry) add(entry, srcPath) end |
#to_s ⇒ Object
Returns the name of the zip archive
145 146 147 |
# File 'lib/zip/zip_file.rb', line 145 def to_s @name end |
#write_buffer ⇒ Object
Write buffer write changes to buffer and return
214 215 216 217 218 219 220 |
# File 'lib/zip/zip_file.rb', line 214 def write_buffer buffer = ZipOutputStream.write_buffer do |zos| @entrySet.each { |e| e.write_to_zip_output_stream(zos) } zos.comment = comment end return buffer end |