Difference between revisions of "Archive Module"

From BaseX Documentation
Jump to navigation Jump to search
(47 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the {{Code|http://basex.org/modules/archive}} namespace, which is statically bound to the {{Code|archive}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/archive</nowiki></code> namespace, which is statically bound to the {{Code|archive}} prefix.<br/>
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Functions=
 
=Functions=
  
 
==archive:create==
 
==archive:create==
 +
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''  
+
| width='120' | '''Signatures'''  
|{{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 />
+
|{{Func|archive:create|$entries as item(), $contents as item()*|xs:base64Binary}}<br />{{Func|archive:create|$entries as item(), $contents as item()*, $options as map(*)?|xs:base64Binary}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 26: Line 26:
 
</pre>
 
</pre>
 
The actual {{Code|$contents}} must be {{Code|xs:string}} or {{Code|xs:base64Binary}} items.<br/>
 
The actual {{Code|$contents}} must be {{Code|xs:string}} or {{Code|xs:base64Binary}} items.<br/>
The {{Code|$options}} parameter contains archiving options, which can either be specified
+
The {{Code|$options}} parameter contains archiving options:
* as children of an {{Code|<archive:options/>}} element:
+
* {{Code|format}}: allowed values are {{Code|zip}} and {{Code|gzip}}. {{Code|zip}} is the default.
<pre class="brush:xml">
+
* {{Code|algorithm}}: allowed values are {{Code|deflate}} and {{Code|stored}} (for the {{Code|zip}} format). {{Code|deflate}} is the default.
<archive:options>
 
  <archive:format value="zip"/>
 
  <archive:algorithm value="deflate"/>
 
</archive:options>
 
</pre>
 
* as map, which contains all key/value pairs:
 
<pre class="brush:xml">
 
map { "format" := "zip", "algorithm" := "deflate" }
 
</pre>
 
Currently, the following combinations are supported (all others will be rejected):
 
* {{Code|zip}}: {{Code|algorithm}} may be {{Code|stored}} or {{Code|deflate}}
 
* {{Code|gzip}}: algorithm may be {{Code|deflate}}
 
 
|-
 
|-
 
| '''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. Invalid XML characters will be ignored if the <code>[[Options#CHECKSTRINGS|CHECKSTRINGS]]</code> option is turned off.<br/>{{Error|ARCH0005|#Errors}} the chosen archive format only allows single entries.{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.<br />{{Error|FORG0006|XQuery Errors#Function Errors}} an argument has a wrong type.
+
|{{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 for some other reason.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 54: Line 42:
 
let $path  := 'audio/'
 
let $path  := 'audio/'
 
let $files := file:list($path, true(), '*.mp3')
 
let $files := file:list($path, true(), '*.mp3')
let $zip  := archive:create(
+
let $zip  := archive:create($files,
  $files ! element archive:entry { . },
+
   for $file in $files
   $files ! file:read-binary($path || .))
+
  return file:read-binary($path || $file)
 +
)
 
return file:write-binary('mp3.zip', $zip)</pre>
 
return file:write-binary('mp3.zip', $zip)</pre>
 +
|}
 +
 +
==archive:create-from==
 +
 +
{{Mark|Updated with Version 9.2}}: options added.
 +
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|archive:create-from|$path as xs:string|xs:base64Binary}}<br/>{{Func|archive:create-from|$path as xs:string, $options as map(*)?|xs:base64Binary}}<br/>{{Func|archive:create-from|$path as xs:string, $options as map(*)?, $entries as item()*|xs:base64Binary}}
 +
|-
 +
| '''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 [[#archive:create|archive:create]], but 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}}).
 +
|-
 +
| '''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 for some other reason.
 +
|-
 +
| '''Examples'''
 +
|This example writes the files of a user’s home directory to <code>archive.zip</code>:
 +
<pre class="brush:xquery">
 +
let $zip := archive:create-from('/home/user/')
 +
return file:write-binary('archive.zip', $zip)
 +
</pre>
 
|}
 
|}
  
Line 64: Line 78:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|archive:entries|$archive as xs:base64Binary|element(archive:entry)*}}<br />
 
|{{Func|archive:entries|$archive as xs:base64Binary|element(archive:entry)*}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the entry descriptors of the given archive. A descriptor contains the following attributes, provided that they are available in the archive format:
+
|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|size}}: original file size
 
* {{Code|size}}: original file size
 
* {{Code|last-modified}}: timestamp, formatted as xs:dateTime
 
* {{Code|last-modified}}: timestamp, formatted as xs:dateTime
Line 80: Line 94:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.
+
|{{Error|error|#Errors}} archive creation failed for some other reason.
 
|-
 
|-
 
|'''Examples'''
 
|'''Examples'''
Line 93: Line 107:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
|{{Func|archive:options|$archive as xs:base64Binary|element(archive:options)}}<br />
+
|{{Func|archive:options|$archive as xs:base64Binary|map(*)}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the options of the given archive in the format specified by [[#archive:create|archive:create]].
+
|Returns the options of the specified {{Code|$archive}} in the format specified by [[#archive:create|archive:create]].
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|ARCH0002|#Errors}} The packing format is not supported.<br/>{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.
+
|{{Error|format|#Errors}} The packing format is not supported.<br/>{{Error|error|#Errors}} archive creation failed for some other reason.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
 
|A standard ZIP archive will return the following options:
 
|A standard ZIP archive will return the following options:
<pre class="brush:xml">
+
<pre class="brush:xquery">
<archive:options xmlns:archive="http://basex.org/modules/archive">
+
map {
  <archive:format value="zip"/>
+
  "format": "zip",
   <archive:algorithm value="deflate"/>
+
   "algorithm": "deflate"
</archive:options>
+
}
 
</pre>
 
</pre>
 
|}
 
|}
Line 116: Line 130:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|archive:extract-text|$archive as xs:base64Binary|xs:string*}}<br/>{{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|xs:string*}}<br/>
 
|{{Func|archive:extract-text|$archive as xs:base64Binary|xs:string*}}<br/>{{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|xs:string*}}<br/>
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Extracts archive entries 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 [[#archive:create|archive:create]] (attributes will be ignored).<br/>The encoding of the input files can be specified via {{Code|$encoding}}.
+
|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 [[#archive:create|archive:create]] (attributes will be ignored).<br/>The encoding of the input files can be specified via {{Code|$encoding}}.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|ARCH0004|#Errors}} the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if the <code>[[Options#CHECKSTRINGS|CHECKSTRINGS]]</code> option is turned off.<br />{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.
+
|{{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 for some other reason.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 138: Line 152:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
|{{Func|archive:extract-binary|$archive as xs:base64Binary|xs:string*}}<br/>{{Func|archive:extract-binary|$archive as xs:base64Binary, $entries as item()*|xs:base64Binary*}}
+
|{{Func|archive:extract-binary|$archive as xs:base64Binary|xs:base64Binary*}}<br/>{{Func|archive:extract-binary|$archive as xs:base64Binary, $entries as item()*|xs:base64Binary*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Extracts archive entries 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 [[#archive:create|archive:create]] (attributes will be ignored).
+
|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 [[#archive:create|archive:create]] (attributes will be ignored).
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.
+
|{{Error|error|#Errors}} archive creation failed for some other reason.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 153: Line 167:
 
let $entries  := archive:entries($archive)
 
let $entries  := archive:entries($archive)
 
let $contents := archive:extract-binary($archive)
 
let $contents := archive:extract-binary($archive)
for $entry at $p in $entries
+
return for-each-pair($entries, $contents, function($entry, $content) {
return (
+
   file:create-dir(replace($entry, "[^/]+$", "")),
   file:create-dir(replace($entry, "[^/]*$", "")),
+
   file:write-binary($entry, $content)
   file:write-binary($entry, $contents[$p])
+
})</pre>
)
+
|}
 +
 
 +
==archive:extract-to==
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|archive:extract-to|$path as xs:string, $archive as xs:base64Binary|empty-sequence()}}<br/>{{Func|archive:extract-to|$path as xs:string, $archive as xs:base64Binary, $entries as item()*|empty-sequence()}}
 +
|-
 +
| '''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 [[#archive:create|archive:create]] (attributes will be ignored).
 +
|-
 +
| '''Errors'''
 +
|{{Error|error|#Errors}} archive creation failed for some other reason.
 +
|-
 +
| '''Examples'''
 +
|The following expression unzips all files of an archive to the current directory:
 +
<pre class="brush:xquery">
 +
archive:extract-to('.', file:read-binary('archive.zip'))
 
</pre>
 
</pre>
 
|}
 
|}
Line 165: Line 197:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|archive:update|$archive as xs:base64Binary, $entries as item()*, $contents as item()*|xs:base64Binary}}
 
|{{Func|archive:update|$archive as xs:base64Binary, $entries as item()*, $contents as item()*|xs:base64Binary}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Adds new entries and replaces existing entries in an archive.<br/>The format of {{Code|$entries}} and {{Code|$contents}} is the same as for [[#archive:create|archive:create]].
+
|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 [[#archive:create|archive:create]].
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|ARCH0001|#Errors}} the number of entries and contents differs.<br />{{Error|ARCH0003|#Errors}} entry descriptors contain invalid entry names, timestamps, compression levels or encodings.<br/>{{Error|ARCH0004|#Errors}} the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if the <code>[[Options#CHECKSTRINGS|CHECKSTRINGS]]</code> option is turned off.<br />{{Error|ARCH0005|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.<br />{{Error|FORG0006|XQuery Errors#Function Errors}} (some of) the contents are not of type {{Code|xs:string}} or {{Code|xs:base64Binary}}.
+
|{{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 for some other reason.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 195: Line 227:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|archive:delete|$archive as xs:base64Binary, $entries as item()*|xs:base64Binary}}
 
|{{Func|archive:delete|$archive as xs:base64Binary, $entries as item()*|xs:base64Binary}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Deletes entries from an archive.<br/>The format of {{Code|$entries}} is the same as for [[#archive:create|archive:create]].
+
|Deletes entries from an {{Code|$archive}}.<br/>The format of {{Code|$entries}} is the same as for [[#archive:create|archive:create]].
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|ARCH0005|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.
+
|{{Error|modify|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|error|#Errors}} archive creation failed for some other reason.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 213: Line 245:
 
|}
 
|}
  
==archive:write==
+
=Errors=
  
{{Mark|Added in Version 7.7}}:
+
{| class="wikitable" width="100%"
 
+
! width="110"|Code
{| width='100%'
+
|Description
 
|-
 
|-
| width='90' | '''Signatures'''
+
|{{Code|descriptor}}
|{{Func|archive:write|$path as xs:string, $archive as xs:base64Binary|xs:string*}}<br/>{{Func|archive:write|$path as xs:string, $archive as xs:base64Binary, $entries as item()*|empty-sequence()}}
+
|Entry descriptors contain invalid entry names, timestamps or compression levels.
 
|-
 
|-
| '''Summary'''
+
|{{Code|encode}}
|This convenience function directly writes files of an {{Code|$archive}} to the specified {{Code|$path}}.<br/>The entries to be written can be limited via {{Code|$entries}}. The format of the argument is the same as for [[#archive:create|archive:create]] (attributes will be ignored).
+
|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.
 
|-
 
|-
| '''Errors'''
+
|{{Code|error}}
|{{Error|FILE0001|File Module#Errors}} a specified path does not exist.<br/>{{Error|ARCH9999|#Errors}} archive creation failed for some other reason.
+
|Archive processing failed for some other reason.
|-
 
| '''Examples'''
 
|This example unzips all files of an archive to the current directory:
 
<pre class="brush:xquery">
 
archive:write(file:read-binary('archive.zip'))
 
</pre>
 
|}
 
 
 
=Errors=
 
 
 
{| width='100%' class="wikitable" width="100%"
 
! width="5%"|Code
 
! width="95%"|Description
 
|-
 
|{{Code|ARCH0001}}
 
|The number of specified entries and contents differs.
 
 
|-
 
|-
|{{Code|ARCH0002}}
+
|{{Code|format}}
 
|The packing format or the specified option is invalid or not supported.
 
|The packing format or the specified option is invalid or not supported.
 
|-
 
|-
|{{Code|ARCH0003}}
+
|{{Code|modify}}
|Entry descriptors contain invalid entry names, timestamps or compression levels.
+
|The entries of the given archive cannot be modified.
 
|-
 
|-
|{{Code|ARCH0004}}
+
|{{Code|number}}
|The specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if the <code>[[Options#CHECKSTRINGS|CHECKSTRINGS]]</code> option is turned off.
+
|The number of specified entries and contents differs.
 
|-
 
|-
|{{Code|ARCH0005}}
+
|{{Code|single}}
|The entries of the given archive cannot be modified.
 
|-
 
|{{Code|ARCH0006}}
 
 
|The chosen archive format only allows single entries.
 
|The chosen archive format only allows single entries.
|-
 
|{{Code|ARCH9999}}
 
|Archive processing failed for some other reason.
 
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.0
 +
 +
* Updated: [[#archive:create-from|archive:create-from]]: options added
 +
 +
;Version 9.0
 +
 +
* Updated: error codes updated; errors now use the module namespace
 +
 +
;Version 8.5
 +
 +
* Updated: [[#archive:options|archive:options]]: map returned instead of element
 +
 +
;Version 8.3
 +
 +
* Added: [[#archive:create-from|archive:create-from]], [[#archive:extract-to|archive:extract-to]] (replaces <code>archive:write</code>)
  
 
;Version 7.7
 
;Version 7.7
 +
 
* Added: [[#archive:write|archive:write]]
 
* Added: [[#archive:write|archive:write]]
  
 
The module was introduced with Version 7.3.
 
The module was introduced with Version 7.3.
 
[[Category:XQuery]]
 

Revision as of 09:36, 16 July 2019

This 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 archive:extract-binary function includes an example for writing the contents of an archive to disk.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/archive namespace, which is statically bound to the archive 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 map(*)?) as xs:base64Binary
Summary Creates a new archive from the specified entries and contents.
The $entries argument contains meta information required to create new 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='8'
               encoding='US-ASCII'>hello.txt</archive:entry>

The actual $contents must be xs:string or xs:base64Binary items.
The $options parameter contains archiving options:

  • format: allowed values are zip and gzip. zip is the default.
  • algorithm: allowed values are deflate and stored (for the zip format). deflate is the default.
Errors number: the number of entries and contents differs.
format: the specified option or its value is invalid or not supported.
descriptor: entry descriptors contain invalid entry names, timestamps or compression levels.
encode: the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if CHECKSTRINGS is turned off.
single: the chosen archive format only allows single entries.
error: archive creation failed for some other reason.
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,
  for $file in $files
  return file:read-binary($path || $file)
)
return file:write-binary('mp3.zip', $zip)

archive:create-from

Template:Mark: options added.

Signatures archive:create-from($path as xs:string) as xs:base64Binary
archive:create-from($path as xs:string, $options as map(*)?) as xs:base64Binary
archive:create-from($path as xs:string, $options as map(*)?, $entries as item()*) as xs:base64Binary
Summary This convenience function creates an archive from all files in the specified directory $path.
The $options parameter contains archiving options, and the files to be archived can be limited via $entries. The format of the two last arguments is identical to archive:create, but two additional options are available:
  • recursive: parse all files recursively (default: true; ignored if entries are specified via the last argument).
  • root-dir: use name of supplied directory as archive root directory (default: false).
Errors file:no-dir: the specified path does not point to a directory.
file:is-dir: one of the specified entries points to a directory.
file:not-found: a specified entry does not exist.
error: archive creation failed for some other reason.
Examples This example writes the files of a user’s home directory to archive.zip:
let $zip := archive:create-from('/home/user/')
return file:write-binary('archive.zip', $zip)

archive:entries

Signatures archive:entries($archive as xs:base64Binary) as element(archive:entry)*
Summary Returns the entry descriptors of the specified $archive. A descriptor contains the following attributes, provided that they are available in the archive format:
  • 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 error: 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($archive as xs:base64Binary) as map(*)
Summary Returns the options of the specified $archive in the format specified by archive:create.
Errors format: The packing format is not supported.
error: archive creation failed for some other reason.
Examples A standard ZIP archive will return the following options:
map {
  "format": "zip",
  "algorithm": "deflate"
}

archive:extract-text

Signatures archive:extract-text($archive as xs:base64Binary) as xs:string*
archive:extract-text($archive as xs:base64Binary, $entries as item()*) as xs:string*
archive:extract-text($archive as xs:base64Binary, $entries as item()*, $encoding as xs:string) as xs:string*
Summary Extracts entries of the specified $archive and returns them as texts.
The returned entries can be limited via $entries. The format of the argument is the same as for archive:create (attributes will be ignored).
The encoding of the input files can be specified via $encoding.
Errors encode: the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if CHECKSTRINGS is turned off.
error: 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($archive as xs:base64Binary) as xs:base64Binary*
archive:extract-binary($archive as xs:base64Binary, $entries as item()*) as xs:base64Binary*
Summary Extracts entries of the specified $archive and returns them as binaries.
The returned entries can be limited via $entries. The format of the argument is the same as for archive:create (attributes will be ignored).
Errors error: 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)
return for-each-pair($entries, $contents, function($entry, $content) {
  file:create-dir(replace($entry, "[^/]+$", "")),
  file:write-binary($entry, $content)
})

archive:extract-to

Signatures archive:extract-to($path as xs:string, $archive as xs:base64Binary) as empty-sequence()
archive:extract-to($path as xs:string, $archive as xs:base64Binary, $entries as item()*) as empty-sequence()
Summary This convenience function writes files of an $archive directly to the specified directory $path.
The archive entries to be written can be restricted via $entries. The format of the argument is the same as for archive:create (attributes will be ignored).
Errors error: archive creation failed for some other reason.
Examples The following expression unzips all files of an archive to the current directory:
archive:extract-to('.', file:read-binary('archive.zip'))

archive:update

Signatures archive:update($archive as xs:base64Binary, $entries as item()*, $contents as item()*) as xs:base64Binary
Summary Creates an updated version of the specified $archive with new or replaced entries.
The format of $entries and $contents is the same as for archive:create.
Errors number: the number of entries and contents differs.
descriptor: entry descriptors contain invalid entry names, timestamps, compression levels or encodings.
encode: the specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if CHECKSTRINGS is turned off.
modify: the entries of the given archive cannot be modified.
error: 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(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($archive as xs:base64Binary, $entries as item()*) as xs:base64Binary
Summary Deletes entries from an $archive.
The format of $entries is the same as for archive:create.
Errors modify: the entries of the given archive cannot be modified.
error: 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
descriptor Entry descriptors contain invalid entry names, timestamps or compression levels.
encode The specified encoding is invalid or not supported, or the string conversion failed. Invalid XML characters will be ignored if CHECKSTRINGS is turned off.
error Archive processing failed for some other reason.
format The packing format or the specified option is invalid or not supported.
modify The entries of the given archive cannot be modified.
number The number of specified entries and contents differs.
single The chosen archive format only allows single entries.

Changelog

Version 9.0
Version 9.0
  • Updated: error codes updated; errors now use the module namespace
Version 8.5
Version 8.3
Version 7.7

The module was introduced with Version 7.3.