<apidoc:module name="Zip" category="ZipBuiltins" lib="xdmp" xmlns:apidoc="http://marklogic.com/xdmp/apidoc"><apidoc:summary access="public">
  Zip function allow the server to handle .zip files.
</apidoc:summary><apidoc:function name="zip-manifest" type="builtin" lib="xdmp" category="Document Conversion" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Return a manifest for this zip file.  The manifest contains information
  about what is in the zip file.  The form of the manifest is:
  <pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  &lt;parts xmlns="xdmp:zip"&gt;
    &lt;part uncompressed-size="[size]" compressed-size="[size]" 
          encrypted="[true/false]"&gt;path1&lt;/part&gt;
    &lt;part uncompressed-size="[size]" compressed-size="[size]" 
          encrypted="[true/false]"&gt;path2&lt;/part&gt;
    ...more parts
  &lt;/parts&gt;      </pre>
  Each &lt;part&gt; is a file within the zip.  The attributes specify the
  uncompressed size for the file, the compressed size for that file, whether
  or not the file is encrypted, and the last-modified timestamp.  Note that
  MarkLogic cannot exctract encrypted files, attempting to do so will cause an
  error. Also note that due to a limitation in the zip file format, the
  last-modified time has a granularity of two seconds (e.g. 10:22:33 becomes
  10:22:32). 
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="zipfile" type="binary()" optional="false">
    The zip document binary node.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>node()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:zip-manifest($myzip)
=&gt; 
&lt;parts&gt;
  &lt;part uncompressed-size="89246" compressed-size="4538" 
        encrypted="no" last-modified="2009-03-20T03:30:32"&gt;
    docProps/app.xml
  &lt;/part&gt;
  &lt;part uncompressed-size="2896" compressed-size="634" 
        encrypted="no" last-modified="2009-03-23T19:30:32"&gt;
    word/fontTable.xml
  &lt;/part&gt;
  &lt;part uncompressed-size="139914" compressed-size="12418" 
        encrypted="yes" last-modified="2009-03-23T15:30:32"&gt;
    word/styles.xml
  &lt;/part&gt;
&lt;/parts&gt;

