Difference between revisions of "ZIP Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "{|" to "{| width='100%'")
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This [[Module Library|XQuery Module]] contains functions to handle ZIP archives. The contents of ZIP files can be extracted and listed, and new archives can be created. The module is based on the [http://expath.org/spec/zip EXPath ZIP Module]. It may soon be replaced by the [[Archive Module]].
+
This [[Module Library|XQuery Module]] contains functions to handle ZIP archives. The contents of ZIP files can be extracted and listed, and new archives can be created. The module is based on the [http://expath.org/spec/zip EXPath ZIP Module]. Please note that the ZIP module is not being actively maintained but is still distributed for compatibility with older applications. We recommend you use the [[Archive Module]] wherever possible.
  
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the {{Code|http://expath.org/ns/zip}} namespace, which is statically bound to the {{Code|zip}} prefix.<br/>
+
All functions in this module are assigned to the <code><nowiki>http://expath.org/ns/zip</nowiki></code> namespace, which is statically bound to the {{Code|zip}} prefix.<br/>
All errors are assigned to the {{Code|http://expath.org/ns/error}} namespace, which is statically bound to the {{Code|exerr}} prefix.
+
All errors are assigned to the <code><nowiki>http://expath.org/ns/error</nowiki></code> namespace, which is statically bound to the {{Code|experr}} prefix.
  
 
=Functions=
 
=Functions=
Line 11: Line 11:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|zip:binary-entry|$uri as xs:string, $path as xs:string|xs:base64Binary}}
 
|{{Func|zip:binary-entry|$uri as xs:string, $path as xs:string|xs:base64Binary}}
 
|-
 
|-
Line 24: Line 24:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|zip:text-entry|$uri as xs:string, $path as xs:string|xs:string}}<br />{{Func|zip:text-entry|$uri as xs:string, $path as xs:string, $encoding as xs:string|xs:string}}
 
|{{Func|zip:text-entry|$uri as xs:string, $path as xs:string|xs:string}}<br />{{Func|zip:text-entry|$uri as xs:string, $path as xs:string, $encoding as xs:string|xs:string}}
 
|-
 
|-
Line 37: Line 37:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|zip:xml-entry|$uri as xs:string, $path as xs:string|document-node()}}<br />
 
|{{Func|zip:xml-entry|$uri as xs:string, $path as xs:string|document-node()}}<br />
 
|-
 
|-
Line 44: Line 44:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FODC0006|XQuery Errors#Functions Errors}} the addressed file is not well-formed.<br />{{Error|ZIP0001|#Errors}} the specified path does not exist.<br />{{Error|ZIP0003|#Errors}} the operation fails for some other reason.
+
|{{Error|ZIP0001|#Errors}} the specified path does not exist.<br />{{Error|ZIP0003|#Errors}} the operation fails for some other reason.
 
|}
 
|}
  
Line 50: Line 50:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|zip:html-entry|$uri as xs:string, $path as xs:string|document-node()}}<br />
 
|{{Func|zip:html-entry|$uri as xs:string, $path as xs:string|document-node()}}<br />
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Extracts the HTML file at {{Code|$path}} within the ZIP file located at {{Code|$uri}} and returns it as a document node. The file is converted to XML first if [http://home.ccil.org/~cowan/XML/tagsoup/ Tagsoup] is found in the classpath.
+
|Extracts the HTML file at {{Code|$path}} within the ZIP file located at {{Code|$uri}} and returns it as a document node. The file is converted to XML first if [[Parsers#HTML_Parser|Tagsoup]] is found in the classpath.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FODC0006|XQuery Errors#Functions Errors}} the addressed file is not well-formed, or cannot be converted to correct XML.<br />{{Error|ZIP0001|#Errors}} the specified path does not exist.<br />{{Error|ZIP0003|#Errors}} the operation fails for some other reason.
+
|{{Error|ZIP0001|#Errors}} the specified path does not exist.<br />{{Error|ZIP0003|#Errors}} the operation fails for some other reason.
 
|}
 
|}
  
Line 63: Line 63:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|zip:entries|$uri as xs:string|element(zip:file)}}<br />
 
|{{Func|zip:entries|$uri as xs:string|element(zip:file)}}<br />
 
|-
 
|-
Line 73: Line 73:
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
|If the ZIP archive {{Code|archive.zip}} is empty, {{Code|zip:entries('archive.zip')}} returns:<br/><pre class="brush:xml"><zip:file xmlns:zip="http://expath.org/ns/zip" href="archive.zip"/></pre>
+
|If the ZIP archive {{Code|archive.zip}} is empty, {{Code|zip:entries('archive.zip')}} returns:
 +
<syntaxhighlight lang="xml">
 +
<zip:file xmlns:zip="http://expath.org/ns/zip" href="archive.zip"/>
 +
</syntaxhighlight>
 
|}
 
