Difference between revisions of "Archive Module"
Jump to navigation
Jump to search
Line 1: | Line 1: | ||
− | This [[Module Library|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 | + | This [[Module Library|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 will soon replace the existing [[ZIP Module]]. |
=Conventions= | =Conventions= |
Revision as of 22:22, 28 May 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 will soon replace the existing ZIP Module.
Contents
Conventions
All functions in this module are assigned to the http://basex.org/modules/zip2
namespace, which is statically bound to the zip2
prefix.
All errors are assigned to the http://basex.org/errors
namespace, which is statically bound to the bxerr
prefix.
Functions
zip2:create
Signatures | zip2:create($entries as element(entry)*, $contents as item()*) as xs:base64Binary |
Summary | Creates a new ZIP archive from the specified entries and contents. The $entries descriptors contain meta information required to create new ZIP entries. Beside the mandatory entry name, which is specified in a text node, further optional attributes can be specified:
An example: <entry last-modified='2011-11-11T11:11:11' compression-level='9' encoding='US-ASCII'>hello.txt</entry> The actual |
Errors | FOZ20001 : the number of entries and contents differs.FOZ20002 : (some of) the contents are not of type xs:string or xs:base64Binary .FOZ20003 : entry descriptors contain invalid entry names, timestamps, compression levels or encodings.FOZ29999 : archive creation failed for some other reason.
|
Examples | The following one-liner creates an archive archive.zip with one file file.txt :
zip2:create(<entry>file.txt</entry>, 'Hello World') The following function creates an archive let $path := 'audio/' let $files := file:list($path, true(), '*.mp3') let $zip := zip2:create( for $f in $files return <entry>{ $f }</entry>, for $f in $files return file:read-binary($path || $f) ) return file:write-binary('mp3.zip', $zip) |
zip2:entries
Signatures | zip2:entries($zip as xs:base64Binary) as element(entry)* |
Summary | Returns the entry descriptors of the given zip archive. A descriptor contains the following attributes:
An example: <entry size="1840" last-modified="2009-03-20T03:30:32" compressed-size="672"> doc/index.html </entry> |
Errors | FOZ29999 : archive creation failed for some other reason.
|
Examples | Sums up the file sizes of all entries of a JAR file:
sum(zip2:entries(file:read-binary('zip.zip'))/@size) |
zip2:extract-texts
Signatures | zip2:extract-texts($zip as xs:base64Binary) as xs:string* zip2:extract-texts($zip as xs:base64Binary, $entry-names as xs:string*) as xs:string* zip2:extract-texts($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 | FOZ20003 : the specified encoding is invalid or not supported.FOZ29999 : 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 zip2:entries($archive)[ends-with(., '.txt')] return zip2:extract-texts($archive, $entry) |
zip2:extract-binaries
Signatures | zip2:extract-binaries($zip as xs:base64Binary) as xs:string* zip2:extract-binaries($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 | FOZ29999 : 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 := zip2:entries($archive) let $contents := zip2:extract-binaries($archive) for $entry at $p in $entries return file:write-binary($entry, $contents[$p]) |
zip2:update
Signatures | zip2:update($zip as xs:base64Binary, $entries as element(entry)*, $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 zip2:create.
|
Errors | FOZ20001 : the number of entries and contents differs.FOZ20002 : (some of) the contents are not of type xs:string or xs:base64Binary .FOZ20003 : entry descriptors contain invalid entry names, timestamps, compression levels or encodings.FOZ29999 : archive creation failed for some other reason.
|
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(zip2:extract-texts($archive, $doc)) modify replace value of node $c//*[text() = "HELLO WORLD!"] with "HELLO UNIVERSE!" return fn:serialize($c) let $updated := zip2:update($archive, <entry>{ $doc }</entry>, $entry) return file:write-binary($output, $updated) |
zip2:delete
Signatures | zip2:delete($zip as xs:base64Binary, $entry-names as xs:string*) as xs:base64Binary
|
Summary | Deletes entries from a zip archive. The format of $entry-names is the list of entries to be deleted.
|
Errors | FOZ29999 : 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 := zip2:entries($zip)[matches(., '\.x?html?$', 'i')] return file:write-binary('new.zip', zip2:delete($zip, $entries)) |
Changelog
The module was introduced with Version 7.3.