</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="zip-get" type="builtin" lib="xdmp" category="Document Conversion" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Get a named file from a zip document. Unzips and returns the file in 
  memory as a document node (for XML formats), a text node (for text formats),
  or a binary node (for binary formats). The format is determined either
  by the mimetype from the file name or by the <code xmlns="http://www.w3.org/1999/xhtml">format</code> option.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="zipfile" type="binary()" optional="false">
    The zip file.
  </apidoc:param>
      <apidoc:param name="name" type="xs:string" optional="false">
    The path to the zip file as shown in the zip manifest.
  </apidoc:param>
      <apidoc:param name="options" type="node()?" optional="true">
    The options node for gitting this zip file.  The default value is ().  
    The node for the xdmp:zip-get options must be in the
    <code xmlns="http://www.w3.org/1999/xhtml">xdmp:zip-get</code> namespace. 
    <p xmlns="http://www.w3.org/1999/xhtml">The <code>xdmp:zip-get</code> options include:</p> 
    <blockquote xmlns="http://www.w3.org/1999/xhtml"><dl>
    <dt><p>&lt;default-namespace&gt;</p></dt>
    <dd>The namespace to use if there is no namespace at the root node of
    the document. The default value is "".</dd>
    <dt><p>&lt;repair&gt;</p></dt>
    <dd>A value of <code>full</code> specifies that malformed XML content be 
        repaired.  A value of <code>none</code> specifies that malformed 
	XML content is rejected. 
        If no repair option is explicitly specified, the default is 
        implicitly specified by the XQuery version of the caller.
        In XQuery <code>1.0</code> and <code>1.0-ml</code> the default 
	is <code>none</code>.  In XQuery <code>0.9-ml</code> the 
	default is <code>full</code>.
        This option has no effect on binary or text documents.</dd>
    <dt><p>&lt;format&gt;</p></dt>
    <dd>A value of <code>text</code> specifies to get the document as a 
        text document, regardless of the URI specified. A value of 
	<code>binary</code> specifies to get the document as a binary 
	document, regardless of the URI specified. A value of <code>xml</code>
       	specifies to get the document as an XML document, regardless of the 
	URI specified.</dd>
    <dt><p>&lt;default-language&gt;</p></dt>
    <dd>The language to specify in an <code>xml:lang</code> attribute on the
    root element node if the root element node does not already have an 
    <code>xml:lang</code> attribute. If <code>default-language</code> is
    not specified, then nothing is added to the root element node.</dd>
    <dt><p>&lt;encoding&gt;</p></dt>
    <dd>Specifies the encoding to use when reading the document into MarkLogic
    Server.  Supported values include <code>UTF-8</code> and 
    <code>ISO-8859-1</code>.  All encodings will be translated into UTF-8
    from the specified encoding.  The string specifed for the 
    <code>encoding</code> option will be matched to an encoding name according
    to the Unicode Charset Alias Matching rules 
    (<a href="http://www.unicode.org/reports/tr22/#Charset_Alias_Matching">http://www.unicode.org/reports/tr22/#Charset_Alias_Matching</a>). 
    An automatic encoding detector will be used if the value <code>auto</code>
    is specified.
    If no encoding can be detected, the encoding defaults to UTF-8.
    If no encoding option is specified, the encoding defaults to the 
    encoding specified in the http header (if using with one of the http 
    functions, for example, <code>xdmp:http-get</code>), otherwise it defaults
    to UTF-8; any encoding http headers are ignored if there is any
    value specified for the <code>encoding</code> option.</dd>
    </dl></blockquote>
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>node()+</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">The name of the document you are extracting will determine the default
  format in which the document is extracted, based on the mimetype settings. 
  For example, if you are extracting a document with the name 
  <code>myDocument.xmlfile</code>, it will by default extract that document
  as a text document (because it is an unknown mimetype, and unknown 
  mimetypes default to text format).  If you know this is an XML document, 
  then specify a <code>format</code> of <code>xml</code> in the 
  <code>options</code> node (see the <a href="#zipget3">third example</a> 
  below).</p> 
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:zip-get(doc("/zip/tmp.zip"), "files/myxmlfile.xml")

=&gt; the "files/myxmlfile.xml" node from the "/zip/tmp.zip" zip file

</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
(: unzip all of the files in the zip archive :)
xquery version "1.0-ml";
declare namespace zip="xdmp:zip";

for $x in xdmp:zip-manifest(doc("/zip/tmp.zip"))//zip:part/text()
return
xdmp:zip-get(doc("/zip/tmp.zip"), $x)

=&gt; a sequence of all of the unzipped nodes in the "/zip/tmp.zip" zip file

</pre></apidoc:example>
    <apidoc:example>
<pre xml:space="preserve" id="zipget3" xmlns="http://www.w3.org/1999/xhtml">
xdmp:zip-get(doc("/zip/tmp.zip"), "myDocument.xmlfile",
	&lt;options xmlns="xdmp:zip-get"&gt;
	  &lt;format&gt;xml&lt;/format&gt;
	&lt;/options&gt;)

=&gt; the "myDocument.xmlfile" node from the "/zip/tmp.zip"
   zip file, as an XML document

</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="zip-create" type="builtin" lib="xdmp" category="Document Conversion" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Create a zip file from a list of nodes.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="manifest" type="node()" optional="false">
    The zip manifest, which must be in the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:zip</code> namespace
    and conform to the <code xmlns="http://www.w3.org/1999/xhtml">zip.xsd</code> schema, located in the 
    <code xmlns="http://www.w3.org/1999/xhtml"><em>marklogic-dir</em>/Schemas</code> directory.
    The manifest has the following basic form:
    <blockquote xmlns="http://www.w3.org/1999/xhtml"><pre xml:space="preserve">
    &lt;parts xmlns="xdmp:zip"&gt;
      &lt;part last-modified="2009-03-23T19:30:32"&gt;path1&lt;/part&gt;
      &lt;part&gt;path2&lt;/part&gt;
      ...more parts
    &lt;/parts&gt;      </pre></blockquote>
    Any of the size or encrypted attributes in the manifest are ignored for
    <code xmlns="http://www.w3.org/1999/xhtml">xdmp:zip-create</code>.  Attributes other than uncompressed-size,
    compressed-size, encrypted, and last-modified will throw an error. If the
    last-modified attribute is specified, that date and time will be set for the
    part. Otherwise, if the node for the part comes from a database that tracks
    the last modified time of a document, that date and time will be used. The
    current date and time will be used if no other value is available. Due to
    a limitation in the zip file format, the time has a granularity of two
    seconds (e.g. 10:22:33 becomes 10:22:32). 
  </apidoc:param>
      <apidoc:param name="nodes" type="node()+" optional="false">
    The nodes that you want to zip up.  The nodes correspond to 
    <code xmlns="http://www.w3.org/1999/xhtml">part</code> elements in the manifest, where the first node corresponds
    to the first <code xmlns="http://www.w3.org/1999/xhtml">part</code> element specified, the second node to the 
    second <code xmlns="http://www.w3.org/1999/xhtml">part</code> element, and so on.  Specifying a different number
    of &lt;part&gt; elements than nodes will result in an error.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>binary()</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">While you can create a zip file of encrypted content, 
  <code>xdmp:zip-create</code> does not have the capability to encrypt
  the content to be zipped.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">The <code>&lt;part&gt;</code> elements in the manifest should 
  contain relative paths so the zip file can be unpacked into its own 
  directory; do not start the path with a forward slash or a backslash.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">To support creating Open Container Format archives for the EPUB
  format, <code>xdmp:zip-create</code> will not compress the first
  part if it is named "mimetype".</p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
let $zip := xdmp:zip-create(
               &lt;parts xmlns="xdmp:zip"&gt;
                 &lt;part&gt;mydoc.xml&lt;/part&gt;
		 &lt;part&gt;mypicture.jpg&lt;/part&gt;
	        &lt;/parts&gt;,
		(doc("/mydoc.xml"), doc("/mypicture.jpg")))
return
xdmp:save("c:/tmp/myzip.zip", $zip,
     &lt;options xmlns="xdmp:save"&gt;
        &lt;encoding&gt;utf8&lt;/encoding&gt;
     &lt;/options&gt;)

=&gt; Creates a zip archive that includes the documents "/mydoc.xml"
   and "/mypicture.jpg", then saves that to the filesystem.  

</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
(: the "mimetype" file will not be compressed to support 
   the EPUB format :)
let $zip := xdmp:zip-create(
               &lt;parts xmlns="xdmp:zip"&gt;
                 &lt;part&gt;mimetype&lt;/part&gt;
		 &lt;part&gt;META-INF/container.xml&lt;/part&gt;
		 &lt;part&gt;OEBPS/content.opf&lt;/part&gt;
		 &lt;part&gt;OEBPS/content.pdf&lt;/part&gt;
	        &lt;/parts&gt;,
		(document { "application/epub+zip" },
                 doc("/my-doc/container.xml"),
                 doc("/my-doc/content.opf"),
                 doc("/my-doc/content.pdf")
                 ))
return
xdmp:save("c:/tmp/mydoc.epub", $zip,
     &lt;options xmlns="xdmp:save"&gt;
        &lt;encoding&gt;utf8&lt;/encoding&gt;
     &lt;/options&gt;)

=&gt; Creates a zip archive that meets the OCF specification,
   then saves that to the filesystem.

</pre></apidoc:example>
  </apidoc:function></apidoc:module>