Archive Module

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

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: last-modified: timestamp, specified as xs:dateTime (default: current time) compression-level: 0-9, 0 = uncompressed (default: 8) encoding: for textual entries (default: UTF-8) An example: <archive:entry last-modified='2011-11-11T11:11:11' compression-level='9' encoding='US-ASCII'>hello.txt</entry> The actual $contents must be xs:string or xs:base64Binary items. The $options parameter contains archiving options, which can either be specified as children of an <archive:options/> element: <archive:options> <archive:format value="zip"/> <archive:algorithm value="deflate"/> </archive:options> as map, which contains all key/value pairs: 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 mp3.zip, which contains all MP3 files of a local directory: let $path := 'audio/' let $files := file:list($path, true(), '*.mp3') let $zip := archive:create( $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: size: original file size last-modified: timestamp, formatted as xs:dateTime compressed-size: compressed file size 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, $entries as item()*) as xs:string* archive:extract-text($zip as xs:base64Binary, $entries as item()*, $encoding as xs:string) as xs:string*
Summary	Extracts archive entries and returns them as texts. The returned entries can be limited to $entries, the format of which is the same as for archive:create. 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, $entries as item()*) as xs:base64Binary*
Summary	Extracts archive entries and returns them as binaries. The returned entries can be limited to $entries, the format of which is the same as for archive:create.
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.