Difference between revisions of "ZIP Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 8: Line 8:
 
|-
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
| valign='top' width='90' | '''Signatures'''
|<code><b>zip:binary-entry</b>($uri as xs:string, $path as xs:string) as xs:base64Binary</code><br />
+
|<code>'''zip:binary-entry'''($uri as xs:string, $path as xs:string) as xs:base64Binary</code>
 
|-
 
|-
 
| valign='top' | '''Summary'''
 
| valign='top' | '''Summary'''
|Extracts the binary file at <code>$path</code> within the ZIP file located at <code>$uri</code> and returns it as an <code>xs:base64Binary</code> item.<br />
+
|Extracts the binary file at <code>$path</code> within the ZIP file located at <code>$uri</code> and returns it as an <code>xs:base64Binary</code> item.
 
|-
 
|-
 
| valign='top' | '''Errors'''
 
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]</b> is raised if the specified path does not exist.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]</b> is raised if the operation fails for some other reason.
+
|'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]''' is raised if the specified path does not exist.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]''' is raised if the operation fails for some other reason.
 
|}
 
|}
  
Line 21: Line 21:
 
|-
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
| valign='top' width='90' | '''Signatures'''
|<code><b>zip:text-entry</b>($uri as xs:string, $path as xs:string) as xs:string</code><br /><code><b>zip:text-entry</b>($uri as xs:string, $path as xs:string, $encoding as xs:string) as xs:string</code>
+
|<code>'''zip:text-entry'''($uri as xs:string, $path as xs:string) as xs:string</code><br /><code>'''zip:text-entry'''($uri as xs:string, $path as xs:string, $encoding as xs:string) as xs:string</code>
 
|-
 
|-
 
| valign='top' | '''Summary'''
 
| valign='top' | '''Summary'''
Line 27: Line 27:
 
|-
 
|-
 
| valign='top' | '''Errors'''
 
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]</b> is raised if the specified path does not exist.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]</b> is raised if the operation fails for some other reason.
+
|'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]''' is raised if the specified path does not exist.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]''' is raised if the operation fails for some other reason.
 
|}
 
|}
  
Line 34: Line 34:
 
|-
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
| valign='top' width='90' | '''Signatures'''
|<code><b>zip:xml-entry</b>($uri as xs:string, $path as xs:string) as document-node()</code><br />
+
|<code>'''zip:xml-entry'''($uri as xs:string, $path as xs:string) as document-node()</code><br />
 
|-
 
|-
 
| valign='top' | '''Summary'''
 
| valign='top' | '''Summary'''
Line 40: Line 40:
 
|-
 
|-
 
| valign='top' | '''Errors'''
 
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#ZIP Functions Errors (FODC)|FODC0006]]</b> is raised if the addressed file is not well-formed.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]</b> is raised if the specified path does not exist.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]</b> is raised if the operation fails for some other reason.
+
|'''[[XQuery Errors#ZIP Functions Errors (FODC)|FODC0006]]''' is raised if the addressed file is not well-formed.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]''' is raised if the specified path does not exist.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]''' is raised if the operation fails for some other reason.
 
|}
 
|}
  
Line 47: Line 47:
 
|-
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
| valign='top' width='90' | '''Signatures'''
|<code><b>zip:html-entry</b>($uri as xs:string, $path as xs:string) as document-node()</code><br />
+
|<code>'''zip:html-entry'''($uri as xs:string, $path as xs:string) as document-node()</code><br />
 
|-
 
|-
 
| valign='top' | '''Summary'''
 
| valign='top' | '''Summary'''
Line 53: Line 53:
 
|-
 
|-
 
| valign='top' | '''Errors'''
 
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#ZIP Functions Errors (FODC)|FODC0006]]</b> is raised if the addressed file is not well-formed, or cannot be converted to correct XML.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]</b> is raised if the specified path does not exist.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]</b> is raised if the operation fails for some other reason.
+
|'''[[XQuery Errors#ZIP Functions Errors (FODC)|FODC0006]]''' is raised if the addressed file is not well-formed, or cannot be converted to correct XML.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]''' is raised if the specified path does not exist.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]''' is raised if the operation fails for some other reason.
 
|}
 
|}
  
Line 60: Line 60:
 
|-
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
| valign='top' width='90' | '''Signatures'''
|<code><b>zip:entries</b>($uri as xs:string) as element(zip:file)</code><br />
+
|<code>'''zip:entries'''($uri as xs:string) as element(zip:file)</code><br />
 
|-
 
|-
 
| valign='top' | '''Summary'''
 
