Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Added in Version 7.7}}: {| class="wikitable" width='"100%'"! width="110"|Code|Description
| width='90' | '''Signatures'''|{{FuncCode|archive:write|$path as xs:string, $archive as xs:base64Binary|xs:string*descriptor}}<br/>{{Func|archive:write|$path as xs:stringEntry descriptors contain invalid entry names, $archive as xs:base64Binary, $entries as item()*|empty-sequence()}}timestamps or compression levels.
| '''Errors'''|{{Error|FILE0001Code|File Module#Errorserror}} a specified path does not exist.<br/>{{Error|ARCH9999|#Errors}} archive creation 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|ARCH9999}}
|Archive processing failed for some other reason.
[[Category:XQuery]]
→archive:create
=Conventions=
All functions and errors in this module are assigned to the {{Code|<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=
==archive:create==
{| width='100%'
|-
| width='90120' | '''Signatures''' |{{Func|archive:create|$entries as item(), $contents as item()*|xs:base64Binary}}<br />{{Func|archive:create|$entries as item(), $contents as item()*, $options as itemmap(*)?|xs:base64Binary}}<br />
|-
| '''Summary'''
</pre>
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:* as children of an {{Code|<archive:options/>format}} element:<pre class="brush:xml"><archive:options> <archive:format value="allowed values are {{Code|zip"/> <archive:algorithm value="deflate"/></archive:options></pre>* as map, which contains all key/value pairs:<pre class="brush:xml">map }} and {{ "format" := "zip", "algorithm" := "deflate" Code|gzip}}</pre>Currently, the following combinations are supported (all others will be rejected):* . {{Code|zip}}: is the default.* {{Code|algorithm}} may be : allowed values are {{Code|storeddeflate}} or and {{Code|deflatestored}}* (for the {{Code|gzipzip}}: algorithm may be format). {{Code|deflate}}is the default.
|-
| '''Errors'''
|{{Error|ARCH0001number|#Errors}} the number of entries and contents differs.<br />{{Error|ARCH0002format|#Errors}} the specified option or its value is invalid or not supported.<br />{{Error|ARCH0003descriptor|#Errors}} entry descriptors contain invalid entry names, timestamps or compression levels.<br/>{{Error|ARCH0004encode|#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{{Option|CHECKSTRINGS]]</code> option }} is turned off.<br/>{{Error|ARCH0005single|#Errors}} the chosen archive format only allows single entries.<br />{{Error|ARCH9999error|#Errors}} archive creation failed for some other reason.<br />{{Error|FORG0006|XQuery Errors#Function Errors}} an argument has a wrong type.
|-
| '''Examples'''
let $path := 'audio/'
let $files := file:list($path, true(), '*.mp3')
let $zip := archive:create( $files ! element archive:entry { . }, for $file in $files ! return file:read-binary($path || .$file))
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>
|}
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|archive:entries|$archive as xs:base64Binary|element(archive:entry)*}}<br />
|-
| '''Summary'''
|Returns the entry descriptors of the given specified {{Code|$archive}}. A descriptor contains the following attributes, provided that they are available in the archive format:
* {{Code|size}}: original file size
* {{Code|last-modified}}: timestamp, formatted as xs:dateTime
|-
| '''Errors'''
|{{Error|ARCH9999error|#Errors}} archive creation failed for some other reason.
|-
|'''Examples'''
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|archive:options|$archive as xs:base64Binary|elementmap(archive:options*)}}<br />
|-
| '''Summary'''
|Returns the options of the given specified {{Code|$archive }} in the format specified by [[#archive:create|archive:create]].
|-
| '''Errors'''
|{{Error|ARCH0002format|#Errors}} The packing format is not supported.<br/>{{Error|ARCH9999error|#Errors}} archive creation failed for some other reason.
|-
| '''Examples'''
|A standard ZIP archive will return the following options:
<pre class="brush:xmlxquery"><archive:options xmlns:archive=map { "http://basex.org/modules/archiveformat"> <archive:format value="zip"/>, <archive"algorithm":algorithm value="deflate"/></archive:options>}
</pre>
|}
{| width='100%'
|-
| width='90120' | '''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/>
|-
| '''Summary'''
|Extracts entries of the specified {{Code|$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}}.
|-
| '''Errors'''
|{{Error|ARCH0004encode|#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{{Option|CHECKSTRINGS]]</code> option }} is turned off.<br />{{Error|ARCH9999error|#Errors}} archive creation failed for some other reason.
|-
| '''Examples'''
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|archive:extract-binary|$archive as xs:base64Binary|xs:stringbase64Binary*}}<br/>{{Func|archive:extract-binary|$archive as xs:base64Binary, $entries as item()*|xs:base64Binary*}}
|-
| '''Summary'''
|Extracts entries of the specified {{Code|$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).
|-
| '''Errors'''
|{{Error|ARCH9999error|#Errors}} archive creation failed for some other reason.
|-
| '''Examples'''
let $entries := archive:entries($archive)
let $contents := archive:extract-binary($archive)
return for -each-pair($entries, $contents, function($entry at , $p in $entriesreturn (content) { file:create-dir(replace($entry, "[^/]*+$", "")), file:write-binary($entry, $contentscontent)})</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 [[$p#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>
|}
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|archive:update|$archive as xs:base64Binary, $entries as item()*, $contents as item()*|xs:base64Binary}}
|-
| '''Summary'''
|Adds Creates an updated version of the specified {{Code|$archive}} with new or replaced 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]].
|-
| '''Errors'''
|{{Error|ARCH0001number|#Errors}} the number of entries and contents differs.<br />{{Error|ARCH0003descriptor|#Errors}} entry descriptors contain invalid entry names, timestamps, compression levels or encodings.<br/>{{Error|ARCH0004encode|#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{{Option|CHECKSTRINGS]]</code> option }} is turned off.<br />{{Error|ARCH0005modify|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|ARCH9999error|#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}}.
|-
| '''Examples'''
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|archive:delete|$archive as xs:base64Binary, $entries as item()*|xs:base64Binary}}
|-
| '''Summary'''
|Deletes entries from an {{Code|$archive}}.<br/>The format of {{Code|$entries}} is the same as for [[#archive:create|archive:create]].
|-
| '''Errors'''
|{{Error|ARCH0005modify|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|ARCH9999error|#Errors}} archive creation failed for some other reason.
|-
| '''Examples'''
|}
==archive:write=Errors=
|-
|-
| '''Summary'''|This convenience function directly writes files of an {{Code|$archiveencode}} to |The specified encoding is invalid or not supported, or the specified {{Code|$path}}string conversion failed.<br/>The entries to Invalid XML characters will be written can be limited via ignored if {{CodeOption|$entriesCHECKSTRINGS}}. The format of the argument is the same as for [[#archive:create|archive:create]] (attributes will be ignored)turned off.
|-
|-
|{{Code|ARCH0002format}}
|The packing format or the specified option is invalid or not supported.
|-
|{{Code|ARCH0003modify}}|Entry descriptors contain invalid entry names, timestamps or compression levelsThe entries of the given archive cannot be modified.
|-
|{{Code|ARCH0004number}}|The number of 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 offentries and contents differs.
|-
|{{Code|ARCH0005}}|The entries of the given archive cannot be modified.|-|{{Code|ARCH0006single}}
|The chosen archive format only allows single entries.
|}
=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
* Added: [[#archive:write|archive:write]]
The module was introduced with Version 7.3.
