Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
;Version 9.0
;Version 7.7
* Added: [[#archive:write|archive:write]]
no edit summary
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/>
=FunctionsContent Handling= ==archive:create== {| width='100%'|-| 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 map(*)?|xs:base64Binary}}<br />|-| '''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|last-modified}}: timestamp, specified as xs:dateTime (default: current time)* {{Code|compression-level}}: 0-9, 0 = uncompressed (default: 8)* {{Code|encoding}}: for textual entries (default: UTF-8)An example:<syntaxhighlight lang="xml"><archive:entry last-modified='2011-11-11T11:11:11' compression-level='8' encoding='US-ASCII'>hello.txt</archive:entry></syntaxhighlight>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.|-| '''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 for some other reason.|-| '''Examples'''|The following one-liner creates an archive {{Code|archive.zip}} with one file {{Code|file.txt}}:<syntaxhighlight lang="xquery">archive:create(<archive:entry>file.txt</archive:entry>, 'Hello World')</syntaxhighlight>The following function creates an archive {{Code|mp3.zip}}, which contains all MP3 files of a local directory:<syntaxhighlight lang="xquery">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)</syntaxhighlight>|} ==archive:create-from== {| 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>:<syntaxhighlight lang="xquery">let $zip := archive:create-from('/home/user/')return file:write-binary('archive.zip', $zip)</syntaxhighlight>|}
==archive:entries==
|-
| '''Errors'''
|{{Error|error|#Errors}} archive creation failed for some other reason.
|-
|'''Examples'''
|-
| '''Errors'''
|{{Error|format|#Errors}} The archive format is not supported.<br/>{{Error|error|#Errors}} archive creation failed for some other reason.
|-
| '''Examples'''
|-
| '''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 for some other reason.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|error|#Errors}} archive creation failed for some other reason.
|-
| '''Examples'''
|}
=Updates= ==archive:extract-tocreate==
{| width='100%'
|-
| width='120' | '''Signatures'''|{{Func|archive:extract-tocreate|$path entries as xs:stringitem(), $archive contents as item()*|xs:base64Binary|empty-sequence()}}<br/>{{Func|archive:extract-tocreate|$path entries as xs:stringitem(), $archive contents as xs:base64Binaryitem()*, $entries options as itemmap(*)*?|empty-sequence()xs:base64Binary}}<br />
|-
| '''Summary'''
|This convenience function writes files 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 an type {{Code|xs:string}}, representing the entry name, or {{Code|$element(archive:entry)}} directly to , containing the name as text node and additional, optional attributes:* {{Code|last-modified}}: timestamp, specified directory as xs:dateTime (default: current time)* {{Code|compression-level}}: 0-9, 0 = uncompressed (default: 8)* {{Code|encoding}}: for textual entries (default: UTF-8)An example:<syntaxhighlight lang="xml"><archive:entry last-modified='2011-11-11T11:11:11' compression-level='8' encoding='US-ASCII'>hello.txt</archive:entry></syntaxhighlight>The actual {{Code|$pathcontents}}must be {{Code|xs:string}} or {{Code|xs:base64Binary}} items.<br/>The archive entries to be written can be restricted via {{Code|$entriesoptions}} parameter contains archiving options:* {{Code|format}}: allowed values are {{Code|zip}} and {{Code|gzip}}. The format of the argument {{Code|zip}} is the same as for [[#archivedefault.* {{Code|algorithm}}:createallowed values are {{Code|deflate}} and {{Code|archive:create]] stored}} (attributes will be ignoredfor the {{Code|zip}} format). {{Code|deflate}} is the default.
|-
| '''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 for some other reason.
|-
| '''Examples'''
|The following expression unzips all files of one-liner creates an archive to the current directory{{Code|archive.zip}} with one file {{Code|file.txt}}:
<syntaxhighlight lang="xquery">
archive:extract-tocreate('<archive:entry>file.'txt</archive:entry>, file:read-binary('archive.zipHello World'))
</syntaxhighlight>
The following function creates an archive {{Code|mp3.zip}}, which contains all MP3 files of a local directory:
<syntaxhighlight lang="xquery">
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)</syntaxhighlight>
|}
|-
| '''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 for some other reason.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|modify|#Errors}} the entries of the given archive cannot be modified.<br/>{{Error|error|#Errors}} archive creation failed for some other reason.
|-
| '''Examples'''
let $entries := archive:entries($zip)[matches(., '\.x?html?$', 'i')]
return file:write-binary('new.zip', archive:delete($zip, $entries))
</syntaxhighlight>
|}
=Convenience Functions=
==archive:create-from==
{| 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.
|-
| '''Examples'''
|This example writes the files of a user’s home directory to <code>archive.zip</code>:
<syntaxhighlight lang="xquery">
let $zip := archive:create-from('/home/user/')
return file:write-binary('archive.zip', $zip)
</syntaxhighlight>
|}
==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.
|-
| '''Examples'''
|The following expression unzips all files of an archive to the current directory:
<syntaxhighlight lang="xquery">
archive:extract-to('.', file:read-binary('archive.zip'))
</syntaxhighlight>
|}
==archive:write==
{{Mark|Introduced with BaseX 9.6}}
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|archive:write|$path as xs:string, $entries as item(), $contents as item()*|xs:base64Binary}}<br />{{Func|archive:write|$path as xs:string, $entries as item(), $contents as item()*, $options as map(*)?|xs:base64Binary}}<br />
|-
| '''Summary'''
|Creates a new archive from the specified {{Code|$entries}} and {{Code|$contents}} and writes it disk.<br/> See {{Function||archive:create}} for more details.
|-
| '''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.
|-
| '''Examples'''
|All mp3 files from a directory are zipped and written to a file:
<syntaxhighlight lang="xquery">
let $files := file:children('music')[ends-with(., 'mp3')]
return archive:write(
'music.zip',
$files ! file:name(.),
$files ! file:read-binary(.)
)
</syntaxhighlight>
|}
|-
|{{Code|error}}
|Archive processing failed for some other reason.
|-
|{{Code|format}}
=Changelog=
;Version 9.6
* Added: [[#archive:write|archive:write]]
;Version 9.0
* Updated: [[#archive:create-from|archive:create-from]]: options added
* 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>)
The module was introduced with Version 7.3.