|}
  
Line 79: Line 82:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|zip:zip-file|$zip as element(zip:file)|empty-sequence()}}<br />
 
|{{Func|zip:zip-file|$zip as element(zip:file)|empty-sequence()}}<br />
 
|-
 
|-
Line 86: Line 89:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|ZIP0001|#Errors}} an addressed file does not exist.<br />{{Error|ZIP0002|#Errors}} entries in the ZIP archive description are unknown, missing, or invalid.<br />{{Error|ZIP0003|#Errors}} the operation fails for some other reason.<br />{{Error|Serialization Errors|XQuery Errors#Serialization Errors}} an inlined XML fragment cannot be successfully serialized.
+
|{{Error|ZIP0001|#Errors}} an addressed file does not exist.<br />{{Error|ZIP0002|#Errors}} entries in the ZIP archive description are unknown, missing, or invalid.<br />{{Error|ZIP0003|#Errors}} the operation fails for some other reason.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
 
|The following function creates a file {{Code|archive.zip}} with the file {{Code|file.txt}} inside:
 
|The following function creates a file {{Code|archive.zip}} with the file {{Code|file.txt}} inside:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
zip:zip-file(
 
zip:zip-file(
 
   <file xmlns="http://expath.org/ns/zip" href="archive.zip">
 
   <file xmlns="http://expath.org/ns/zip" href="archive.zip">
 
     <entry src="file.txt"/>
 
     <entry src="file.txt"/>
 
   </file>)
 
   </file>)
</pre>
+
</syntaxhighlight>
 
The following function creates a file {{Code|archive.zip}}. It contains one file {{Code|readme}} with the content "{{Code|thanks}}":
 
The following function creates a file {{Code|archive.zip}}. It contains one file {{Code|readme}} with the content "{{Code|thanks}}":
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
zip:zip-file(
 
zip:zip-file(
 
   <file xmlns="http://expath.org/ns/zip" href="archive.zip">
 
   <file xmlns="http://expath.org/ns/zip" href="archive.zip">
 
     <entry name="readme">thanks</entry>
 
     <entry name="readme">thanks</entry>
 
   </file>)
 
   </file>)
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 108: Line 111:
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Func|zip:update-entries|$zip as element(zip:file), $output as xs:string|empty-sequence()}}<br />
 
|{{Func|zip:update-entries|$zip as element(zip:file), $output as xs:string|empty-sequence()}}<br />
 
|-
 
