Changes

This [[Module Library|XQuery Module]] contains functions to handle ZIP archives(including ePub, Open Office, JAR, and many other formats). New ZIP and GZIP archives can be created, existing archives can be updated, and the archive entries can be listed and extracted. This module will soon replace The {{Function||archive:extract-binary}} function includes an example for writing the existing [[ZIP Module]] ([http://spex.basex.org/index.php?title=ZIP_Module more information])contents of an archive to disk.

All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/zip2}} archive</nowiki></code> namespace, which is statically bound to the {{Code|zip2archive}} prefix.<br/>All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.

=FunctionsContent Handling= ==archive:entries==

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|zip2<pre>archive:create|entries( $entries archive as xs:base64Binary) as element(archive:entry)*, $contents as item()*|xs:base64Binary}}<br /pre>|-valign="top"

|Creates a new ZIP archive from Returns the entry descriptors of the specified entries and contents.<br/>The {{Code|$entriesarchive}} descriptors contain meta information required to create new ZIP entries. Beside A descriptor contains the mandatory entry namefollowing attributes, which is specified provided that they are available in a text node, further optional attributes can be specifiedthe archive format:* {{Code|last-modifiedsize}}: timestamp, specified as xs:dateTime (default: current time)original file size* {{Code|compressionlast-levelmodified}}: 0-9timestamp, 0 = uncompressed (defaultformatted as xs: 8)dateTime* {{Code|encodingcompressed-size}}: for textual entries (default: UTF-8)compressed file size

<pre classlang="brush:xml"><archive:entry size="1840" last-modified='2011"2009-1103-11T1120T03:1130:11' compression32" compressed-levelsize='9'"672"> encoding='US-ASCII'>hello doc/index.txthtml</archive:entry>

The actual {{Code|$contents}} must be {{Code|xs:string}} or {{Code|xs:base64Binary}} items.|-valign="top"

|{{Error|FOZ20001|#Errors}} the number of entries and contents differs.<br />{{Error|FOZ20002|#Errors}} (some of) the contents are not of type {{Code|xs:string}} or {{Code|xs:base64Binary}}.<br />{{Error|FOZ20003|#Errors}} entry descriptors contain invalid entry names, timestamps or compression levels.<br/>{{Error|FOZ20004|#Errors}} the specified encoding is invalid or not supported, or encoding failed.<br />{{Error|FOZ29999error|#Errors}} archive creation failed for some other reason.|-valign="top"| '''Examples'''|The following one-liner creates an archive {{Code|archive.zip}} with one Sums up the file {{Code|sizes of all entries of a JAR file.txt}}:<pre classlang="brush:'xquery"'>zip2sum(archive:createentries(<entry>file:read-binary('zip.txt<zip'))/entry>, 'Hello World'@size)

==zip2archive:entriesoptions==

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|zip2<pre>archive:entries|options( $zip archive as xs:base64Binary|element) as map(entry*)*}}<br /pre>|-valign="top"

|Returns the entry descriptors options of the given zip archive. A descriptor contains the following attributes:* specified {{Code|size$archive}}: original file size* in the format specified by {{CodeFunction||last-modifiedarchive:create}}: timestamp, formatted as xs:dateTime.* {{Code|compressed-size}}: compressed file sizeAn example:<pre class="brush:xml"><entry size="1840" last-modifiedvalign="2009-03-20T03:30:32" compressed-size=top"672"> doc/index.html</entry></pre>|-

|{{Error|FOZ29999format|#Errors}} The archive format is not supported.<br/>{{Error|error|#Errors}} archive creation failed for some other reason.|-valign="top"|'''Examples'''|Sums up A standard ZIP archive will return the file sizes of all entries of a JAR filefollowing options:<pre classlang='xquery'>map { "format"brush:xquery">zip",sum(zip2 "algorithm":entries(file:read-binary('zip.zip'))/@size)"deflate"}

==zip2archive:extract-textstext==

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|zip2:extract-texts|$zip as xs:base64Binary|xs:string*}}<br/pre>{{Func|zip2archive:extract-texts|text( $zip archive as xs:base64Binary, $entry-names entries as xs:stringitem()*|xs :string*}}<br/>{{Func|zip2:extract-texts|$zip as xs:base64Binary= (), $entry-names encoding as xs:string*, $encoding := ()) as xs:string|xs:string*}}<br/pre>|-valign="top"

|Extracts entries of the specified {{Code|$archive entries }} and returns them as texts.<br/>The returned entries can be limited to via {{Code|$entry-namesentries}}. The format of the argument is the same as for {{Function||archive:create}}(attributes will be ignored).<br/>The optional parameter encoding of the input files can be specified via {{Code|$encoding}} defines the encoding of the file.|-valign="top"

