Archive Module: Eighth Proposal

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

Yet another proposal for the Archive Module:

  • changed the options schema to be consistent with the options for fn:serialize
  • entry elements are in the namespace of the module

The full function signatures are as follows:

module namespace a = "http://www.expath.org/ns/archive";

import schema namespace options = "http://www.expath.org/ns/archive";
 
(:~
 : Create a new archive according to the given spec.
 : The contents can be string and base64Binary items.
 :
 : Example:
 : <!-- specify compression level (0 = uncompressed) -->
 : <a:entry last-modified="" compression-level="0">
 :   myfile.txt
 : </a:entry>
 : <!-- specify encoding for text entries -->
 : <a:entry encoding="Shift_JIS">
 :   dir/myfile.xml
 : </a:entry>
 : <a:entry>
 :   dir/dir2/image.png
 : </a: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 a:create(
  $entries as element(a:entry)*,
  $contents as item()*)
    as xs:base64Binary external;

(:~
 : <a:options archive-format="zip">
 :   <a:algorithm value="stored"/>
 : </a:options>
 :)
declare function a:create(
  $entries as element(a:entry)*,
  $contents as item()*,
  $options as element(a:options))
    as xs:base64Binary external; 
 
(:~
 : Return the specification of the given archive.
 :
 : Example:
 : <a:entry last-modified="2009-03-20T03:30:32" compressed-size="232" uncompressed-size"324" encrypted="false">
 :   myfile.txt
 : </a:entry>
 : <a:entry>
 :   dir/myfile.xml
 : </a:entry>
 : <a:entry>
 :   dir/dir2/image.png
 : </a:entry>
 :
 : @return specification
 :)
declare function a:entries($archive as xs:base64Binary)
    as element(a:entry)* external;
 
(:~
 : Returns all entries from the archive as a string.
 : The default encoding used to read the string is UTF-8.
 :
 : @return strings
 :
 : @error if the file contains invalid utf-8 characters
 : @error if the file doesn't exist
 :)
declare function a:extract-text($archive as xs:base64Binary)
    as xs:string* external;
 
(:~
 : Returns the entries identified by the given paths from the archive
 : as a string.
 : The default encoding used to read the string is UTF-8.
 :
 : @return strings
 :
 : @error if the file contains invalid utf-8 characters
 : @error if the file doesn't exist
 :)
declare function a:extract-text($archive as xs:base64Binary, $entry-names as xs:string*)
    as xs:string* external;
 
(:~
 : Returns the entries identified by the given paths from the archive
 : as a string.
 :
 : @return strings
 :
 : @error if the file contains invalid characters
 : @error if a transcoding error happens
 :)
declare function a:extract-text($archive as xs:base64Binary, $entry-names as xs:string*, $encoding as xs:string)
    as xs:string* external;
 
(:~
 : Returns all entries from the archive
 : as base64Binary.
 :
 : @return base64Binary items
 :
 : @error if the file does not exist
 :)
declare function a:extract-binary($archive as xs:base64Binary)
    as xs:base64Binary* external;
 
(:~
 : Returns the entries identified by the given paths from the archive
 : as base64Binary.
 :
 : @return base64Binary items
 :
 : @error if the file does not exist
 :)
declare function a:extract-binary($archive as xs:base64Binary, $entry-names as xs:string*)
    as xs:base64Binary* external;
 
(:~
 : Adds and replaces entries in a archive according to
 : the given spec. The contents can be string and base64Binary items.
 :
 : @return the updated base64Binary
 :
 : @error if the number of entry elements differs from the number
 :        of specified contents: count($entries) ne count($contents)
 :
 :)
declare function a:update($archive as xs:base64Binary, $entries as element(entry)*, $contents as item()*)
    as xs:base64Binary external;
 
(:~
 : Deletes entries from a archive.
 :
 : @return the updated base64Binary
 :
 : @error if an addressed entry does not exist
 :)
declare function a:delete($archive as xs:base64Binary, $entry-names as xs:string*)
    as xs:base64Binary external;

The options schema is follows:

<?xml version="1.0"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.expath.org/ns/archive"
  xmlns="http://www.expath.org/ns/archive"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified">

  <xs:simpleType name="compression-algorithm-string-type">
    <xs:restriction base="xs:string">
      <xs:enumeration value="stored"/>
      <xs:enumeration value="deflate"/>
      <xs:enumeration value="bzip2"/>
      <xs:enumeration value="lzma"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="compression-integer-type">
    <xs:restriction base="xs:integer">
      <xs:minInclusive value="0"/>
      <xs:maxInclusive value="9"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="archive-format-string-type">
    <xs:restriction base="xs:string">
      <xs:enumeration value="zip"/>
      <xs:enumeration value="tar"/>
      <xs:enumeration value="pax"/>
    </xs:restriction>
  </xs:simpleType>

  <!-- base type -->
  <xs:complexType name="base-param-type">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
        <xs:anyAttribute namespace="##other" processContents="lax"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:element name="archive-option-element"
    abstract="true" type="base-param-type"/>

  <!-- compression algorithm -->
  <xs:complexType name="compression-algorithm-type">
    <xs:complexContent>
      <xs:extension base="base-param-type">
        <xs:attribute name="value" type="compression-algorithm-string-type"
              use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:element id="algorithm" name="algorithm" type="compression-algorithm-type"
        substitutionGroup="archive-option-element"/>

  <!-- compression level -->
  <xs:complexType name="compression-type">
    <xs:complexContent>
      <xs:extension base="base-param-type">
        <xs:attribute name="value" type="compression-integer-type"
              use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:element id="compression" name="compression" type="compression-type"
        substitutionGroup="archive-option-element"/>

  <!-- archive format -->
  <xs:complexType name="archive-format-type">
    <xs:complexContent>
      <xs:extension base="base-param-type">
        <xs:attribute name="value" type="archive-format-string-type"
              use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:element id="format" name="format" type="archive-format-type"
        substitutionGroup="archive-option-element"/>

  <!-- options element -->
  <xs:element name="options">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="archive-option-element"
              minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox