ZIP Module: Binary Proposal

From Spex: Specifications for XQuery Modules
Jump to: navigation, search

This is a yet another proposal for the ZIP Module that restricts all operations to base64Binary items. The conversion from/to strings, nodes and other XDM types could happen in a pre- or post-processing step, such as e.g. in the following example (which assumes that we have only a basic file:read() function that always returns binary content):

  let $zip := file:read('one.zip')
  let $entry := zip:extract($zip, 'file.txt')
  return convert:to-string($entry, 'UTF-8')

The advantage of this approach is that we don't need two methods for text and binary in each new module. The drawback is that most XML developer may be used to working with text instead of binary data, which is why they may want to avoid explicit conversion code.

Here are the function signatures (including the latest zip:add(), zip:replace() and zip:delete() functions:

module namespace zip = "http://www.expath.org/ns/zip2";
(:~
 : Create a new zip archiving according to the given spec.
 : The contents must be base64Binary items.
 :
 : Example:
 : <!-- overwrite compression level with '0' (uncompressed) -->
 : <entry last-modified="2009-03-20T03:30:32" compression-level="0">
 :   myfile.txt
 : </entry>
 : <entry>
 :   dir/myfile.xml
 : </entry>
 : <entry>
 :   dir/dir2/image.png
 : </entry>
 :
 : @return a base64Binary 
 :
 : @error if the number of entry elements differs from the number
          of specified contents: count($entries) ne count($contents)
 : @error if an encoding is specified and the item is a base64Binary
 :)
declare function zip:create($entries as element(entry)*, $contents as xs:base64Binary()*)
    as xs:base64Binary external;

(:~
 : Returns the specifications of all entries of the given zip archive.
 :
 : Example:
 : <entry size="324" last-modified="2009-03-20T03:30:32" compressed-size="232">
 :   myfile.txt
 : </entry>
 : <entry>
 :   dir/myfile.xml
 : </entry>
 : <entry>
 :   dir/dir2/image.png
 : </entry>
 :
 : @return specification
 :)
declare function zip:entries($zip as xs:base64Binary)
    as element(entry)* external;

(:~
 : Returns all entries from the zip archive
 : as base64Binary.
 :
 : @return base64Binary items
 :
 : @error if the file doesn't exist
 :)
declare function zip:contents($zip as xs:base64Binary)
    as xs:base64Binary* external;

(:~
 : Returns the entries identified by the given path from the zip archive
 : as base64Binary.
 :
 : @return base64Binary items
 :
 : @error if the file doesn't exist
 :)
declare function zip:contents($zip as xs:base64Binary, $path as xs:string*)
    as xs:base64Binary* external;

(:~
 : Adds or replaces entries in a zip archive.
 : The contents must be base64Binary items.
 :
 : @return the updated base64Binary
 :
 : @error if an addressed entry does not exist
 : @error if the number of paths differs from the number
 :        of specified contents: count($paths) ne count($contents)
 :)
declare function zip:update($zip as xs:base64Binary, $paths as xs:string*, $contents as xs:base64Binary()*)
    as xs:base64Binary external;

(:~
 : Deletes entries from a zip archive.
 :
 : @return the updated base64Binary
 :
 : @error if an addressed entry does not exist
 :)
declare function zip:delete($zip as xs:base64Binary, $paths as xs:string*)
    as xs:base64Binary external;
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox