Difference between revisions of "Archive Module"
Line 11: | Line 11: | ||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
− | | width='90' | '''Signatures''' | + | | width='90' | '''Signatures''' |
− | |{{Func|archive:create|$entries as | + | |{{Func|archive:create|$entries as item(), $contents as item()*|xs:base64Binary}}<br />{{Func|archive:create|$entries as item(), $contents as item()*, $options as item()|xs:base64Binary}}<br /> |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Creates a new ZIP archive from the specified entries and contents.<br/>The {{Code|$entries}} | + | |Creates a new ZIP archive from the specified entries and contents.<br/>The {{Code|$entries}} argument contains meta information required to create new ZIP 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|last-modified}}: timestamp, specified as xs:dateTime (default: current time) | ||
* {{Code|compression-level}}: 0-9, 0 = uncompressed (default: 8) | * {{Code|compression-level}}: 0-9, 0 = uncompressed (default: 8) | ||
Line 41: | Line 41: | ||
|- | |- | ||
| '''Errors''' | | '''Errors''' | ||
− | |{{Error|ARCH0001|#Errors}} the number of entries and contents differs.<br />{{Error|ARCH0002|#Errors}} the specified option or its value is invalid or not supported.<br />{{Error|ARCH0003|#Errors}} entry descriptors contain invalid entry names, timestamps or compression levels.<br/>{{Error|ARCH0004|#Errors}} the specified encoding is invalid or not supported, or the string conversion failed.<br/>{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.<br />{{Error|FORG0006|XQuery Errors#Function Errors}} | + | |{{Error|ARCH0001|#Errors}} the number of entries and contents differs.<br />{{Error|ARCH0002|#Errors}} the specified option or its value is invalid or not supported.<br />{{Error|ARCH0003|#Errors}} entry descriptors contain invalid entry names, timestamps or compression levels.<br/>{{Error|ARCH0004|#Errors}} the specified encoding is invalid or not supported, or the string conversion failed.<br/>{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.<br />{{Error|FORG0006|XQuery Errors#Function Errors}} an argument has a wrong type. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
Line 153: | Line 153: | ||
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | |{{Func|archive:update|$zip as xs:base64Binary, $entries as | + | |{{Func|archive:update|$zip as xs:base64Binary, $entries as item()*, $contents as item()*|xs:base64Binary}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 173: | Line 173: | ||
modify replace value of node $c//*[text() = "HELLO WORLD!"] with "HELLO UNIVERSE!" | modify replace value of node $c//*[text() = "HELLO WORLD!"] with "HELLO UNIVERSE!" | ||
return fn:serialize($c) | return fn:serialize($c) | ||
− | let $updated := archive:update($archive, | + | let $updated := archive:update($archive, $doc, $entry) |
return file:write-binary($output, $updated) | return file:write-binary($output, $updated) | ||
</pre> | </pre> | ||
Line 183: | Line 183: | ||
|- | |- | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | |{{Func|archive:delete|$zip as xs:base64Binary, $ | + | |{{Func|archive:delete|$zip as xs:base64Binary, $entries as item()*|xs:base64Binary}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Deletes entries from a zip archive.<br/>The format of {{Code|$ | + | |Deletes entries from a zip archive.<br/>The format of {{Code|$entries}} is the same as for [[#archive:create|archive:create]]. |
|- | |- | ||
| '''Errors''' | | '''Errors''' |
Revision as of 15:55, 17 June 2012
This XQuery Module contains functions to handle ZIP archives. New ZIP archives can be created, existing archives can be updated, and the archive entries can be listed and extracted. This module may soon replace the existing ZIP Module (more information).
Contents
Conventions
All functions in this module are assigned to the http://basex.org/modules/archive
namespace, which is statically bound to the archive
prefix.
All errors are assigned to the http://basex.org/errors
namespace, which is statically bound to the bxerr
prefix.
Functions
archive:create
Signatures | archive:create($entries as item(), $contents as item()*) as xs:base64Binary archive:create($entries as item(), $contents as item()*, $options as item()) as xs:base64Binary |
Summary | Creates a new ZIP archive from the specified entries and contents. The $entries argument contains meta information required to create new ZIP entries. All items may either be of type xs:string , representing the entry name, or element(archive:entry) , containing the name as text node and additional, optional attributes:
An example: <archive:entry last-modified='2011-11-11T11:11:11' compression-level='9' encoding='US-ASCII'>hello.txt</entry> The actual
<archive:options> <archive:format value="zip"/> <archive:algorithm value="deflate"/> </archive:options>
map { "format" := "zip", "algorithm" := "deflate" } Currently, only the default options are supported, which are shown in the above examples. |
Errors | ARCH0001 : the number of entries and contents differs.ARCH0002 : the specified option or its value is invalid or not supported.ARCH0003 : entry descriptors contain invalid entry names, timestamps or compression levels.ARCH0004 : the specified encoding is invalid or not supported, or the string conversion failed.ARCH9999 : archive creation failed for some other reason.FORG0006 : an argument has a wrong type.
|
Examples | The following one-liner creates an archive archive.zip with one file file.txt :
archive:create(<archive:entry>file.txt</archive:entry>, 'Hello World') The following function creates an archive let $path := 'audio/' let $files := file:list($path, true(), '*.mp3') let $zip := archive:create( $files ! element archive:entry { . }, $files ! file:read-binary($path || .) ) return file:write-binary('mp3.zip', $zip) |
archive:entries
Signatures | archive:entries($zip as xs:base64Binary) as element(archive:entry)* |
Summary | Returns the entry descriptors of the given zip archive. A descriptor contains the following attributes:
An example: <archive:entry size="1840" last-modified="2009-03-20T03:30:32" compressed-size="672"> doc/index.html </archive:entry> |
Errors | ARCH9999 : archive creation failed for some other reason.
|
Examples | Sums up the file sizes of all entries of a JAR file:
sum(archive:entries(file:read-binary('zip.zip'))/@size) |
archive:options
Signatures | archive:options($zip as xs:base64Binary) as element(archive:options)* |
Summary | Returns the options of the given zip archive, as specified by the archive:create function. |
Errors | ARCH0002 : The packing format is not supported.ARCH9999 : archive creation failed for some other reason.
|
archive:extract-text
Signatures | archive:extract-text($zip as xs:base64Binary) as xs:string* archive:extract-text($zip as xs:base64Binary, $entry-names as xs:string*) as xs:string* archive:extract-text($zip as xs:base64Binary, $entry-names as xs:string*, $encoding as xs:string) as xs:string* |
Summary | Extracts archive entries and returns them as texts. The returned entries can be limited to $entry-names .The optional parameter $encoding defines the encoding of the file.
|
Errors | ARCH0004 : the specified encoding is invalid or not supported, or the string conversion failed.ARCH9999 : archive creation failed for some other reason.
|
Examples | The following expression extracts all .txt files from an archive:
let $archive := file:read-binary("documents.zip") for $entry in archive:entries($archive)[ends-with(., '.txt')] return archive:extract-text($archive, $entry) |
archive:extract-binary
Signatures | archive:extract-binary($zip as xs:base64Binary) as xs:string* archive:extract-binary($zip as xs:base64Binary, $entry-names as xs:string*) as xs:base64Binary*
|
Summary | Extracts archive entries and returns them as binaries. The returned entries can be limited to $entry-names .
|
Errors | ARCH9999 : archive creation failed for some other reason.
|
Examples | This example unzips all files of an archive to the current directory:
let $archive := file:read-binary('archive.zip') let $entries := archive:entries($archive) let $contents := archive:extract-binary($archive) for $entry at $p in $entries return file:write-binary($entry, $contents[$p]) |
archive:update
Signatures | archive:update($zip as xs:base64Binary, $entries as item()*, $contents as item()*) as xs:base64Binary
|
Summary | Adds new entries and replaces existing entries in a zip archive. The format of $entries and $contents is the same as for archive:create.
|
Errors | ARCH0001 : the number of entries and contents differs.ARCH0003 : entry descriptors contain invalid entry names, timestamps, compression levels or encodings.ARCH0004 : the specified encoding is invalid or not supported, or the string conversion failed.ARCH9999 : archive creation failed for some other reason.FORG0006 : (some of) the contents are not of type xs:string or xs:base64Binary .
|
Examples | This example replaces texts in a Word document:
declare variable $input := "HelloWorld.docx"; declare variable $output := "HelloUniverse.docx"; declare variable $doc := "word/document.xml"; let $archive := file:read-binary($input) let $entry := copy $c := fn:parse-xml(archive:extract-text($archive, $doc)) modify replace value of node $c//*[text() = "HELLO WORLD!"] with "HELLO UNIVERSE!" return fn:serialize($c) let $updated := archive:update($archive, $doc, $entry) return file:write-binary($output, $updated) |
archive:delete
Signatures | archive:delete($zip as xs:base64Binary, $entries as item()*) as xs:base64Binary
|
Summary | Deletes entries from a zip archive. The format of $entries is the same as for archive:create.
|
Errors | ARCH9999 : archive creation failed for some other reason.
|
Examples | This example deletes all HTML files in an archive and creates a new file:
let $zip := file:read-binary('old.zip') let $entries := archive:entries($zip)[matches(., '\.x?html?$', 'i')] return file:write-binary('new.zip', archive:delete($zip, $entries)) |
Errors
Code | Description |
---|---|
ARCH0001
|
The number of specified entries and contents differs. |
ARCH0002
|
The packing format or the specified option is invalid or not supported. |
ARCH0003
|
Entry descriptors contain invalid entry names, timestamps or compression levels. |
ARCH0004
|
The specified encoding is invalid or not supported, or the string conversion failed. |
ARCH9999
|
ZIP processing failed for some other reason. |
Changelog
The module was introduced with Version 7.3.