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.
998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 |
# File 'lib/zip/zip.rb', line 998 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
1030 1031 1032 |
# File 'lib/zip/zip.rb', line 1030 def comment @comment end |
#name ⇒ Object (readonly)
Returns the value of attribute name.
994 995 996 |
# File 'lib/zip/zip.rb', line 994 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).
1038 1039 1040 1041 1042 1043 |
# File 'lib/zip/zip.rb', line 1038 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.
1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 |
# File 'lib/zip/zip.rb', line 1016 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
1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 |
# File 'lib/zip/zip.rb', line 1077 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.
1136 1137 1138 |
# File 'lib/zip/zip.rb', line 1136 def close commit end |
#commit ⇒ Object
Commits changes that has been made since the previous commit to the zip archive.
1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 |
# File 'lib/zip/zip.rb', line 1120 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
1142 1143 1144 |
# File 'lib/zip/zip.rb', line 1142 def commit_required? return @entrySet != @storedEntries || @create == ZipFile::CREATE end |
#extract(entry, destPath, &onExistsProc) ⇒ Object
Extracts entry to file destPath.
1108 1109 1110 1111 1112 1113 1114 1115 1116 |
# File 'lib/zip/zip.rb', line 1108 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
1148 1149 1150 1151 1152 1153 |
# File 'lib/zip/zip.rb', line 1148 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.
1157 1158 1159 1160 1161 1162 1163 |
# File 'lib/zip/zip.rb', line 1157 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.
1048 1049 1050 |
# File 'lib/zip/zip.rb', line 1048 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.
1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 |
# File 'lib/zip/zip.rb', line 1055 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
1166 1167 1168 1169 1170 1171 |
# File 'lib/zip/zip.rb', line 1166 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
1072 1073 1074 |
# File 'lib/zip/zip.rb', line 1072 def read(entry) get_input_stream(entry) { |is| is.read } end |
#remove(entry) ⇒ Object
Removes the specified entry.
1089 1090 1091 |
# File 'lib/zip/zip.rb', line 1089 def remove(entry) @entrySet.delete(get_entry(entry)) end |
#rename(entry, newName, &continueOnExistsProc) ⇒ Object
Renames the specified entry.
1094 1095 1096 1097 1098 |
# File 'lib/zip/zip.rb', line 1094 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).
1102 1103 1104 1105 |
# File 'lib/zip/zip.rb', line 1102 def replace(entry, srcPath) check_file(srcPath) add(remove(entry), srcPath) end |
#to_s ⇒ Object
Returns the name of the zip archive
1067 1068 1069 |
# File 'lib/zip/zip.rb', line 1067 def to_s @name end |