<apidoc:module name="ConvertModule" category="Generic Conversion" bucket="CPF Functions" 
  xmlns:apidoc="http://marklogic.com/xdmp/apidoc"
  xmlns="http://www.w3.org/1999/xhtml" lib="cvt"
>
<apidoc:summary access="public">
<p>The conversion module is part of the conversion processing pipeline.
These functions provide some basic path manipulation functions.
</p>
<p>To use the conversion module as part of your own XQuery module, include the
following line in your XQuery prolog:
</p>
<p><code>import module namespace cvt = "http://marklogic.com/cpf/convert"
         at "/MarkLogic/conversion/convert.xqy";</code></p>
<p>You will need to ensure that the conversion module is loaded into the same
modules database as the importing module.</p>
<p>The library namespace prefix <code>cvt</code> is <em>not</em> predefined in
the server.</p>
</apidoc:summary>

<apidoc:function name="basepath" type="convert" lib="cvt" 
	category="Generic Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Return the base path of the URI, cutting off the filename.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">
    The URI to manipulate.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:string </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cvt = "http://marklogic.com/cpf/convert" 
		  at "/MarkLogic/conversion/convert.xqy";

  cvt:basepath( "http://example.com/a.path/myfile.doc" ) 

  => "http://example.com/a.path"
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="basename" type="convert" lib="cvt" 
	category="Generic Conversion" bucket="CPF Functions">
  <apidoc:summary>
   Return the filename part of the URI, cutting off any query strings or 
   fragments.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">
    The URI to manipulate.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:string </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cvt = "http://marklogic.com/cpf/convert" 
		  at "/MarkLogic/conversion/convert.xqy";

  cvt:basename( "http://example.com/a.path/myfile.doc" ) 
     
  => "myfile.doc"
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="destination-uri" type="convert" lib="cvt" 
	category="Generic Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Construct the destination URI from the source URI using the following
  rules:
     The path prefix of the destination URI is the same as the source URI's.
     The filename in the destination maps '.' to '_' and appends the
     given extension.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">
    The URI to manipulate.
    </apidoc:param>
    <apidoc:param name="extension" type="xs:string">
    The extension to add, such as ".xml"
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:string </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cvt = "http://marklogic.com/cpf/convert" 
		  at "/MarkLogic/conversion/convert.xqy";

  cvt:destination-uri("http://example.com/a.path/myfile.doc", ".xml")
     
  => "http://example.com/a.path/myfile_doc.xml"
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="part-uri" type="convert" lib="cvt" 
	category="Generic Conversion" bucket="CPF Functions">
  <apidoc:summary>
  Construct the URI for the part using the following rules:
    The path prefix of the part URI is the same source URI's, followed by
       a subdirectory name.
    The subdirectory name is formed by mapping '.' to '_' in the source
       filename and appending '_parts' to it.
    The part's filename is unchanged, but any part path is removed.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">
    The URI to manipulate.
    </apidoc:param>
    <apidoc:param name="part" type="xs:string">
	    The part to append to the URI.  Only the filename is appended; any 
	    subdirectories preceding the filename are removed.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:string </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cvt = "http://marklogic.com/cpf/convert" 
		  at "/MarkLogic/conversion/convert.xqy";

  cvt:part-uri("http://example.com/a.path/myfile.doc", 
               "images/image1.jpg")
  
  => "http://example.com/a.path/myfile_doc_parts/image1.jpg"
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="save-converted-documents" type="convert" lib="cvt" 
	category="Generic Conversion" bucket="CPF Functions">
  <apidoc:summary>
   Save a set of converted documents, with appropriate links. If there is
   a main document, it must be the first listed in the manifest. The order
   in the manifest (as in xdmp:xxx-convert) must match the order of
   document nodes. Any cleaning or other preprocessing of the documents 
   must already have been done. If certain parts should have been created 
   in a certain state or with other initial properties, that must be done 
   after the call to this function.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="source-uri" type="xs:string">
    The URI of the source document.
    </apidoc:param>
    <apidoc:param name="destination-uri" type="xs:string">
    The URI of the root destination (converted) document.
    </apidoc:param>
    <apidoc:param name="manifest" type="element()">
    The parts list of all the conversion products, as returned by
    xdmp:pdf-convert, xdmp:word-convert, etc. The main or root document
    should be the first on the list, if there is one.
    </apidoc:param>
    <apidoc:param name="docs" type="document-node()*">
    The documents produced by conversion, in the same order as in the manifest.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> empty-sequence() </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace cvt = "http://marklogic.com/cpf/convert" 
		  at "/MarkLogic/conversion/convert.xqy";

  let $results := xdmp:word-convert( doc("myfile.doc"), "myfile.doc" )
  return 
     cvt:save-converted-documents("myfile.doc", "myfile.doc",
        $results[1], $results[2 to last()] )
  ]]></pre>
  </apidoc:example>
</apidoc:function>
</apidoc:module>
