The zip module archives and extract files to and from a zip archive. The zip format is specified by the "ZIP Appnote.txt" file available on PKWare's website www.pkware.com.
The zip module supports zip archive versions up to 6.1. However, password-protection and Zip64 is not supported.
By convention, the name of a zip file should end in ".zip". To abide to the convention, you'll need to add ".zip" yourself to the name.
Zip archives are created with the zip/2 or the zip/3 function. (They are also available as create, to resemble the erl_tar module.)
To extract files from a zip archive, use the unzip/1 or the unzip/2 function. (They are also available as extract.)
To return a list of the files in a zip archive, use the list_dir/1 or the list_dir/2 function. (They are also available as table.)
To print a list of files to the Erlang shell, use either the t/1 or tt/1 function.
In some cases, it is desirable to open a zip archive, and to unzip files from it file by file, without having to reopen the archive. The functions zip_open, zip_get, zip_list_dir and zip_close do this.
Zip64 archives are not currently supported.
Password-protected and encrypted archives are not currently supported
Only the DEFLATE (zlib-compression) and the STORE (uncompressed data) zip methods are supported.
The size of the archive is limited to 2 G-byte (32 bits).
Comments for indivudal files is not supported when creating zip archives. The zip archive comment for the whole zip archive is supported.
There is currently no support for altering an existing zip archive. To add or remove a file from an archive, the whole archive must be recreated.
zip_file()
The record zip_file contains the following fields.
zip_comment
The record zip_comment just contains the archive comment for a zip archive
zip(Name, FileList) -> RetValue
zip(Name, FileList, Options) -> RetValue
create(Name, FileList) -> RetValue
create(Name, FileList, Options) -> RetValue
Types:
Name = filename()
FileList = [FileSpec]
FileSpec = filename() | {filename(), binary()}
Options = [Option]
Option = memory | cooked | verbose | {comment, Comment} | {cwd, CWD} | {compress, What} | {uncompress, What}
What = all | [Extension] | {add, [Extension]} | {del, [Extension]}
Extension = string()
Comment = CWD = string()
RetValue = {ok, Name} | {ok, {Name, binary()}} | {error, Reason}
Reason = term()
The zip function creates a zip archive containing the files specified in FileList.
As synonyms, the functions create/2 and create/3 are provided, to make it resemble the erl_tar module.
The file-list is a list of files, with paths relative to the current directory, they will be stored with this path in the archive. Files may also be specified with data in binaries, to create an archive directly from data.
Files will be compressed using the DEFLATE compression, as described in the Appnote.txt file. However, files will be stored without compression if they already are compressed. The zip/2 and zip/3 checks the file extension to see whether the file should be stored without compression. Files with the following extensions are not compressed: .Z, .zip, .zoo, .arc, .lzh, .arj.
It is possible to override the default behavior and explicitly control what types of files that should be compressed by using the {compress, What} and {uncompress, What} options. It is possible to have several compress and uncompress options. In order to trigger compression of a file, its extension must match with the compress condition and must not match the uncompress condition. For example if compress is set to ["gif", "jpg"] and uncompress is set to ["jpg"], only files with "gif" as extension will be compressed. No other files will be compressed.
The following options are available:
unzip(Archive) -> RetValue
unzip(Archive, Options) -> RetValue
extract(Archive) -> RetValue
extract(Archive, Options) -> RetValue
Types:
Archive = filename() | binary()
Options = [Option]
Option = {file_list, FileList} | keep_old_files | verbose | memory | {file_filter, FileFilter} | {cwd, CWD}
FileList = [filename()]
FileBinList = [{filename(),binary()}]
FileFilter = fun(ZipFile) -> true | false
CWD = string()
ZipFile = zip_file()
RetValue = {ok,FileList} | {ok,FileBinList} | {error, Reason} | {error, {Name, Reason}}
Reason = term()
The unzip/1 function extracts all files from a zip archive. The unzip/2 function provides options to extract some files, and more.
If the Archive argument is given as a binary, the contents of the binary is assumed to be a zip archive, otherwise it should be a filename.
The following options are available:
list_dir(Archive) -> RetValue
list_dir(Archive, Options)
table(Archive) -> RetValue
table(Archive, Options)
Types:
Archive = filename() | binary()
RetValue = {ok, [Comment, Files]} | {error, Reason}
Comment = zip_comment()
Files = [zip_file()]
Options = [Option]
Option = cooked
Reason = term()
The list_dir/1 function retrieves the names of all files in the zip archive Archive. The list_dir/2 function provides options.
As synonyms, the functions table/2 and table/3 are provided, to make it resemble the erl_tar module.
The result value is the tuple {ok, List}, where List contains the zip archive comment as the first element.
The following options are available:
Types:
Archive = filename() | binary() | ZipHandle
ZipHandle = pid()
The t/1 function prints the names of all files in the zip archive Archive to the Erlang shell. (Similar to "tar t".)
Types:
Archive = filename() | binary()
The tt/1 function prints names and information about all files in the zip archive Archive to the Erlang shell. (Similar to "tar tv".)
zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
Types:
Archive = filename() | binary()
Options = [Option]
Options = cooked | memory | {cwd, CWD}
CWD = string()
ZipHandle = pid()
The zip_open function opens a zip archive, and reads and saves its directory. This means that subsequently reading files from the archive will be faster than unzipping files one at a time with unzip.
The archive must be closed with zip_close/1.
zip_list_dir(ZipHandle) -> Result | {error, Reason}
Types:
Result = [ZipComment, ZipFile...]
ZipComment = #zip_comment{}
ZipFile = #zip_file{}
ZipHandle = pid()
zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
Types:
FileName = filename()
ZipHandle = pid()
Result = filename() | {filename(), binary()}
The zip_get function extracts one or all files from an open archive.
The files will be unzipped to memory or to file, depending on the options given to the zip_open function when the archive was opened.
zip_close(ZipHandle) -> ok | {error, einval}
Types:
ZipHandle = pid()
The zip_close/1 function closes a zip archive, previously opened with zip_open. All resources are closed, and the handle should not be used after closing.