|-
Line 115: Line 118:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|ZIP0001|#Errors}} an addressed file does not exist.<br />{{Error|ZIP0002|#Errors}} entries in the ZIP archive description are unknown, missing, or invalid.<br />{{Error|ZIP0003|#Errors}} the operation fails for some other reason.<br />{{Error|Serialization Errors|XQuery Errors#Serialization Errors}} an inlined XML fragment cannot be successfully serialized.
+
|{{Error|ZIP0001|#Errors}} an addressed file does not exist.<br />{{Error|ZIP0002|#Errors}} entries in the ZIP archive description are unknown, missing, or invalid.<br />{{Error|ZIP0003|#Errors}} the operation fails for some other reason.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
 
|The following function creates a copy {{Code|new.zip}} of the existing {{Code|archive.zip}} file:
 
|The following function creates a copy {{Code|new.zip}} of the existing {{Code|archive.zip}} file:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
zip:update-entries(zip:entries('archive.zip'), 'new.zip')
 
zip:update-entries(zip:entries('archive.zip'), 'new.zip')
</pre>
+
</syntaxhighlight>
 
The following function deletes all PNG files from {{Code|archive.zip}}:
 
The following function deletes all PNG files from {{Code|archive.zip}}:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
declare namespace zip = "http://expath.org/ns/zip";
 
declare namespace zip = "http://expath.org/ns/zip";
 
copy $doc := zip:entries('archive.zip')
 
copy $doc := zip:entries('archive.zip')
 
modify delete node $doc//zip:entry[ends-with(lower-case(@name), '.png')]
 
modify delete node $doc//zip:entry[ends-with(lower-case(@name), '.png')]
 
return zip:update-entries($doc, 'archive.zip')
 
return zip:update-entries($doc, 'archive.zip')
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
 
=Errors=
 
=Errors=
  
{| width='100%' class="wikitable" width="100%"
+
{| class="wikitable" width="100%"
! width="5%"|Code
+
! width="110"|Code
! width="95%"|Description
+
|Description
 
|-
 
|-
 
|{{Code|ZIP0001}}
 
|{{Code|ZIP0001}}
Line 146: Line 149:
 
|An operation fails for some other reason.
 
|An operation fails for some other reason.
 
|}
 
|}
 
[[Category:XQuery]]
 

Latest revision as of 14:16, 27 February 2020

This XQuery Module contains functions to handle ZIP archives. The contents of ZIP files can be extracted and listed, and new archives can be created. The module is based on the EXPath ZIP Module. Please note that the ZIP module is not being actively maintained but is still distributed for compatibility with older applications. We recommend you use the Archive Module wherever possible.

Conventions[edit]

All functions in this module are assigned to the http://expath.org/ns/zip namespace, which is statically bound to the zip prefix.
All errors are assigned to the http://expath.org/ns/error namespace, which is statically bound to the experr prefix.

Functions[edit]

zip:binary-entry[edit]

Signatures zip:binary-entry($uri as xs:string, $path as xs:string) as xs:base64Binary
Summary Extracts the binary file at $path within the ZIP file located at $uri and returns it as an xs:base64Binary item.
Errors ZIP0001: the specified path does not exist.
ZIP0003: the operation fails for some other reason.

zip:text-entry[edit]

Signatures zip:text-entry($uri as xs:string, $path as xs:string) as xs:string
zip:text-entry($uri as xs:string, $path as xs:string, $encoding as xs:string) as xs:string
Summary Extracts the text file at $path within the ZIP file located at $uri and returns it as an xs:string item.
An optional encoding can be specified via $encoding.
Errors ZIP0001: the specified path does not exist.
ZIP0003: the operation fails for some other reason.

zip:xml-entry[edit]

Signatures zip:xml-entry($uri as xs:string, $path as xs:string) as document-node()
Summary Extracts the XML file at $path within the ZIP file located at $uri and returns it as a document node.
Errors ZIP0001: the specified path does not exist.
ZIP0003: the operation fails for some other reason.

zip:html-entry[edit]

Signatures zip:html-entry($uri as xs:string, $path as xs:string) as document-node()
Summary Extracts the HTML file at $path within the ZIP file located at $uri and returns it as a document node. The file is converted to XML first if Tagsoup is found in the classpath.
Errors ZIP0001: the specified path does not exist.
ZIP0003: the operation fails for some other reason.

zip:entries[edit]

Signatures zip:entries($uri as xs:string) as element(zip:file)
Summary Generates an ZIP XML Representation of the hierarchical structure of the ZIP file located at $uri and returns it as an element node. The file contents are not returned by this function.
Errors ZIP0001: the specified path does not exist.
ZIP0003: the operation fails for some other reason.
Examples If the ZIP archive archive.zip is empty, zip:entries('archive.zip') returns:
<zip:file xmlns:zip="http://expath.org/ns/zip" href="archive.zip"/>

zip:zip-file[edit]

Signatures zip:zip-file($zip as element(zip:file)) as empty-sequence()
Summary Creates a new ZIP archive with the characteristics described by $zip, the ZIP XML Representation.
Errors ZIP0001: an addressed file does not exist.
ZIP0002: entries in the ZIP archive description are unknown, missing, or invalid.
ZIP0003: the operation fails for some other reason.
Examples The following function creates a file archive.zip with the file file.txt inside:
zip:zip-file(
  <file xmlns="http://expath.org/ns/zip" href="archive.zip">
    <entry src="file.txt"/>
  </file>)

The following function creates a file archive.zip. It contains one file readme with the content "thanks":

zip:zip-file(
  <file xmlns="http://expath.org/ns/zip" href="archive.zip">
    <entry name="readme">thanks</entry>
  </file>)

zip:update-entries[edit]

Signatures zip:update-entries($zip as element(zip:file), $output as xs:string) as empty-sequence()
Summary Updates an existing ZIP archive or creates a modifed copy, based on the characteristics described by $zip, the ZIP XML Representation. The $output argument is the URI where the modified ZIP file is copied to.
Errors ZIP0001: an addressed file does not exist.
ZIP0002: entries in the ZIP archive description are unknown, missing, or invalid.
ZIP0003: the operation fails for some other reason.
Examples The following function creates a copy new.zip of the existing archive.zip file:
zip:update-entries(zip:entries('archive.zip'), 'new.zip')

The following function deletes all PNG files from archive.zip:

declare namespace zip = "http://expath.org/ns/zip";
copy $doc := zip:entries('archive.zip')
modify delete node $doc//zip:entry[ends-with(lower-case(@name), '.png')]
return zip:update-entries($doc, 'archive.zip')

Errors[edit]

Code Description
ZIP0001 A specified path does not exist.
ZIP0002 Entries in the ZIP archive description are unknown, missing, or invalid.
ZIP0003 An operation fails for some other reason.