|{{Error|FOZ20004encode|#Errors}} the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if {{Option|CHECKSTRINGS}} is turned off.<br />{{Error|FOZ29999error|#Errors}} archive creation failed for some other reason.|-valign="top"

<pre classlang="brush:'xquery"'>

for $entry in zip2archive:entries($archive)[ends-with(., '.txt')]return zip2archive:extract-textstext($archive, $entry)

==zip2archive:extract-binariesbinary==

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|zip2:extract-binaries|$zip as xs:base64Binary|xs:string*}}<br/pre>{{Func|zip2archive:extract-binaries|binary( $zip archive as xs:base64Binary, $entry-names entries as xsitem()* :string*|= ()) as xs:base64Binary*}}</pre>|-valign="top"

|Extracts entries of the specified {{Code|$archive entries }} and returns them as binaries.<br/>The returned entries can be limited to via {{Code|$entry-namesentries}}. The format of the argument is the same as for {{Function||archive:create}}(attributes will be ignored).|-valign="top"

|{{Error|FOZ29999error|#Errors}} archive creation failed for some other reason.|-valign="top"

<pre classlang="brush:'xquery"'>

let $entries := zip2archive:entries($archive)let $contents := zip2archive:extract-binariesbinary($archive)return for -each-pair($entries, $contents, function($entry at , $p in content) { file:create-dir(replace($entry, "[^/]+$entries", "")),return file:write-binary($entry, $content)})</pre>|} =Updates= ==archive:create== {| width='100%'|- valign="top"| width='120' | '''Signature''' |<pre>archive:create( $entries as item(), $contents as item()*, $options as map(*)? := map { }) as xs:base64Binary</pre>|- valign="top"| '''Summary'''|Creates a new archive from the specified entries and contents.<br/>The {{Code|$entries}} argument contains meta information required to create new entries. All items may either be of type {{Code|xs:string}}, representing the entry name, or {{Code|element(archive:entry)}}, containing the name as text node and additional, optional attributes:* {{Code|last-modified}}: timestamp, specified as xs:dateTime (default: current time)* {{Code|compression-level}}: 0-9, 0 = uncompressed (default: 8)* {{Code|encoding}}: for textual entries (default: UTF-8)An example:<pre lang="xml"><archive:entry last-modified='2011-11-11T11:11:11' compression-level='8' encoding='US-ASCII'>hello.txt</archive:entry></pre>The actual {{Code|$contents[}} must be {{Code|xs:string}} or {{Code|xs:base64Binary}} items.<br/>The {{Code|$p]options}} parameter contains archiving options:* {{Code|format}}: allowed values are {{Code|zip}} and {{Code|gzip}}. {{Code|zip}} is the default.* {{Code|algorithm}}: allowed values are {{Code|deflate}} and {{Code|stored}} (for the {{Code|zip}} format). {{Code|deflate}} is the default.|- valign="top"| '''Errors'''|{{Error|number|#Errors}} the number of entries and contents differs.<br/>{{Error|format|#Errors}} the specified option or its value is invalid or not supported.<br/>{{Error|descriptor|#Errors}} entry descriptors contain invalid entry names, timestamps or compression levels.<br/>{{Error|encode|#Errors}} the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if {{Option|CHECKSTRINGS}} is turned off.<br/>{{Error|single|#Errors}} the chosen archive format only allows single entries.<br/>{{Error|error|#Errors}} archive creation failed.|- valign="top"| '''Examples'''|The following one-liner creates an archive {{Code|archive.zip}} with one file {{Code|file.txt}}:<pre lang='xquery'>archive:create(<archive:entry>file.txt</archive:entry>, 'Hello World')

==zip2archive:update==

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|zip2<pre>archive:update|( $zip archive as xs:base64Binary, $entries as elementitem(entry)*, $contents as item()*|) as xs:base64Binary}}</pre>|-valign="top"

|Adds Creates an updated version of the specified {{Code|$archive}} with new or replaced entries and replaces existing entries in a zip archive.<br/>The format of {{Code|$entries}} and {{Code|$contents}} is the same as for [[#zip2:create{{Function||zip2archive:create]]}}.|-valign="top"

|{{Error|FOZ20001number|#Errors}} the number of entries and contents differs.<br />{{Error|FOZ20002descriptor|#Errors}} (some of) the contents are not of type entry descriptors contain invalid entry names, timestamps, compression levels or encodings.<br/>{{CodeError|xs:stringencode|#Errors}} the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if {{CodeOption|xs:base64BinaryCHECKSTRINGS}}is turned off.<br />{{Error|FOZ20003modify|#Errors}} entry descriptors contain invalid entry names, timestamps, compression levels or encodingsthe entries of the given archive cannot be modified.<br/>{{Error|FOZ29999error|#Errors}} archive creation failed for some other reason.|-valign="top"

<pre classlang="brush:'xquery"'>

copy $c := fn:parse-xml(zip2archive:extract-textstext($archive, $doc))

let $updated := zip2archive:update($archive, <entry>{ $doc }</entry>, $entry)

==zip2archive:delete==

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|zip2<pre>archive:delete|( $zip archive as xs:base64Binary, $entry-names entries as xs:stringitem()*|) as xs:base64Binary}}</pre>|-valign="top"

|Deletes entries from a zip an {{Code|$archive}}.<br/>The format of {{Code|$entry-namesentries}} is the list of entries to be deletedsame as for {{Function||archive:create}}.|-valign="top"

|{{Error|FOZ29999modify|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|error|#Errors}} archive creation failed for some other reason.|-valign="top"

<pre classlang="brush:'xquery"'>

let $entries := zip2archive:entries($zip)[matches(., '\.x?html?$', 'i')]return file:write-binary('new.zip', zip2archive:delete($zip, $entries))</pre>|} =Convenience= ==archive:create-from== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>archive:create-from( $path as xs:string, $options as map(*)? := map { }, $entries as item()* := ()) as xs:base64Binary</pre>|- valign="top"| '''Summary'''|This convenience function creates an archive from all files in the specified directory {{Code|$path}}.<br/>The {{Code|$options}} parameter contains archiving options, and the files to be archived can be limited via {{Code|$entries}}. The format of the two last arguments is identical to {{Function||archive:create}}, with two additional options:* {{Code|recursive}}: parse all files recursively (default: {{Code|true}}; ignored if entries are specified via the last argument).* {{Code|root-dir}}: use name of supplied directory as archive root directory (default: {{Code|false}}).|- valign="top"| '''Errors'''|{{Error|file:no-dir|File Module#Errors}} the specified path does not point to a directory.<br/>{{Error|file:is-dir|File Module#Errors}} one of the specified entries points to a directory.<br/>{{Error|file:not-found|File Module#Errors}} a specified entry does not exist.<br/>{{Error|error|#Errors}} archive creation failed.|- valign="top"| '''Examples'''|This example writes the files of a user’s home directory to <code>archive.zip</code>:<pre lang='xquery'>let $zip := archive:create-from('/home/user/')return file:write-binary('archive.zip', $zip)</pre>|} ==archive:extract-to== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>archive:extract-to( $path as xs:string, $archive as xs:base64Binary, $entries as item()* := ()) as empty-sequence()</pre>|- valign="top"| '''Summary'''|This convenience function writes files of an {{Code|$archive}} directly to the specified directory {{Code|$path}}.<br/>The archive entries to be written can be restricted via {{Code|$entries}}. The format of the argument is the same as for {{Function||archive:create}} (attributes will be ignored).|- valign="top"| '''Errors'''|{{Error|error|#Errors}} archive creation failed.|- valign="top"| '''Examples'''|The following expression unzips all files of an archive to the current directory:<pre lang='xquery'>archive:extract-to('.', file:read-binary('archive.zip'))</pre>|} ==archive:write== {| width='100%'|- valign="top"| width='120' | '''Signature''' |<pre>archive:write( $path as xs:string, $entries as item(), $contents as item()*, $options as map(*)? := map { }) as xs:base64Binary</pre>|- valign="top"| '''Summary'''|This convenience function creates a new archive from the specified {{Code|$entries}} and {{Code|$contents}} and writes it disk.<br/> See {{Function||archive:create}} for more details.|- valign="top"| '''Errors'''|{{Error|number|#Errors}} the number of entries and contents differs.<br/>{{Error|format|#Errors}} the specified option or its value is invalid or not supported.<br/>{{Error|descriptor|#Errors}} entry descriptors contain invalid entry names, timestamps or compression levels.<br/>{{Error|encode|#Errors}} the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if {{Option|CHECKSTRINGS}} is turned off.<br/>{{Error|single|#Errors}} the chosen archive format only allows single entries.<br/>{{Error|error|#Errors}} archive creation failed.|- valign="top"| '''Examples'''|All mp3 files from a directory are zipped and written to a file, along with an info file:<pre lang='xquery'>let $files := file:children('music')[ends-with(., 'mp3')]return archive:write( 'music.zip', ('info.txt', $files ! file:name(.)), ('Archive with MP3 files', $files ! file:read-binary(.)))

! width="5%110"|Code! width|Description|- valign="top"|{{Code|descriptor}}|Entry descriptors contain invalid entry names, timestamps or compression levels.|- valign="95%top"|{{Code|encode}}|DescriptionThe specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if {{Option|CHECKSTRINGS}} is turned off.|- valign="top"|{{Code|error}}| processing failed.|- valign="top"|{{Code|format}}|The archive format or the specified option is invalid or not supported.|- valign="top"|{{Code|modify}}|The entries of the given archive cannot be modified.|-valign="top"|{{Code|FOZ20001number}}

|-valign="top"|{{Code|FOZ20002}}|(Some of) the contents are not of type {{Code|xs:string}} or {{Code|xs:base64Binary}}.|-|{{Code|FOZ20003}}|Entry descriptors contain invalid entry names, timestamps or compression levels.|-|{{Code|FOZ20004single}}|The specified encoding is invalid or not supported, or encoding failed.|-|{{Code|FOZ29999}}|ZIP processing failed for some other reasonchosen archive format only allows single entries.