Class: Zip::ZipFile
- Inherits:
-
ZipCentralDirectory
- Object
- ZipCentralDirectory
- Zip::ZipFile
- Includes:
- ZipFileSystem
- Defined in:
- lib/zip/zip.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.
Class Method Summary collapse
-
.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) ⇒ 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, &aProc) ⇒ Object
Returns an output stream to the specified entry.
-
#initialize(fileName, create = nil) ⇒ ZipFile
constructor
Opens a zip archive.
-
#mkdir(entryName, permissionInt = 0) ⇒ 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.
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
Methods included from Enumerable
Constructor Details
#initialize(fileName, create = nil) ⇒ ZipFile
Opens a zip archive. Pass true as the second parameter to create a new archive if it doesn’t exist already.
1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 |
# File 'lib/zip/zip.rb', line 1019 def initialize(fileName, create = nil) super() @name = fileName @comment = "" if (File.exists?(fileName)) File.open(name, "rb") { |f| read_from_stream(f) } elsif (create) @entrySet = ZipEntrySet.new else raise ZipError, "File #{fileName} not found" end @create = create @storedEntries = @entrySet.dup end |
Instance Attribute Details
#comment ⇒ Object
Returns the zip files comment, if it has one
1051 1052 1053 |
# File 'lib/zip/zip.rb', line 1051 def comment @comment end |
#name ⇒ Object (readonly)
Returns the value of attribute name.
1015 1016 1017 |
# File 'lib/zip/zip.rb', line 1015 def name @name end |
Class Method Details
.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).
1059 1060 1061 1062 1063 1064 |
# File 'lib/zip/zip.rb', line 1059 def ZipFile.foreach(aZipFileName, &block) ZipFile.open(aZipFileName) { |zipFile| zipFile.each(&block) } 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.
1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 |
# File 'lib/zip/zip.rb', line 1037 def ZipFile.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
1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 |
# File 'lib/zip/zip.rb', line 1098 def add(entry, srcPath, &continueOnExistsProc) continueOnExistsProc ||= proc { false } check_entry_exists(entry, continueOnExistsProc, "add") newEntry = entry.kind_of?(ZipEntry) ? entry : ZipEntry.new(@name, entry.to_s) if is_directory(newEntry, srcPath) @entrySet << ZipStreamableDirectory.new(newEntry) else @entrySet << ZipStreamableFile.new(newEntry, srcPath) end end |
#close ⇒ Object
Closes the zip file committing any changes that has been made.
1157 1158 1159 |
# File 'lib/zip/zip.rb', line 1157 def close commit end |
#commit ⇒ Object
Commits changes that has been made since the previous commit to the zip archive.
1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 |
# File 'lib/zip/zip.rb', line 1141 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) } 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
1163 1164 1165 |
# File 'lib/zip/zip.rb', line 1163 def commit_required? return @entrySet != @storedEntries || @create == ZipFile::CREATE end |
#extract(entry, destPath, &onExistsProc) ⇒ Object
Extracts entry to file destPath.
1129 1130 1131 1132 1133 1134 1135 1136 1137 |
# File 'lib/zip/zip.rb', line 1129 def extract(entry, destPath, &onExistsProc) onExistsProc ||= proc { false } foundEntry = get_entry(entry) if foundEntry.is_directory create_directory(foundEntry, destPath, &onExistsProc) else write_file(foundEntry, destPath, &onExistsProc) end end |
#find_entry(entry) ⇒ Object
Searches for entry with the specified name. Returns nil if no entry is found. See also get_entry
1169 1170 1171 1172 1173 1174 |
# File 'lib/zip/zip.rb', line 1169 def find_entry(entry) @entrySet.detect { |e| e.name.sub(/\/$/, "") == entry.to_s.sub(/\/$/, "") } end |
#get_entry(entry) ⇒ Object
Searches for an entry just as find_entry, but throws Errno::ENOENT if no entry is found.
1178 1179 1180 1181 1182 1183 1184 |
# File 'lib/zip/zip.rb', line 1178 def get_entry(entry) selectedEntry = find_entry(entry) unless selectedEntry raise Errno::ENOENT, entry end return 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.
1069 1070 1071 |
# File 'lib/zip/zip.rb', line 1069 def get_input_stream(entry, &aProc) get_entry(entry).get_input_stream(&aProc) end |
#get_output_stream(entry, &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.
1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 |
# File 'lib/zip/zip.rb', line 1076 def get_output_stream(entry, &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 zipStreamableEntry = ZipStreamableStream.new(newEntry) @entrySet << zipStreamableEntry zipStreamableEntry.get_output_stream(&aProc) end |
#mkdir(entryName, permissionInt = 0) ⇒ Object
Creates a directory
1187 1188 1189 1190 1191 1192 |
# File 'lib/zip/zip.rb', line 1187 def mkdir(entryName, = 0) #permissionInt ignored if find_entry(entryName) raise Errno::EEXIST, "File exists - #{entryName}" end @entrySet << ZipStreamableDirectory.new(ZipEntry.new(name, entryName.to_s.ensure_end("/"))) end |
#read(entry) ⇒ Object
Returns a string containing the contents of the specified entry
1093 1094 1095 |
# File 'lib/zip/zip.rb', line 1093 def read(entry) get_input_stream(entry) { |is| is.read } end |
#remove(entry) ⇒ Object
Removes the specified entry.
1110 1111 1112 |
# File 'lib/zip/zip.rb', line 1110 def remove(entry) @entrySet.delete(get_entry(entry)) end |
#rename(entry, newName, &continueOnExistsProc) ⇒ Object
Renames the specified entry.
1115 1116 1117 1118 1119 |
# File 'lib/zip/zip.rb', line 1115 def rename(entry, newName, &continueOnExistsProc) foundEntry = get_entry(entry) check_entry_exists(newName, continueOnExistsProc, "rename") foundEntry.name=newName end |
#replace(entry, srcPath) ⇒ Object
Replaces the specified entry with the contents of srcPath (from the file system).
1123 1124 1125 1126 |
# File 'lib/zip/zip.rb', line 1123 def replace(entry, srcPath) check_file(srcPath) add(remove(entry), srcPath) end |
#to_s ⇒ Object
Returns the name of the zip archive
1088 1089 1090 |
# File 'lib/zip/zip.rb', line 1088 def to_s @name end |