| valign='top' | '''Summary'''
|Generates an [http://expath.org/spec/zip#spec-file-handling-elements-sect XML Representation] of the hierarchical structure of the ZIP file located at <code>$uri</code> and returns it as an element node. The file contents are not returned by this function.
+
|Generates an [http://expath.org/spec/zip#spec-file-handling-elements-sect ZIP XML Representation] of the hierarchical structure of the ZIP file located at <code>$uri</code> and returns it as an element node. The file contents are not returned by this function.
 
|-
 
|-
 
| valign='top' | '''Errors'''
 
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]</b> is raised if the specified path does not exist.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]</b> is raised if the operation fails for some other reason.
+
|'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]''' is raised if the specified path does not exist.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]''' is raised if the operation fails for some other reason.
 
|-
 
|-
 
| valign='top' | '''Examples'''
 
| valign='top' | '''Examples'''
|If the ZIP archive <code>archive.zip</code> is empty, <code>zip:entries('archive.zip')</code> returns <code><zip:file xmlns:zip="http://expath.org/ns/zip" href="archive.zip"/></code>.<br />
+
|
 +
* If the ZIP archive <code>archive.zip</code> is empty, <code>zip:entries('archive.zip')</code> returns <code><zip:file xmlns:zip="http://expath.org/ns/zip" href="archive.zip"/></code>.
 
|}
 
|}
  
Line 76: Line 77:
 
|-
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
| valign='top' width='90' | '''Signatures'''
|<code><b>zip:zip-file</b>($zip as element(zip:file)) as empty-sequence()</code><br />
+
|<code>'''zip:zip-file'''($zip as element(zip:file)) as empty-sequence()</code><br />
 
|-
 
|-
 
| valign='top' | '''Summary'''
 
| valign='top' | '''Summary'''
|Creates a new ZIP archive with the characteristics described by <code>$zip</code>, the [http://expath.org/spec/zip#spec-file-handling-elements-sect XML Representation].
+
|Creates a new ZIP archive with the characteristics described by <code>$zip</code>, the [http://expath.org/spec/zip#spec-file-handling-elements-sect ZIP XML Representation].
 
|-
 
|-
 
| valign='top' | '''Errors'''
 
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]</b> is raised if an addressed file does not exist.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0002]]</b> is raised if entries in the ZIP archive description are unknown, missing, or invalid.</b><br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]</b> is raised if the operation fails for some other reason.<br /><b>[[XQuery Errors#Serialization Errors (SEPM, SERE, SESU)|Serialization Errors]]</b> are raised if an inlined XML fragment cannot be successfully serialized.
+
|'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]''' is raised if an addressed file does not exist.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0002]]''' is raised if entries in the ZIP archive description are unknown, missing, or invalid.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]''' is raised if the operation fails for some other reason.<br />'''[[XQuery Errors#Serialization Errors (SEPM, SERE, SESU)|Serialization Errors]]''' are raised if an inlined XML fragment cannot be successfully serialized.
 
|-
 
|-
 
| valign='top' | '''Examples'''
 
| valign='top' | '''Examples'''
|The following function creates a file <code>archive.zip</code> with the file <code>file.txt</code> inside:<br /><code>zip:zip-file(<file xmlns="http://expath.org/ns/zip" href="archive.zip"><entry src="file.txt"/></file>)</code><br/>The following function creates a file <code>archive.zip</code>. It contains one file <code>readme</code> with the content "<code>thanks</code>":<br /><code>zip:zip-file(<file xmlns="http://expath.org/ns/zip" href="archive.zip"><entry name="readme">thanks</entry></file>)</code>
+
|
 +
* The following function creates a file <code>archive.zip</code> with the file <code>file.txt</code> inside:
 +
<pre class="brush:xquery">
 +
zip:zip-file(
 +
  <file xmlns="http://expath.org/ns/zip" href="archive.zip">
 +
    <entry src="file.txt"/>
 +
  </file>)
 +
</pre>
 +
* The following function creates a file <code>archive.zip</code>. It contains one file <code>readme</code> with the content "<code>thanks</code>":
 +
<pre class="brush:xquery">
 +
zip:zip-file(
 +
  <file xmlns="http://expath.org/ns/zip" href="archive.zip">
 +
    <entry name="readme">thanks</entry>
 +
  </file>)
 +
</pre>
 
|}
 
|}
  
Line 92: Line 107:
 
|-
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
| valign='top' width='90' | '''Signatures'''
|<code><b>zip:update-entries</b>($zip as element(zip:file), $output as xs:string) as empty-sequence()</code><br />
+
|<code>'''zip:update-entries'''($zip as element(zip:file), $output as xs:string) as empty-sequence()</code><br />
 
