zip
(stdlib)Utility for reading and creating 'zip' archives.
The zip
module archives and extracts 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 are 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 fold a function over all files in a zip archive, use the foldl_3 function.
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.
LIMITATIONS
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 individual 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.
Types
zip_comment() = #zip_comment{comment = undefined | string()}
The record zip_comment
just contains the archive comment for
a zip archive
zip_file() =
#zip_file{name = undefined | string(),
info = undefined | file:file_info(),
comment = undefined | string(),
offset = undefined | integer() >= 0,
comp_size = undefined | integer() >= 0}
The record zip_file
contains the following fields.
name
the name of the file
info
file info as in file:read_file_info/1
comment
the comment for the file in the zip archive
offset
the offset of the file in the zip archive (used internally)
comp_size
the compressed size of the file (the uncompressed size is found
in info
)
Functions
zip(Name, FileList) -> RetValue
Name = file:name()
FileList = [FileSpec]
FileSpec =
file:name() |
{file:name(), binary()} |
{file:name(), binary(), file:file_info()}RetValue =
{ok, FileName :: file:name()} |
{ok, {FileName :: file:name(), binary()}} |
{error, Reason :: term()}
zip(Name, FileList, Options) -> RetValue
Name = file:name()
FileList = [FileSpec]
FileSpec =
file:name() |
{file:name(), binary()} |
{file:name(), binary(), file:file_info()}Options = [Option]
Option =
memory |
cooked |
verbose |
{comment, Comment} |
{cwd, CWD} |
{compress, What} |
{uncompress, What}What =
all | [Extension] | {add, [Extension]} | {del, [Extension]}Extension = Comment = CWD = string()
RetValue =
{ok, FileName :: file:name()} |
{ok, {FileName :: file:name(), binary()}} |
{error, Reason :: term()}
create(Name, FileList) -> RetValue
Name = file:name()
FileList = [FileSpec]
FileSpec =
file:name() |
{file:name(), binary()} |
{file:name(), binary(), file:file_info()}RetValue =
{ok, FileName :: file:name()} |
{ok, {FileName :: file:name(), binary()}} |
{error, Reason :: term()}
create(Name, FileList, Options) -> RetValue
Name = file:name()
FileList = [FileSpec]
FileSpec =
file:name() |
{file:name(), binary()} |
{file:name(), binary(), file:file_info()}Options = [Option]
Option =
memory |
cooked |
verbose |
{comment, Comment} |
{cwd, CWD} |
{compress, What} |
{uncompress, What}What =
all | [Extension] | {add, [Extension]} | {del, [Extension]}Extension = Comment = CWD = string()
RetValue =
{ok, FileName :: file:name()} |
{ok, {FileName :: file:name(), binary()}} |
{error, Reason :: term()}
The zip
function creates a
zip archive containing the files specified in
.
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
functions check 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,
and
{uncompress,
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:
cooked
By default, the open/2
function will open the
zip file in raw
mode, which is faster but does not allow
a remote (erlang) file server to be used. Adding cooked
to the mode list will override the default and open the zip file
without the raw
option. The same goes for the files
added.
verbose
Print an informational message about each file being added.
memory
The output will not be to a file, but instead as a tuple
{
. The binary will be a full zip
archive with header, and can be extracted with for instance
unzip/2
.
{comment, Comment }
Add a comment to the zip-archive.
{cwd, CWD }
Use the given directory as current directory, it will be prepended to file names when adding them, although it will not be in the zip-archive. (Acting like a file:set_cwd/1, but without changing the global cwd property.)
{compress, What }
Controls what types of files will be
compressed. It is by default set to all
. The
following values of What
are allowed:
all
means that all files will be compressed (as long
as they pass the uncompress
condition).
[Extension ]
means that only files with exactly these extensions will be compressed.
{add,[Extension ]}
adds these extensions to the list of compress extensions.
{del,[Extension ]}
deletes these extensions from the list of compress extensions.
{uncompress, What }
Controls what types of files will be uncompressed. It is by
default set to [".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]
.
The following values of What
are allowed:
all
means that no files will be compressed.
[Extension ]
means that files with these extensions will be uncompressed.
{add,[Extension ]}
adds these extensions to the list of uncompress extensions.
{del,[Extension ]}
deletes these extensions from the list of uncompress extensions.
unzip(Archive) -> RetValue
Archive = file:name() | binary()
RetValue =
{ok, FileList} |
{ok, FileBinList} |
{error, Reason :: term()} |
{error, {Name :: file:name(), Reason :: term()}}FileList = [file:name()]
FileBinList = [{file:name(), binary()}]
unzip(Archive, Options) -> RetValue
Archive = file:name() | binary()
Options = [Option]
Option =
{file_list, FileList} |
keep_old_files |
verbose |
memory |
{file_filter, FileFilter} |
{cwd, CWD}FileList = [file:name()]
FileBinList = [{file:name(), binary()}]
FileFilter = fun((ZipFile) -> boolean())
CWD = string()
ZipFile = zip_file()
RetValue =
{ok, FileList} |
{ok, FileBinList} |
{error, Reason :: term()} |
{error, {Name :: file:name(), Reason :: term()}}
extract(Archive) -> RetValue
Archive = file:name() | binary()
RetValue =
{ok, FileList} |
{ok, FileBinList} |
{error, Reason :: term()} |
{error, {Name :: file:name(), Reason :: term()}}FileList = [file:name()]
FileBinList = [{file:name(), binary()}]
extract(Archive, Options) -> RetValue
Archive = file:name() | binary()
Options = [Option]
Option =
{file_list, FileList} |
keep_old_files |
verbose |
memory |
{file_filter, FileFilter} |
{cwd, CWD}FileList = [file:name()]
FileBinList = [{file:name(), binary()}]
FileFilter = fun((ZipFile) -> boolean())
CWD = string()
ZipFile = zip_file()
RetValue =
{ok, FileList} |
{ok, FileBinList} |
{error, Reason :: term()} |
{error, {Name :: file:name(), 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
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:
{file_list, FileList }
By default, all files will be extracted from the zip
archive. With the {file_list,
option,
the unzip/2
function will only extract the files
whose names are included in
. The full
paths, including the names of all sub directories within
the zip archive, must be specified.
cooked
By default, the open/2
function will open the
zip file in raw
mode, which is faster but does not allow
a remote (erlang) file server to be used. Adding cooked
to the mode list will override the default and open the zip file
without the raw
option. The same goes for the files
extracted.
keep_old_files
By default, all existing files with the same name as file in
the zip archive will be overwritten. With the keep_old_files
option, the unzip/2
function will not overwrite any existing
files. Note that even with the memory
option given, which
means that no files will be overwritten, files existing will be
excluded from the result.
verbose
Print an informational message as each file is being extracted.
memory
Instead of extracting to the current directory, the
memory
option will give the result as a list of tuples
{Filename, Binary}
, where Binary
is a binary
containing the extracted data of the file named Filename
in the zip archive.
{cwd, CWD}
Use the given directory as current directory, it will be prepended to file names when extracting them from the zip-archive. (Acting like a file:set_cwd/1, but without changing the global cwd property.)
foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason}
Fun = fun((FileInArchive, GetInfo, GetBin, AccIn) -> AccOut)
FileInArchive = file:name()
GetInfo = fun(() -> file:file_info())
GetBin = fun(() -> binary())
Acc0 = Acc1 = AccIn = AccOut = term()
Archive = file:name() | {file:name(), binary()}
Reason = term()
The foldl/3
function
calls
on
successive files in the Archive
, starting with
.
is
the name that the file
has in the archive.
is a fun that
returns info
about the the file.
returns the contents
of the
file. Both
and
must be called
within the
. Their behavior is undefined if
they are
called outside the context of the
.
The
must return a new accumulator which is passed to the next
call. foldl/3
returns the final value of the
accumulator.
is returned if the archive is
empty. It is not necessary to iterate over all files in the
archive. The iteration may be ended prematurely in a
controlled manner by throwing an exception.
For example:
>Name = "dummy.zip".
"dummy.zip" >{ok, {Name, Bin}} = zip:create(Name, [{"foo", <<"FOO">>}, {"bar", <<"BAR">>}], [memory]).
{ok,{"dummy.zip", <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0, 0,0,3,0,0,...>>}} >{ok, FileSpec} = zip:foldl(fun(N, I, B, Acc) -> [{N, B(), I()} | Acc] end, [], {Name, Bin}).
{ok,[{"bar",<<"BAR">>, {file_info,3,regular,read_write, {{2010,3,1},{19,2,10}}, {{2010,3,1},{19,2,10}}, {{2010,3,1},{19,2,10}}, 54,1,0,0,0,0,0}}, {"foo",<<"FOO">>, {file_info,3,regular,read_write, {{2010,3,1},{19,2,10}}, {{2010,3,1},{19,2,10}}, {{2010,3,1},{19,2,10}}, 54,1,0,0,0,0,0}}]} >{ok, {Name, Bin}} = zip:create(Name, lists:reverse(FileSpec), [memory]).
{ok,{"dummy.zip", <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0, 0,0,3,0,0,...>>}} >catch zip:foldl(fun("foo", _, B, _) -> throw(B()); (_,_,_,Acc) -> Acc end, [], {Name, Bin}).
<<"FOO">>
list_dir(Archive) -> RetValue
Archive = file:name() | binary()
RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
CommentAndFiles = [zip_comment() | zip_file()]
list_dir(Archive, Options) -> RetValue
Archive = file:name() | binary()
RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
CommentAndFiles = [zip_comment() | zip_file()]
Options = [Option]
Option = cooked
table(Archive) -> RetValue
Archive = file:name() | binary()
RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
CommentAndFiles = [zip_comment() | zip_file()]
table(Archive, Options) -> RetValue
Archive = file:name() | binary()
RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
CommentAndFiles = [zip_comment() | zip_file()]
Options = [Option]
Option = cooked
The list_dir/1
function retrieves the names of all files in the zip 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:
cooked
By default, the open/2
function will open the
zip file in raw
mode, which is faster but does not allow
a remote (erlang) file server to be used. Adding cooked
to the mode list will override the default and open the zip file
without the raw
option.
t(Archive) -> ok
Archive = file:name() | binary() | ZipHandle
ZipHandle = pid()
The t/1
function prints the names
of all files in the zip archive
to the Erlang shell.
(Similar to "tar�t
".)
tt(Archive) -> ok
Archive = file:name() | binary() | ZipHandle
ZipHandle = pid()
The tt/1
function prints names and
information about all files in the zip archive
to
the Erlang shell. (Similar to "tar tv
".)
zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
Archive = file:name() | binary()
ZipHandle = pid()
Reason = term()
zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
Archive = file:name() | binary()
ZipHandle = pid()
Options = [Option]
Option = cooked | memory | {cwd, CWD :: string()}
Reason = term()
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) -> {ok, Result} | {error, Reason}
Result = [zip_comment() | zip_file()]
ZipHandle = pid()
Reason = term()
The
zip_list_dir/1
function
returns the file list of an open zip archive. The first returned
element is the zip archive comment.
zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
ZipHandle = pid()
Result = file:name() | {file:name(), binary()}
Reason = term()
zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
FileName = file:name()
ZipHandle = pid()
Result = file:name() | {file:name(), binary()}
Reason = term()
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}
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.