ZIP Module: Second Proposal

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

This is a slightly updated proposal for the ZIP Module. The major changes are as follows:

  1. zip:update function added
  2. "Parts" renamed to "Entries", function names shortened
  3. Entries: "encoding" attribute added
  4. Entries: "compression-level" and "uncompressed" attributes merged
  5. Options reduced to a single "$encoding" argument

These are all suggestions; feedback is welcome.

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

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

(:~
 : Return the entry identified by the given path from the zip archive
 : as a string.
 : The default encoding used to read the string is UTF-8.
 :
 : @return a string
 :
 : @error if the file contains invalid utf-8 characters
 : @error if the file doesn't exist
 :)
declare function zip:extract-text($zip as xs:base64Binary, $path as xs:string)
    as xs:string external;

(:~
 : Return the entry identified by the given path from the zip archive
 : as a string.
 :
 : @return a string
 :
 : @error if the file contains invalid characters
 : @error if a transcoding error happens
 :)
declare function zip:extract-text($zip as xs:base64Binary, $path as xs:string, $encoding as xs:string)
    as xs:string external;

(:~
 : Return the entry identified by the given path from the zip archive
 : as a base64Binary.
 :
 : @return a base64Binary
 :
 : @error if the file doesn't exist
 :)
declare function zip:extract-binary($zip as xs:base64Binary, $path as xs:string)
    as xs:base64Binary external;

(:~
 : Add, update and delete entries in a zip archive according to
 : the given spec. The contents can be string and base64Binary items.
 : If a specification entry has a delete attribute with its value set
 : to "true", this entry will be removed.
 :
 : Example:
 : <!-- specify global compression level -->
 : <entries compression-level="9">
 :   <!-- overwrite compression level -->
 :   <entry compression-level="0">
 :     image.png
 :   </entry>
 :   <!-- specify encoding for text entries -->
 :   <entry encoding="UTF-8">
 :     dir/myfile.xml
 :   </entry>
 :   <!-- entry will be deleted -->
 :   <entry delete="true">
 :     to/be/deleted.txt
 :   </entry>
 : </entries>
 :
 : @return the updated base64Binary
 :
 : @error if the number of non-deleting entry elements differs from the number
 :        of specified contents:
 :        count($entries/entry[not(@delete = 'true')]) ne count($contents)
 :)
declare function zip:update($zip as xs:base64Binary, $entries as element(entries), $contents as item()*)
    as xs:base64Binary external;
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox