Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
Text replacement - "syntaxhighlight" to "pre"
This [[Module Library|XQuery Module]] contains functions to handle 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. The {{Function|Archive|archive:extract-binary}} function includes an example for writing the contents of an archive to disk.
=Conventions=
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>archive:entries|( $archive as xs:base64Binary|) as element(archive:entry)*}}<br /pre>|-valign="top"
| '''Summary'''
|Returns the entry descriptors of the specified {{Code|$archive}}. A descriptor contains the following attributes, provided that they are available in the archive format:
* {{Code|compressed-size}}: compressed file size
An example:
<syntaxhighlight pre lang="xml">
<archive:entry size="1840" last-modified="2009-03-20T03:30:32" compressed-size="672">
doc/index.html
</archive:entry>
</syntaxhighlightpre>|-valign="top"
| '''Errors'''
|{{Error|error|#Errors}} archive creation failed.
|-valign="top"
|'''Examples'''
|Sums up the file sizes of all entries of a JAR file:
<syntaxhighlight pre lang="'xquery"'>
sum(archive:entries(file:read-binary('zip.zip'))/@size)
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>archive:options|( $archive as xs:base64Binary|) as map(*)}}<br /pre>|-valign="top"
| '''Summary'''
|Returns the options of the specified {{Code|$archive}} in the format specified by {{Function|Archive|archive:create}}.|-valign="top"
| '''Errors'''
|{{Error|format|#Errors}} The archive format is not supported.<br/>{{Error|error|#Errors}} archive creation failed.
|-valign="top"
| '''Examples'''
|A standard ZIP archive will return the following options:
<syntaxhighlight pre lang="'xquery"'>
map {
"format": "zip",
"algorithm": "deflate"
}
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|archive:extract-text|$archive as xs:base64Binary|xs:string*}}<br/pre>{{Func|archive:extract-text|( $archive as xs:base64Binary, $entries as item()*|xs :string*}}<br/>{{Func|archive:extract-text|$archive as xs:base64Binary, $entries as item= ()*, $encoding as xs:string| := ()) as xs:string*}}<br/pre>|-valign="top"
| '''Summary'''
|Extracts entries of the specified {{Code|$archive}} and returns them as texts.<br/>The returned entries can be limited via {{Code|$entries}}. The format of the argument is the same as for {{Function|Archive|archive:create}} (attributes will be ignored).<br/>The encoding of the input files can be specified via {{Code|$encoding}}.|-valign="top"
| '''Errors'''
|{{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|error|#Errors}} archive creation failed.|-valign="top"
| '''Examples'''
|The following expression extracts all {{Code|.txt}} files from an archive:
<syntaxhighlight pre lang="'xquery"'>
let $archive := file:read-binary("documents.zip")
for $entry in archive:entries($archive)[ends-with(., '.txt')]
return archive:extract-text($archive, $entry)
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|archive:extract-binary|$archive as xs:base64Binary|xs:base64Binary*}}<br/pre>{{Func|archive:extract-binary|( $archive as xs:base64Binary, $entries as item()*| := ()) as xs:base64Binary*}}</pre>|-valign="top"
| '''Summary'''
|Extracts entries of the specified {{Code|$archive}} and returns them as binaries.<br/>The returned entries can be limited via {{Code|$entries}}. The format of the argument is the same as for {{Function|Archive|archive:create}} (attributes will be ignored).|-valign="top"
| '''Errors'''
|{{Error|error|#Errors}} archive creation failed.
|-valign="top"
| '''Examples'''
|This example unzips all files of an archive to the current directory:
<syntaxhighlight pre lang="'xquery"'>
let $archive := file:read-binary('archive.zip')
let $entries := archive:entries($archive)
file:create-dir(replace($entry, "[^/]+$", "")),
file:write-binary($entry, $content)
})</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature''' |{{Func|archive:create|$entries as item(), $contents as item()*|xs:base64Binary}}<br /pre>{{Func|archive:create|( $entries as item(), $contents as item()*, $options as map(*)?| := map { }) as xs:base64Binary}}<br /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|encoding}}: for textual entries (default: UTF-8)
An example:
<syntaxhighlight pre lang="xml">
<archive:entry last-modified='2011-11-11T11:11:11'
compression-level='8'
encoding='US-ASCII'>hello.txt</archive:entry>
</syntaxhighlightpre>
The actual {{Code|$contents}} must be {{Code|xs:string}} or {{Code|xs:base64Binary}} items.<br/>
The {{Code|$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}}:
<syntaxhighlight pre lang="'xquery"'>
archive:create(<archive:entry>file.txt</archive:entry>, 'Hello World')
</syntaxhighlightpre>
The following function creates an archive {{Code|mp3.zip}}, which contains all MP3 files of a local directory:
<syntaxhighlight pre lang="'xquery"'>
let $path := 'audio/'
let $files := file:list($path, true(), '*.mp3')
return file:read-binary($path || $file)
)
return file:write-binary('mp3.zip', $zip)</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>archive:update|( $archive as xs:base64Binary, $entries as item()*, $contents as item()*|) as xs:base64Binary}}</pre>|-valign="top"
| '''Summary'''
|Creates an updated version of the specified {{Code|$archive}} with new or replaced entries.<br/>The format of {{Code|$entries}} and {{Code|$contents}} is the same as for {{Function|Archive|archive:create}}.|-valign="top"
| '''Errors'''
|{{Error|number|#Errors}} the number of entries and contents differs.<br />{{Error|descriptor|#Errors}} entry descriptors contain invalid entry names, timestamps, compression levels or encodings.<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|modify|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|error|#Errors}} archive creation failed.|-valign="top"
| '''Examples'''
|This example replaces texts in a Word document:
<syntaxhighlight pre lang="'xquery"'>
declare variable $input := "HelloWorld.docx";
declare variable $output := "HelloUniverse.docx";
let $updated := archive:update($archive, $doc, $entry)
return file:write-binary($output, $updated)
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>archive:delete|( $archive as xs:base64Binary, $entries as item()*|) as xs:base64Binary}}</pre>|-valign="top"
| '''Summary'''
|Deletes entries from an {{Code|$archive}}.<br/>The format of {{Code|$entries}} is the same as for {{Function|Archive|archive:create}}.|-valign="top"
| '''Errors'''
|{{Error|modify|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|error|#Errors}} archive creation failed.
|-valign="top"
| '''Examples'''
|This example deletes all HTML files in an archive and creates a new file:
<syntaxhighlight pre lang="'xquery"'>
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))
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|archive:create-from|$path as xs:string|xs:base64Binary}}<br/pre>{{Func|archive:create-from|( $path as xs:string, $options as map(*)?|xs :base64Binary= map { }}<br/>{{Func|archive:create-from|$path as xs:string, $options as 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|archive:create}}, but with two additional options are available:
* {{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>:
<syntaxhighlight pre lang="'xquery"'>
let $zip := archive:create-from('/home/user/')
return file:write-binary('archive.zip', $zip)
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|archive:extract-to|$path as xs:string, $archive as xs:base64Binary|empty-sequence()}}<br/pre>{{Func|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|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:
<syntaxhighlight pre lang="'xquery"'>
archive:extract-to('.', file:read-binary('archive.zip'))
</syntaxhighlightpre>
|}
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature''' |{{Func|archive:write|$path as xs:string, $entries as item(), $contents as item()*|xs:base64Binary}}<br /pre>{{Func|archive:write|( $path as xs:string, $entries as item(), $contents as item()*, $options as map(*)?| := map { }) as xs:base64Binary}}<br /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:
<syntaxhighlight pre lang="'xquery"'>
let $files := file:children('music')[ends-with(., 'mp3')]
return archive:write(
('Archive with MP3 files', $files ! file:read-binary(.))
)
</syntaxhighlightpre>
|}
! width="110"|Code
|Description
|-valign="top"
|{{Code|descriptor}}
|Entry descriptors contain invalid entry names, timestamps or compression levels.
|-valign="top"
|{{Code|encode}}
|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.
|-valign="top"
|{{Code|error}}
|Archive 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|number}}
|The number of specified entries and contents differs.
|-valign="top"
|{{Code|single}}
|The chosen archive format only allows single entries.
;Version 9.6
* Added: {{Function|Archive|archive:write}}
;Version 9.0
* Updated: {{Function|Archive|archive:create-from}}: options added
* Updated: error codes updated; errors now use the module namespace
;Version 8.5
* Updated: {{Function|Archive|archive:options}}: map returned instead of element
;Version 8.3
* Added: {{Function|Archive|archive:create-from}}, {{Function|Archive|archive:extract-to}} (replaces <code>archive:write</code>)
The module was introduced with Version 7.3.
