aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/zip.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-06-13 12:33:50 +0200
committerBjörn Gustavsson <[email protected]>2016-06-13 12:33:50 +0200
commit1280c70da91b90592ae4be88f1f045956e716de7 (patch)
tree42a0b48e54a9b5c982ce606b8c7e7ff9c564ade6 /lib/stdlib/doc/src/zip.xml
parent3873cb650711342aced0036e3c2d640df8a73c4b (diff)
parent68d53c01b0b8e9a007a6a30158c19e34b2d2a34e (diff)
downloadotp-1280c70da91b90592ae4be88f1f045956e716de7.tar.gz
otp-1280c70da91b90592ae4be88f1f045956e716de7.tar.bz2
otp-1280c70da91b90592ae4be88f1f045956e716de7.zip
Merge branch 'bjorn/stdlib/doc'
* bjorn/stdlib/doc: Update STDLIB documentation
Diffstat (limited to 'lib/stdlib/doc/src/zip.xml')
-rw-r--r--lib/stdlib/doc/src/zip.xml683
1 files changed, 369 insertions, 314 deletions
diff --git a/lib/stdlib/doc/src/zip.xml b/lib/stdlib/doc/src/zip.xml
index 09a6587583..de23608046 100644
--- a/lib/stdlib/doc/src/zip.xml
+++ b/lib/stdlib/doc/src/zip.xml
@@ -28,98 +28,130 @@
<docno>1</docno>
<approved></approved>
<checked></checked>
- <date>05-11-02</date>
+ <date>2005-11-02</date>
<rev>PA1</rev>
- <file>zip.sgml</file>
+ <file>zip.xml</file>
</header>
<module>zip</module>
- <modulesummary>Utility for reading and creating 'zip' archives.</modulesummary>
+ <modulesummary>Utility for reading and creating 'zip' archives.
+ </modulesummary>
<description>
- <p>The <c>zip</c> 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.</p>
+ <p>This module archives and extracts files to and from a zip
+ archive. The zip format is specified by the "ZIP Appnote.txt" file,
+ available on the PKWARE web site
+ <url href="http://www.pkware.com">www.pkware.com</url>.</p>
<p>The zip module supports zip archive versions up to 6.1. However,
password-protection and Zip64 are not supported.</p>
- <p>By convention, the name of a zip file should end in "<c>.zip</c>".
- To abide to the convention, you'll need to add "<c>.zip</c>" yourself
- to the name.</p>
- <p>Zip archives are created with the
- <seealso marker="#zip_2">zip/2</seealso> or the
- <seealso marker="#zip_2">zip/3</seealso> function. (They are
- also available as <c>create</c>, to resemble the <c>erl_tar</c>
- module.)</p>
- <p>To extract files from a zip archive, use the
- <seealso marker="#unzip_1">unzip/1</seealso> or the
- <seealso marker="#unzip_2">unzip/2</seealso> function. (They are
- also available as <c>extract</c>.)</p>
- <p>To fold a function over all files in a zip archive, use the
- <seealso marker="#foldl_3">foldl_3</seealso> function.</p>
- <p>To return a list of the files in a zip archive, use the
- <seealso marker="#list_dir_1">list_dir/1</seealso> or the
- <seealso marker="#list_dir_2">list_dir/2</seealso> function. (They
- are also available as <c>table</c>.)</p>
- <p>To print a list of files to the Erlang shell,
- use either the <seealso marker="#t_1">t/1</seealso> or
- <seealso marker="#tt_1">tt/1</seealso> function.</p>
- <p>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
- <seealso marker="#zip_open">zip_open</seealso>,
- <seealso marker="#zip_get">zip_get</seealso>,
- <seealso marker="#zip_list_dir">zip_list_dir</seealso> and
- <seealso marker="#zip_close">zip_close</seealso> do this.</p>
+ <p>By convention, the name of a zip file is to end with <c>.zip</c>.
+ To abide to the convention, add <c>.zip</c> to the filename.</p>
+ <list type="bulleted">
+ <item>
+ <p>To create zip archives, use function
+ <seealso marker="#zip/2"><c>zip/2</c></seealso> or
+ <seealso marker="#zip/2"><c>zip/3</c></seealso>. They are
+ also available as <c>create/2,3</c>, to resemble the
+ <seealso marker="erl_tar"><c>erl_tar</c></seealso> module.</p>
+ </item>
+ <item>
+ <p>To extract files from a zip archive, use function
+ <seealso marker="#unzip/1"><c>unzip/1</c></seealso> or
+ <seealso marker="#unzip/2"><c>unzip/2</c></seealso>. They are
+ also available as <c>extract/1,2</c>, to resemble the
+ <seealso marker="erl_tar"><c>erl_tar</c></seealso> module.</p>
+ </item>
+ <item>
+ <p>To fold a function over all files in a zip archive, use function
+ <seealso marker="#foldl/3"><c>foldl/3</c></seealso>.</p>
+ </item>
+ <item>
+ <p>To return a list of the files in a zip archive, use function
+ <seealso marker="#list_dir/1"><c>list_dir/1</c></seealso> or
+ <seealso marker="#list_dir/2"><c>list_dir/2</c></seealso>. They are
+ also available as <c>table/1,2</c>, to resemble the
+ <seealso marker="erl_tar"><c>erl_tar</c></seealso> module.</p>
+ </item>
+ <item>
+ <p>To print a list of files to the Erlang shell, use function
+ <seealso marker="#t/1"><c>t/1</c></seealso> or
+ <seealso marker="#tt/1"><c>tt/1</c></seealso>.</p>
+ </item>
+ <item>
+ <p>Sometimes it is desirable to open a zip archive, and to
+ unzip files from it file by file, without having to reopen the
+ archive. This can be done by functions
+ <seealso marker="#zip_open/1"><c>zip_open/1,2</c></seealso>,
+ <seealso marker="#zip_get/1"><c>zip_get/1,2</c></seealso>,
+ <seealso marker="#zip_list_dir/1"><c>zip_list_dir/1</c></seealso>, and
+ <seealso marker="#zip_close/1"><c>zip_close/1</c></seealso>.</p>
+ </item>
+ </list>
</description>
<section>
- <title>LIMITATIONS</title>
- <p>Zip64 archives are not currently supported.</p>
- <p>Password-protected and encrypted archives are not currently
- supported</p>
- <p>Only the DEFLATE (zlib-compression) and the STORE (uncompressed
- data) zip methods are supported.</p>
- <p>The size of the archive is limited to 2 G-byte (32 bits).</p>
- <p>Comments for individual files is not supported when creating zip
- archives. The zip archive comment for the whole zip archive is
- supported.</p>
- <p>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.</p>
+ <title>Limitations</title>
+ <list type="bulleted">
+ <item>
+ <p>Zip64 archives are not supported.</p>
+ </item>
+ <item>
+ <p>Password-protected and encrypted archives are not supported.</p>
+ </item>
+ <item>
+ <p>Only the DEFLATE (zlib-compression) and the STORE (uncompressed
+ data) zip methods are supported.</p>
+ </item>
+ <item>
+ <p>The archive size is limited to 2 GB (32 bits).</p>
+ </item>
+ <item>
+ <p>Comments for individual files are not supported when creating zip
+ archives. The zip archive comment for the whole zip archive is
+ supported.</p>
+ </item>
+ <item>
+ <p>Changing a zip archive is not supported.
+ To add or remove a file from an archive, the whole archive must be
+ recreated.</p>
+ </item>
+ </list>
</section>
<datatypes>
<datatype>
<name name="zip_comment"/>
<desc>
- <p>The record <c>zip_comment</c> just contains the archive comment for
- a zip archive</p>
+ <p>The record <c>zip_comment</c> only contains the archive comment for
+ a zip archive.</p>
</desc>
</datatype>
<datatype>
<name name="zip_file"/>
<desc>
- <p>The record <c>zip_file</c> contains the following fields.</p>
+ <p>The record <c>zip_file</c> contains the following fields:</p>
<taglist>
<tag><c>name</c></tag>
<item>
- <p>the name of the file</p>
+ <p>The filename</p>
</item>
<tag><c>info</c></tag>
<item>
- <p>file info as in
- <seealso marker="kernel:file#read_file_info/1">file:read_file_info/1</seealso></p>
+ <p>File information as in
+ <seealso marker="kernel:file#read_file_info/1">
+ <c>file:read_file_info/1</c></seealso>
+ in <c>Kernel</c></p>
</item>
<tag><c>comment</c></tag>
<item>
- <p>the comment for the file in the zip archive</p>
+ <p>The comment for the file in the zip archive</p>
</item>
<tag><c>offset</c></tag>
<item>
- <p>the offset of the file in the zip archive (used internally)</p>
+ <p>The file offset in the zip archive (used internally)</p>
</item>
<tag><c>comp_size</c></tag>
<item>
- <p>the compressed size of the file (the uncompressed size is found
- in <c>info</c>)</p>
+ <p>The size of the compressed file (the size of the uncompressed
+ file is found in <c>info</c>)</p>
</item>
</taglist>
</desc>
@@ -133,224 +165,44 @@
<datatype>
<name name="create_option"/>
<desc>
- <p>These options are described in <seealso marker="#zip_options">create/3</seealso>.</p>
+ <p>These options are described in <seealso marker="#zip_options">
+ <c>create/3</c></seealso>.</p>
</desc>
</datatype>
<datatype>
- <name name="handle"/>
+ <name name="handle"/>
<desc>
- <p>As returned by <seealso marker="#zip_open/2">zip_open/2</seealso>.</p>
+ <p>As returned by
+ <seealso marker="#zip_open/2"><c>zip_open/2</c></seealso>.</p>
</desc>
</datatype>
</datatypes>
+
<funcs>
<func>
- <name name="zip" arity="2"/>
- <name name="zip" arity="3"/>
- <name name="create" arity="2"/>
- <name name="create" arity="3"/>
- <fsummary>Create a zip archive with options</fsummary>
- <desc>
- <p>The <marker id="zip_2"></marker><c>zip</c> function creates a
- zip archive containing the files specified in <c><anno>FileList</anno></c>.</p>
- <p>As synonyms, the functions <c>create/2</c> and <c>create/3</c>
- are provided, to make it resemble the <c>erl_tar</c> module.</p>
- <p>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.</p>
- <p>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 <c>zip/2</c> and <c>zip/3</c> functions check the file extension
- to see whether the file should be stored without compression.
- Files with the following extensions are not compressed:
- <c>.Z</c>, <c>.zip</c>, <c>.zoo</c>, <c>.arc</c>, <c>.lzh</c>,
- <c>.arj</c>.</p>
- <p>It is possible to override the default behavior and
- explicitly control what types of files that should be
- compressed by using the <c>{compress, <anno>What</anno>}</c> and
- <c>{uncompress, <anno>What</anno>}</c> options. It is possible to have
- several <c>compress</c> and <c>uncompress</c> options. In
- order to trigger compression of a file, its extension must
- match with the
- <c>compress</c> condition and must not match the
- <c>uncompress</c> condition. For example if <c>compress</c> is
- set to <c>["gif", "jpg"]</c> and <c>uncompress</c> is set to
- <c>["jpg"]</c>, only files with <c>"gif"</c> as extension will
- be compressed. No other files will be compressed.</p>
- <marker id="zip_options"></marker>
- <p>The following options are available:</p>
- <taglist>
- <tag><c>cooked</c></tag>
- <item>
- <p>By default, the <c>open/2</c> function will open the
- zip file in <c>raw</c> mode, which is faster but does not allow
- a remote (erlang) file server to be used. Adding <c>cooked</c>
- to the mode list will override the default and open the zip file
- without the <c>raw</c> option. The same goes for the files
- added.</p>
- </item>
- <tag><c>verbose</c></tag>
- <item>
- <p>Print an informational message about each file
- being added.</p>
- </item>
- <tag><c>memory</c></tag>
- <item>
- <p>The output will not be to a file, but instead as a tuple
- <c>{<anno>FileName</anno>, binary()}</c>. The binary will be a full zip
- archive with header, and can be extracted with for instance
- <c>unzip/2</c>.</p>
- </item>
- <tag><c>{comment, <anno>Comment</anno>}</c></tag>
- <item>
- <p>Add a comment to the zip-archive.</p>
- </item>
- <tag><c>{cwd, <anno>CWD</anno>}</c></tag>
- <item>
- <p>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.)</p>
- </item>
- <tag><c>{compress, <anno>What</anno>}</c></tag>
- <item>
- <p>Controls what types of files will be
- compressed. It is by default set to <c>all</c>. The
- following values of <c>What</c> are allowed:</p>
- <taglist>
- <tag><c>all</c></tag>
- <item><p> means that all files will be compressed (as long
- as they pass the <c>uncompress</c> condition).</p></item>
- <tag><c>[<anno>Extension</anno>]</c></tag>
- <item><p>means that only files with exactly these extensions
- will be compressed.</p></item>
- <tag><c>{add,[<anno>Extension</anno>]}</c></tag>
- <item><p>adds these extensions to the list of compress
- extensions.</p></item>
- <tag><c>{del,[<anno>Extension</anno>]}</c></tag>
- <item><p>deletes these extensions from the list of compress
- extensions.</p></item>
- </taglist>
- </item>
- <tag><c>{uncompress, <anno>What</anno>}</c></tag>
- <item>
- <p>Controls what types of files will be uncompressed. It is by
- default set to <c>[".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]</c>.
- The following values of <c>What</c> are allowed:</p>
- <taglist>
- <tag><c>all</c></tag>
- <item><p> means that no files will be compressed.</p></item>
- <tag><c>[<anno>Extension</anno>]</c></tag>
- <item><p>means that files with these extensions will be
- uncompressed.</p></item>
- <tag><c>{add,[<anno>Extension</anno>]}</c></tag>
- <item><p>adds these extensions to the list of uncompress
- extensions.</p></item>
- <tag><c>{del,[<anno>Extension</anno>]}</c></tag>
- <item><p>deletes these extensions from the list of uncompress
- extensions.</p></item>
- </taglist>
- </item>
- </taglist>
- </desc>
- </func>
- <func>
- <name name="unzip" arity="1"/>
- <name name="unzip" arity="2"/>
- <name name="extract" arity="1"/>
- <name name="extract" arity="2"/>
- <fsummary>Extract files from a zip archive</fsummary>
- <desc>
- <p>The <marker id="unzip_1"></marker><c>unzip/1</c> function extracts
- all files from a zip archive.
- The <marker id="unzip_2"></marker><c>unzip/2</c> function provides
- options to extract some files, and more.</p>
- <p>If the <c><anno>Archive</anno></c> argument is given as a binary,
- the contents of the binary is assumed to be a zip archive,
- otherwise it should be a filename.</p>
- <p>The following options are available:</p>
- <taglist>
- <tag><c>{file_list, <anno>FileList</anno>}</c></tag>
- <item>
- <p>By default, all files will be extracted from the zip
- archive. With the <c>{file_list, <anno>FileList</anno>}</c> option,
- the <c>unzip/2</c> function will only extract the files
- whose names are included in <c><anno>FileList</anno></c>. The full
- paths, including the names of all sub directories within
- the zip archive, must be specified.</p>
- </item>
- <tag><c>cooked</c></tag>
- <item>
- <p>By default, the <c>open/2</c> function will open the
- zip file in <c>raw</c> mode, which is faster but does not allow
- a remote (erlang) file server to be used. Adding <c>cooked</c>
- to the mode list will override the default and open the zip file
- without the <c>raw</c> option. The same goes for the files
- extracted.</p>
- </item>
- <tag><c>keep_old_files</c></tag>
- <item>
- <p>By default, all existing files with the same name as file in
- the zip archive will be overwritten. With the <c>keep_old_files</c>
- option, the <c>unzip/2</c> function will not overwrite any existing
- files. Note that even with the <c>memory</c> option given, which
- means that no files will be overwritten, files existing will be
- excluded from the result.</p>
- </item>
- <tag><c>verbose</c></tag>
- <item>
- <p>Print an informational message as each file is being
- extracted.</p>
- </item>
- <tag><c>memory</c></tag>
- <item>
- <p>Instead of extracting to the current directory, the
- <c>memory</c> option will give the result as a list of tuples
- <c>{Filename, Binary}</c>, where <c>Binary</c> is a binary
- containing the extracted data of the file named <c>Filename</c>
- in the zip archive.</p>
- </item>
- <tag><c>{cwd, CWD}</c></tag>
- <item>
- <p>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.)</p>
- </item>
- </taglist>
- </desc>
- </func>
- <func>
<name name="foldl" arity="3"/>
- <fsummary>Fold a function over all files in a zip archive</fsummary>
+ <fsummary>Fold a function over all files in a zip archive.</fsummary>
<desc>
- <p>The <marker id="foldl_3"></marker> <c>foldl/3</c> function
- calls <c><anno>Fun</anno>(<anno>FileInArchive</anno>, <anno>GetInfo
- </anno>, <anno>GetBin</anno>, <anno>AccIn</anno>)</c> on
- successive files in the <c>Archive</c>, starting with
- <c><anno>AccIn</anno>
- == <anno>Acc0</anno></c>. <c><anno>FileInArchive</anno></c> is
- the name that the file
- has in the archive. <c><anno>GetInfo</anno></c> is a fun that
- returns info
- about the the file. <c><anno>GetBin</anno></c> returns the contents
- of the
- file. Both <c><anno>GetInfo</anno></c> and <c><anno>GetBin</anno></c>
- must be called
- within the <c><anno>Fun</anno></c>. Their behavior is undefined if
- they are
- called outside the context of the <c><anno>Fun</anno></c>.
- The <c><anno>Fun</anno></c>
- must return a new accumulator which is passed to the next
- call. <c>foldl/3</c> returns the final value of the
- accumulator. <c><anno>Acc0</anno></c> 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.</p>
-
- <p>For example:</p>
+ <p>Calls <c><anno>Fun</anno>(<anno>FileInArchive</anno>, <anno>GetInfo
+ </anno>, <anno>GetBin</anno>, <anno>AccIn</anno>)</c> on
+ successive files in the <c>Archive</c>, starting with
+ <c><anno>AccIn</anno> == <anno>Acc0</anno></c>.</p>
+ <p><c><anno>FileInArchive</anno></c> is the name that the file
+ has in the archive.</p>
+ <p><c><anno>GetInfo</anno></c> is a fun that returns information
+ about the file.</p>
+ <p><c><anno>GetBin</anno></c> returns the file contents.</p>
+ <p>Both <c><anno>GetInfo</anno></c> and <c><anno>GetBin</anno></c>
+ must be called within the <c><anno>Fun</anno></c>. Their behavior is
+ undefined if they are called outside the context of
+ <c><anno>Fun</anno></c>.</p>
+ <p>The <c><anno>Fun</anno></c> must return a new accumulator, which is
+ passed to the next call. <c>foldl/3</c> returns the final accumulator
+ value. <c><anno>Acc0</anno></c> is returned if the archive is
+ empty. It is not necessary to iterate over all files in the archive.
+ The iteration can be ended prematurely in a controlled manner
+ by throwing an exception.</p>
+ <p><em>Example:</em></p>
<pre>
&gt; <input>Name = "dummy.zip".</input>
"dummy.zip"
@@ -380,97 +232,300 @@
</pre>
</desc>
</func>
+
<func>
<name name="list_dir" arity="1"/>
<name name="list_dir" arity="2"/>
<name name="table" arity="1" />
<name name="table" arity="2"/>
- <fsummary>Retrieve the name of all files in a zip archive</fsummary>
+ <fsummary>Retrieve the name of all files in a zip archive.</fsummary>
<desc>
- <p>The <marker id="list_dir_1"></marker><c>list_dir/1</c>
- function retrieves the names of all files in the zip archive
- <c><anno>Archive</anno></c>. The <marker id="list_dir_2"></marker>
- <c>list_dir/2</c> function provides options.</p>
- <p>As synonyms, the functions <c>table/2</c> and <c>table/3</c>
- are provided, to make it resemble the <c>erl_tar</c> module.</p>
+ <p><c>list_dir/1</c> retrieves all filenames in the zip archive
+ <c><anno>Archive</anno></c>.</p>
+ <p><c>list_dir/2</c> provides options.</p>
+ <p><c>table/1</c> and <c>table/2</c> are provided as synonyms
+ to resemble the
+ <seealso marker="erl_tar"><c>erl_tar</c></seealso> module.</p>
<p>The result value is the tuple <c>{ok, List}</c>, where <c>List</c>
contains the zip archive comment as the first element.</p>
- <p>The following options are available:</p>
+ <p>One option is available:</p>
<taglist>
<tag><c>cooked</c></tag>
<item>
- <p>By default, the <c>open/2</c> function will open the
- zip file in <c>raw</c> mode, which is faster but does not allow
- a remote (erlang) file server to be used. Adding <c>cooked</c>
- to the mode list will override the default and open the zip file
- without the <c>raw</c> option.</p>
+ <p>By default, this function opens the zip file in
+ <c>raw</c> mode, which is faster but does not allow a remote
+ (Erlang) file server to be used. Adding <c>cooked</c> to the
+ mode list overrides the default
+ and opens the zip file without option <c>raw</c>.</p>
</item>
</taglist>
</desc>
</func>
+
<func>
<name name="t" arity="1"/>
- <fsummary>Print the name of each file in a zip archive</fsummary>
+ <fsummary>Print the name of each file in a zip archive.</fsummary>
<desc>
- <p>The <marker id="t_1"></marker><c>t/1</c> function prints the names
- of all files in the zip archive <c><anno>Archive</anno></c> to the Erlang shell.
- (Similar to "<c>tar&nbsp;t</c>".)</p>
+ <p>Prints all filenames in the zip archive <c><anno>Archive</anno></c>
+ to the Erlang shell. (Similar to <c>tar&nbsp;t</c>.)</p>
</desc>
</func>
+
<func>
<name name="tt" arity="1"/>
- <fsummary>Print name and information for each file in a zip archive</fsummary>
+ <fsummary>Print name and information for each file in a zip archive.
+ </fsummary>
<desc>
- <p>The <marker id="tt_1"></marker><c>tt/1</c> function prints names and
- information about all files in the zip archive <c><anno>Archive</anno></c> to
- the Erlang shell. (Similar to "<c>tar tv</c>".)</p>
+ <p>Prints filenames and information about all files in the zip archive
+ <c><anno>Archive</anno></c> to the Erlang shell.
+ (Similar to <c>tar tv</c>.)</p>
</desc>
</func>
+
<func>
- <name name="zip_open" arity="1"/>
- <name name="zip_open" arity="2"/>
- <fsummary>Open an archive and return a handle to it</fsummary>
+ <name name="unzip" arity="1"/>
+ <name name="unzip" arity="2"/>
+ <name name="extract" arity="1"/>
+ <name name="extract" arity="2"/>
+ <fsummary>Extract files from a zip archive.</fsummary>
<desc>
- <p>The <marker id="zip_open"></marker><c>zip_open</c> 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 <c>unzip</c>.</p>
- <p>The archive must be closed with <c>zip_close/1</c>.</p>
- <p>The <c><anno>ZipHandle</anno></c> will be closed if the
- process which originally opened the archive dies.</p>
+ <p><c>unzip/1</c> extracts all files from a zip archive.</p>
+ <p><c>unzip/2</c> provides options to extract some files, and more.</p>
+ <p><c>extract/1</c> and <c>extract/2</c> are provided as synonyms
+ to resemble module
+ <seealso marker="erl_tar"><c>erl_tar</c></seealso>.</p>
+ <p>If argument <c><anno>Archive</anno></c> is specified as a binary,
+ the contents of the binary is assumed to be a zip archive,
+ otherwise a filename.</p>
+ <p>Options:</p>
+ <taglist>
+ <tag><c>{file_list, <anno>FileList</anno>}</c></tag>
+ <item>
+ <p>By default, all files are extracted from the zip
+ archive. With option <c>{file_list, <anno>FileList</anno>}</c>,
+ function <c>unzip/2</c> only extracts the files
+ whose names are included in <c><anno>FileList</anno></c>. The full
+ paths, including the names of all subdirectories within
+ the zip archive, must be specified.</p>
+ </item>
+ <tag><c>cooked</c></tag>
+ <item>
+ <p>By default, this function opens the
+ zip file in <c>raw</c> mode, which is faster but does not allow
+ a remote (Erlang) file server to be used. Adding <c>cooked</c>
+ to the mode list overrides the default and opens the zip file
+ without option <c>raw</c>. The same applies for the files
+ extracted.</p>
+ </item>
+ <tag><c>keep_old_files</c></tag>
+ <item>
+ <p>By default, all files with the same name as files in
+ the zip archive are overwritten. With option <c>keep_old_files</c>
+ set, function <c>unzip/2</c> does not overwrite existing files.
+ Notice that
+ even with option <c>memory</c> specified, which
+ means that no files are overwritten, existing files are
+ excluded from the result.</p>
+ </item>
+ <tag><c>verbose</c></tag>
+ <item>
+ <p>Prints an informational message for each extracted file.</p>
+ </item>
+ <tag><c>memory</c></tag>
+ <item>
+ <p>Instead of extracting to the current directory,
+ the result is given as a list of tuples
+ <c>{Filename, Binary}</c>, where <c>Binary</c> is a binary
+ containing the extracted data of file <c>Filename</c>
+ in the zip archive.</p>
+ </item>
+ <tag><c>{cwd, CWD}</c></tag>
+ <item>
+ <p>Uses the specified directory as current directory. It is
+ prepended to filenames when extracting them from the
+ zip archive. (Acting like
+ <seealso marker="kernel:file#set_cwd/1">
+ <c>file:set_cwd/1</c></seealso> in <c>Kernel</c>,
+ but without changing the global <c>cwd</c> property.)</p>
+ </item>
+ </taglist>
</desc>
</func>
+
<func>
- <name name="zip_list_dir" arity="1"/>
- <fsummary>Return a table of files in open zip archive</fsummary>
+ <name name="zip" arity="2"/>
+ <name name="zip" arity="3"/>
+ <name name="create" arity="2"/>
+ <name name="create" arity="3"/>
+ <fsummary>Create a zip archive with options.</fsummary>
<desc>
- <p>The <marker id="zip_list_dir"></marker>
- <c>zip_list_dir/1</c> function
- returns the file list of an open zip archive. The first returned
- element is the zip archive comment.</p>
+ <p>Creates a zip archive containing the files specified in
+ <c><anno>FileList</anno></c>.</p>
+ <p><c>create/2</c> and <c>create/3</c> are provided as synonyms
+ to resemble module
+ <seealso marker="erl_tar"><c>erl_tar</c></seealso>.</p>
+ <p><c><anno>FileList</anno></c> is a list of files, with paths relative
+ to the current directory, which are stored with this path in the
+ archive. Files can also be specified with data in binaries
+ to create an archive directly from data.</p>
+ <p>Files are compressed using the DEFLATE compression, as
+ described in the "Appnote.txt" file. However, files are
+ stored without compression if they are already compressed.
+ <c>zip/2</c> and <c>zip/3</c> check the file extension
+ to determine if the file is to be stored without compression.
+ Files with the following extensions are not compressed:
+ <c>.Z</c>, <c>.zip</c>, <c>.zoo</c>, <c>.arc</c>, <c>.lzh</c>,
+ <c>.arj</c>.</p>
+ <p>It is possible to override the default behavior and control
+ what types of files that are to be compressed by using options
+ <c>{compress, <anno>What</anno>}</c> and
+ <c>{uncompress, <anno>What</anno>}</c>. It is also possible to use
+ many <c>compress</c> and <c>uncompress</c> options.</p>
+ <p>To trigger file compression, its extension must match with the
+ <c>compress</c> condition and must not match the
+ <c>uncompress</c> condition. For example, if <c>compress</c> is
+ set to <c>["gif", "jpg"]</c> and <c>uncompress</c> is set to
+ <c>["jpg"]</c>, only files with extension <c>"gif"</c> are
+ compressed.</p>
+ <marker id="zip_options"></marker>
+ <p>Options:</p>
+ <taglist>
+ <tag><c>cooked</c></tag>
+ <item>
+ <p>By default, this function opens the
+ zip file in mode <c>raw</c>, which is faster but does not allow
+ a remote (Erlang) file server to be used. Adding <c>cooked</c>
+ to the mode list overrides the default and opens the zip file
+ without the <c>raw</c> option. The same applies for the files
+ added.</p>
+ </item>
+ <tag><c>verbose</c></tag>
+ <item>
+ <p>Prints an informational message about each added file.</p>
+ </item>
+ <tag><c>memory</c></tag>
+ <item>
+ <p>The output is not to a file, but instead as a tuple
+ <c>{<anno>FileName</anno>, binary()}</c>. The binary is a full zip
+ archive with header and can be extracted with, for example,
+ <seealso marker="#unzip/2"><c>unzip/2</c></seealso>.</p>
+ </item>
+ <tag><c>{comment, <anno>Comment</anno>}</c></tag>
+ <item>
+ <p>Adds a comment to the zip archive.</p>
+ </item>
+ <tag><c>{cwd, <anno>CWD</anno>}</c></tag>
+ <item>
+ <p>Uses the specified directory as current work directory
+ (<c>cwd</c>). This is prepended to filenames when adding them,
+ although not in the zip archive (acting like
+ <seealso marker="kernel:file#set_cwd/1">
+ <c>file:set_cwd/1</c></seealso> in <c>Kernel</c>, but without
+ changing the global <c>cwd</c> property.).</p>
+ </item>
+ <tag><c>{compress, <anno>What</anno>}</c></tag>
+ <item>
+ <p>Controls what types of files to be compressed. Defaults to
+ <c>all</c>. The following values of <c>What</c> are allowed:</p>
+ <taglist>
+ <tag><c>all</c></tag>
+ <item>
+ <p>All files are compressed (as long
+ as they pass the <c>uncompress</c> condition).</p>
+ </item>
+ <tag><c>[<anno>Extension</anno>]</c></tag>
+ <item>
+ <p>Only files with exactly these extensions
+ are compressed.</p>
+ </item>
+ <tag><c>{add,[<anno>Extension</anno>]}</c></tag>
+ <item>
+ <p>Adds these extensions to the list of compress
+ extensions.</p>
+ </item>
+ <tag><c>{del,[<anno>Extension</anno>]}</c></tag>
+ <item>
+ <p>Deletes these extensions from the list of compress
+ extensions.</p>
+ </item>
+ </taglist>
+ </item>
+ <tag><c>{uncompress, <anno>What</anno>}</c></tag>
+ <item>
+ <p>Controls what types of files to be uncompressed. Defaults to
+ <c>[".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]</c>.
+ The following values of <c>What</c> are allowed:</p>
+ <taglist>
+ <tag><c>all</c></tag>
+ <item>
+ <p>No files are compressed.</p>
+ </item>
+ <tag><c>[<anno>Extension</anno>]</c></tag>
+ <item>
+ <p>Files with these extensions are uncompressed.</p>
+ </item>
+ <tag><c>{add,[<anno>Extension</anno>]}</c></tag>
+ <item>
+ <p>Adds these extensions to the list of uncompress
+ extensions.</p>
+ </item>
+ <tag><c>{del,[<anno>Extension</anno>]}</c></tag>
+ <item>
+ <p>Deletes these extensions from the list of uncompress
+ extensions.</p>
+ </item>
+ </taglist>
+ </item>
+ </taglist>
</desc>
</func>
+
+ <func>
+ <name name="zip_close" arity="1"/>
+ <fsummary>Close an open archive.</fsummary>
+ <desc>
+ <p>Closes a zip archive, previously opened with
+ <seealso marker="#zip_open/1"><c>zip_open/1,2</c></seealso>.
+ All resources are closed, and the handle is not to be used after
+ closing.</p>
+ </desc>
+ </func>
+
<func>
<name name="zip_get" arity="1"/>
<name name="zip_get" arity="2"/>
- <fsummary>Extract files from an open archive</fsummary>
+ <fsummary>Extract files from an open archive.</fsummary>
<desc>
- <p>The <marker id="zip_get"></marker><c>zip_get</c> function extracts
- one or all files from an open archive.</p>
- <p>The files will be unzipped to memory or to file, depending on
- the options given to the <c>zip_open</c> function when the
- archive was opened.</p>
+ <p>Extracts one or all files from an open archive.</p>
+ <p>The files are unzipped to memory or to file, depending on
+ the options specified to function
+ <seealso marker="#zip_open/1"><c>zip_open/1,2</c></seealso>
+ when opening the archive.</p>
</desc>
</func>
+
<func>
- <name name="zip_close" arity="1"/>
- <fsummary>Close an open archive</fsummary>
+ <name name="zip_list_dir" arity="1"/>
+ <fsummary>Return a table of files in open zip archive.</fsummary>
<desc>
- <p>The <marker id="zip_close"></marker><c>zip_close/1</c> function
- closes a zip archive, previously opened with <c>zip_open</c>. All
- resources are closed, and the handle should not be used after
- closing.</p>
+ <p>Returns the file list of an open zip archive. The first returned
+ element is the zip archive comment.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="zip_open" arity="1"/>
+ <name name="zip_open" arity="2"/>
+ <fsummary>Open an archive and return a handle to it.</fsummary>
+ <desc>
+ <p>Opens a zip archive, and reads and saves its directory. This
+ means that later reading files from the archive is
+ faster than unzipping files one at a time with
+ <seealso marker="#unzip/1"><c>unzip/1,2</c></seealso>.</p>
+ <p>The archive must be closed with
+ <seealso marker="#zip_close/1"><c>zip_close/1</c></seealso>.</p>
+ <p>The <c><anno>ZipHandle</anno></c> is closed if the
+ process that originally opened the archive dies.</p>
</desc>
</func>
</funcs>