aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/zip.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/zip.xml')
-rw-r--r--lib/stdlib/doc/src/zip.xml297
1 files changed, 117 insertions, 180 deletions
diff --git a/lib/stdlib/doc/src/zip.xml b/lib/stdlib/doc/src/zip.xml
index 4d98a20206..b03fc7f4e2 100644
--- a/lib/stdlib/doc/src/zip.xml
+++ b/lib/stdlib/doc/src/zip.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>2006</year><year>2010</year>
+ <year>2006</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -34,11 +34,11 @@
<module>zip</module>
<modulesummary>Utility for reading and creating 'zip' archives.</modulesummary>
<description>
- <p>The <c>zip</c> module archives and extract files to and from a zip
+ <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>The zip module supports zip archive versions up to 6.1. However,
- password-protection and Zip64 is not supported.</p>
+ 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>
@@ -52,7 +52,7 @@
<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>.</p>
+ <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
@@ -85,67 +85,55 @@
recreated.</p>
</section>
- <section>
- <title>DATA TYPES</title>
- <code type="none">
-zip_file() </code>
- <p>The record <c>zip_file</c> contains the following fields.</p>
- <taglist>
- <tag><c>name = string()</c></tag>
- <item>
- <p>the name of the file</p>
- </item>
- <tag><c>info = file_info()</c></tag>
- <item>
- <p>file info as in
- <seealso marker="erts:file#read_file_info/1">file:read_file_info/1</seealso></p>
- </item>
- <tag><c>comment = string()</c></tag>
- <item>
- <p>the comment for the file in the zip archive</p>
- </item>
- <tag><c>offset = integer()</c></tag>
- <item>
- <p>the offset of the file in the zip archive (used internally)</p>
- </item>
- <tag><c>comp_size = integer()</c></tag>
- <item>
- <p>the compressed size of the file (the uncompressed size is found
- in <c>info</c>)</p>
- </item>
- </taglist>
- <code type="none">zip_comment</code>
- <p>The record <c>zip_comment</c> just contains the archive comment for
- a zip archive</p>
- <taglist>
- <tag><c>comment = string()</c></tag>
- <item>
- <p>the comment for the zip archive</p>
- </item>
- </taglist>
- </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>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="zip_file"/>
+ <desc>
+ <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>
+ </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>
+ </item>
+ <tag><c>comment</c></tag>
+ <item>
+ <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>
+ </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>
+ </item>
+ </taglist>
+ </desc>
+ </datatype>
+ </datatypes>
<funcs>
<func>
- <name>zip(Name, FileList) -> RetValue</name>
- <name>zip(Name, FileList, Options) -> RetValue</name>
- <name>create(Name, FileList) -> RetValue</name>
- <name>create(Name, FileList, Options) -> RetValue</name>
+ <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>
- <type>
- <v>Name = filename()</v>
- <v>FileList = [FileSpec]</v>
- <v>FileSpec = filename() | {filename(), binary()} | {filename(), binary(), #file_info{}}</v>
- <v>Options = [Option]</v>
- <v>Option = memory | cooked | verbose | {comment, Comment} | {cwd, CWD} | {compress, What} | {uncompress, What}</v>
- <v>What = all | [Extension] | {add, [Extension]} | {del, [Extension]}</v>
- <v>Extension = string()</v>
- <v>Comment = CWD = string()</v>
- <v>RetValue = {ok, Name} | {ok, {Name, binary()}} | {error, Reason}</v>
- <v>Reason = term()</v>
- </type>
<desc>
<p>The <marker id="zip_2"></marker><c>zip</c> function creates a
- zip archive containing the files specified in <c>FileList</c>.</p>
+ 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
@@ -155,15 +143,15 @@ zip_file() </code>
<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> checks the file extension
+ 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, What}</c> and
- <c>{uncompress, What}</c> options. It is possible to have
+ 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
@@ -191,56 +179,56 @@ zip_file() </code>
<tag><c>memory</c></tag>
<item>
<p>The output will not be to a file, but instead as a tuple
- <c>{FileName, binary()}</c>. The binary will be a full zip
+ <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, Comment}</c></tag>
+ <tag><c>{comment, <anno>Comment</anno>}</c></tag>
<item>
<p>Add a comment to the zip-archive.</p>
</item>
- <tag><c>{cwd, CWD}</c></tag>
+ <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, What}</c></tag>
+ <tag><c>{compress, <anno>What</anno>}</c></tag>
<item>
- <p>Controls what types of files that will be
+ <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>[Extension]</c></tag>
+ <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,[Extension]}</c></tag>
+ <tag><c>{add,[<anno>Extension</anno>]}</c></tag>
<item><p>adds these extensions to the list of compress
extensions.</p></item>
- <tag><c>{del,[Extension]}</c></tag>
+ <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, What}</c></tag>
+ <tag><c>{uncompress, <anno>What</anno>}</c></tag>
<item>
- <p>Controls what types of files that will be uncompressed. It is by
+ <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>[Extension]</c></tag>
+ <tag><c>[<anno>Extension</anno>]</c></tag>
<item><p>means that files with these extensions will be
uncompressed.</p></item>
- <tag><c>{add,[Extension]}</c></tag>
+ <tag><c>{add,[<anno>Extension</anno>]}</c></tag>
<item><p>adds these extensions to the list of uncompress
extensions.</p></item>
- <tag><c>{del,[Extension]}</c></tag>
+ <tag><c>{del,[<anno>Extension</anno>]}</c></tag>
<item><p>deletes these extensions from the list of uncompress
extensions.</p></item>
</taglist>
@@ -249,23 +237,11 @@ zip_file() </code>
</desc>
</func>
<func>
- <name>unzip(Archive) -> RetValue</name>
- <name>unzip(Archive, Options) -> RetValue</name>
- <name>extract(Archive) -> RetValue</name>
- <name>extract(Archive, Options) -> RetValue</name>
+ <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>
- <type>
- <v>Archive = filename() | binary()</v>
- <v>Options = [Option]</v>
- <v>Option = {file_list, FileList} | keep_old_files | verbose | memory | {file_filter, FileFilter} | {cwd, CWD}</v>
- <v>FileList = [filename()]</v>
- <v>FileBinList = [{filename(),binary()}]</v>
- <v>FileFilter = fun(ZipFile) -> true | false</v>
- <v>CWD = string()</v>
- <v>ZipFile = zip_file()</v>
- <v>RetValue = {ok,FileList} | {ok,FileBinList} | {error, Reason} | {error, {Name, Reason}}</v>
- <v>Reason = term()</v>
- </type>
<desc>
<p>The <marker id="unzip_1"></marker>
<c>unzip/1</c> function extracts
@@ -273,17 +249,17 @@ zip_file() </code>
<marker id="unzip_2"></marker>
<c>unzip/2</c> function provides options
to extract some files, and more.</p>
- <p>If the <c>Archive</c> argument is given as a binary,
+ <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, FileList}</c></tag>
+ <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,FileList}</c> option,
+ 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>FileList</c>. The full
+ 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>
@@ -292,7 +268,7 @@ zip_file() </code>
<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 zip file
+ 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>
@@ -301,7 +277,7 @@ zip_file() </code>
<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. Not that even with the <c>memory</c> option given, which
+ 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>
@@ -329,29 +305,29 @@ zip_file() </code>
</desc>
</func>
<func>
- <name>foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason}</name>
+ <name name="foldl" arity="3"/>
<fsummary>Fold a function over all files in a zip archive</fsummary>
- <type>
- <v>Fun = fun(FileInArchive, GetInfo, GetBin, AccIn) -> AccOut</v>
- <v>FileInArchive = filename()</v>
- <v>GetInfo = fun() -> #file_info{}</v>
- <v>GetBin = fun() -> binary()</v>
- <v>Acc0 = Acc1 = AccIn = AccOut = term()</v>
- <v>Archive = filename() | {filename(), binary()}</v>
- </type>
<desc>
<p>The <marker id="foldl_3"></marker> <c>foldl/3</c> function
- calls <c>Fun(FileInArchive, GetInfo, GetBin, AccIn)</c> on
- successive files in the <c>Archive</c>, starting with <c>AccIn
- == Acc0</c>. <c>FileInArchive</c> is the name that the file
- has in the archive. <c>GetInfo</c> is a fun that returns info
- about the the file. <c>GetBin</c> returns the contents of the
- file. Both <c>GetInfo</c> and <c>GetBin</c> must be called
- within the <c>Fun</c>. Their behavior is undefined if they are
- called outside the context of the <c>Fun</c>. The <c>Fun</c>
+ 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>Acc0</c> is returned if the archive is
+ 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>
@@ -387,26 +363,16 @@ zip_file() </code>
</desc>
</func>
<func>
- <name>list_dir(Archive) -> RetValue</name>
- <name>list_dir(Archive, Options)</name>
- <name>table(Archive) -> RetValue</name>
- <name>table(Archive, Options)</name>
+ <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>
- <type>
- <v>Archive = filename() | binary()</v>
- <v>RetValue = {ok, [Comment, Files]} | {error, Reason}</v>
- <v>Comment = zip_comment()</v>
- <v>Files = [zip_file()]</v>
- <v>Options = [Option]</v>
- <v>Option = cooked</v>
- <v>Reason = term()</v>
- </type>
<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>Archive</c>. The
- <marker id="list_dir_2"></marker>
-<c>list_dir/2</c> function provides options.</p>
+ <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>The result value is the tuple <c>{ok, List}</c>, where <c>List</c>
@@ -418,50 +384,34 @@ zip_file() </code>
<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 zip file
+ to the mode list will override the default and open the zip file
without the <c>raw</c> option.</p>
</item>
</taglist>
</desc>
</func>
<func>
- <name>t(Archive)</name>
+ <name name="t" arity="1"/>
<fsummary>Print the name of each file in a zip archive</fsummary>
- <type>
- <v>Archive = filename() | binary() | ZipHandle</v>
- <v>ZipHandle = pid()</v>
- </type>
<desc>
- <p>The <marker id="t_1"></marker>
-<c>t/1</c> function prints the names
- of all files in the zip archive <c>Archive</c> to the Erlang shell.
+ <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>
</desc>
</func>
<func>
- <name>tt(Archive)</name>
+ <name name="tt" arity="1"/>
<fsummary>Print name and information for each file in a zip archive</fsummary>
- <type>
- <v>Archive = filename() | binary()</v>
- </type>
<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>Archive</c> to
+ <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>
</desc>
</func>
<func>
- <name>zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}</name>
- <name>zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}</name>
+ <name name="zip_open" arity="1"/>
+ <name name="zip_open" arity="2"/>
<fsummary>Open an archive and return a handle to it</fsummary>
- <type>
- <v>Archive = filename() | binary()</v>
- <v>Options = [Option]</v>
- <v>Options = cooked | memory | {cwd, CWD}</v>
- <v>CWD = string()</v>
- <v>ZipHandle = pid()</v>
- </type>
<desc>
<p>The <marker id="zip_open"></marker>
<c>zip_open</c> function opens a
@@ -472,29 +422,19 @@ zip_file() </code>
</desc>
</func>
<func>
- <name>zip_list_dir(ZipHandle) -> Result | {error, Reason}</name>
+ <name name="zip_list_dir" arity="1"/>
<fsummary>Return a table of files in open zip archive</fsummary>
- <type>
- <v>Result = [ZipComment, ZipFile...]</v>
- <v>ZipComment = #zip_comment{}</v>
- <v>ZipFile = #zip_file{}</v>
- <v>ZipHandle = pid()</v>
- </type>
<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.</p>
+ <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>
</desc>
</func>
<func>
- <name>zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}</name>
- <name>zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}</name>
+ <name name="zip_get" arity="1"/>
+ <name name="zip_get" arity="2"/>
<fsummary>Extract files from an open archive</fsummary>
- <type>
- <v>FileName = filename()</v>
- <v>ZipHandle = pid()</v>
- <v>Result = filename() | {filename(), binary()}</v>
- </type>
<desc>
<p>The <marker id="zip_get"></marker>
<c>zip_get</c> function extracts
@@ -505,11 +445,8 @@ zip_file() </code>
</desc>
</func>
<func>
- <name>zip_close(ZipHandle) -> ok | {error, einval}</name>
+ <name name="zip_close" arity="1"/>
<fsummary>Close an open archive</fsummary>
- <type>
- <v>ZipHandle = pid()</v>
- </type>
<desc>
<p>The <marker id="zip_close"></marker>
<c>zip_close/1</c> function closes