|-
 
|-
 
| valign='top' | '''Summary'''
 
| valign='top' | '''Summary'''
|Updates an existing ZIP archive or creates a modifed copy, based on the characteristics described by <code>$zip</code>, the [http://expath.org/spec/zip#spec-file-handling-elements-sect XML Representation]. The <code>$output</code> argument is the URI where the modified ZIP file is copied to.
+
|Updates an existing ZIP archive or creates a modifed copy, based on the characteristics described by <code>$zip</code>, the [http://expath.org/spec/zip#spec-file-handling-elements-sect ZIP XML Representation]. The <code>$output</code> argument is the URI where the modified ZIP file is copied to.
 
|-
 
|-
 
| valign='top' | '''Errors'''
 
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]</b> is raised if an addressed file does not exist.<br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0002]]</b> is raised if entries in the ZIP archive description are unknown, missing, or invalid.</b><br /><b>[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]</b> is raised if the operation fails for some other reason.<br /><b>[[XQuery Errors#Serialization Errors (SEPM, SERE, SESU)|Serialization Errors]]</b> are raised if an inlined XML fragment cannot be successfully serialized.
+
|'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0001]]''' is raised if an addressed file does not exist.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0002]]''' is raised if entries in the ZIP archive description are unknown, missing, or invalid.<br />'''[[XQuery Errors#ZIP Functions Errors (FOZP)|FOZP0003]]''' is raised if the operation fails for some other reason.<br />'''[[XQuery Errors#Serialization Errors (SEPM, SERE, SESU)|Serialization Errors]]''' are raised if an inlined XML fragment cannot be successfully serialized.
 
|-
 
|-
 
| valign='top' | '''Examples'''
 
| valign='top' | '''Examples'''
|The following function creates a copy <code>new.zip</code> of the existing <code>archive.zip</code> file:<br /><code>zip:update-entries(zip:entries('archive.zip'), 'new.zip')</code><br />The following function deletes all PNG files from <code>archive.zip</code>:<br /><code>declare namespace zip = "<nowiki>http://expath.org/ns/zip</nowiki>";<br/>copy $doc := zip:entries('archive.zip')<br/>modify delete node $doc//zip:entry[ends-with(lower-case(@name), '.png')]<br/>return zip:update-entries($doc, 'archive.zip')</code>
+
|
 +
* The following function creates a copy <code>new.zip</code> of the existing <code>archive.zip</code> file:
 +
<pre class="brush:xquery">
 +
zip:update-entries(zip:entries('archive.zip'), 'new.zip')
 +
</pre>
 +
* The following function deletes all PNG files from <code>archive.zip</code>:
 +
<pre class="brush:xquery">
 +
declare namespace zip = "<nowiki>http://expath.org/ns/zip</nowiki>";
 +
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')
 +
</pre>
 
|}
 
|}
  
 
[[Category:XQuery]]
 
[[Category:XQuery]]

Revision as of 15:34, 23 April 2011

This module contains XQuery Functions to handle ZIP archives. The contents of ZIP files can be extracted and listed, and new archives can be created. All functions are preceded by the zip: prefix, which is linked to the http://expath.org/ns/zip namespace. The module is based on the EXPath ZIP Module.

Example

zip:binary-entry

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 FOZP0001 is raised if the specified path does not exist.
FOZP0003 is raised if the operation fails for some other reason.

zip:text-entry

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 FOZP0001 is raised if the specified path does not exist.
FOZP0003 is raised if the operation fails for some other reason.

zip:xml-entry

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 FODC0006 is raised if the addressed file is not well-formed.
FOZP0001 is raised if the specified path does not exist.
FOZP0003 is raised if the operation fails for some other reason.

zip:html-entry

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 FODC0006 is raised if the addressed file is not well-formed, or cannot be converted to correct XML.
FOZP0001 is raised if the specified path does not exist.
FOZP0003 is raised if the operation fails for some other reason.

zip:entries

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 FOZP0001 is raised if the specified path does not exist.
FOZP0003 is raised if 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

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 FOZP0001 is raised if an addressed file does not exist.
FOZP0002 is raised if entries in the ZIP archive description are unknown, missing, or invalid.
FOZP0003 is raised if the operation fails for some other reason.
Serialization Errors are raised if an inlined XML fragment cannot be successfully serialized.
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

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 FOZP0001 is raised if an addressed file does not exist.
FOZP0002 is raised if entries in the ZIP archive description are unknown, missing, or invalid.
FOZP0003 is raised if the operation fails for some other reason.
Serialization Errors are raised if an inlined XML fragment cannot be successfully serialized.
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')