# zip

### MODULE

zip

### MODULE SUMMARY

Utility for reading and creating 'zip' arhcives.

### DESCRIPTION

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.

### 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 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.

### DATA TYPES

    zip_file()

The record `zip_file` contains the following fields.

`name = string()`
  the name of the file
`info = file_info()`
  file info as in file:read_file_info/1
`commenct = string()`
  the comment for the file in the zip archive
`offset = integer()`
  the offset of the file in the zip archive (used internally)
`comp_size = integer()`
  the compressed size of the file (the uncompressed size is found in `info`)

    zip_comment

The record `zip_comment` just contains the archive comment for a zip archive

`comment = string()`
  the comment for the zip archive

### EXPORTS

`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}`
`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`.

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 `{FileName, binary()}`. 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.)

`unzip(Archive) -> RetValue`
`unzip(Archive, Options) -> RetValue`
`extract(Archive) -> RetValue`
`extract(Archive, Options) -> RetValue`

Types:

`Name = filename() | binary()`
`Options = [Option]`
`Option = {files, FileList} | keep_old_files | verbose | memory | {file_filter, FileFilter} | {cwd, CWD}`
`FileList = [filename()]`
`FileFilter = fun(ZipFile) -> true | false`
`CWD = string()`
`ZipFile = zip_file()`
`RetValue = ok | {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:

`{files, FileList}`
  By default, all files will be extracted from the zip archive. With the `{files,Files}` option, the `unzip/2` function will only extract the files whose names are included in `FileList`.
`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 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. Not 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.)

`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:

`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 zip file without the `raw` option.

`t(Archive)`

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`".)

`tt(Archive)`

Types:

`Name = 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:

`Name = 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()`

The `zip_list_dir/1` function returns the file list of an open zip archive.

`zip_get(ZipHandle) -> {ok, Result} | {error, Reason}`
`zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}`

Types:

`Name = filename() | binary() | ZipHandle`
`ZipHandle = pid()`

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.

### AUTHORS

Jakob Cederlund - support@erlang.ericsson.se

stdlib 1.14.5
Copyright © 1991-2007 Ericsson AB