<apidoc:module name="SpellingModule" category="Spelling Dictionary Management" bucket="XQuery Library Modules" 
  xmlns:apidoc="http://marklogic.com/xdmp/apidoc"
  xmlns="http://www.w3.org/1999/xhtml" lib="spell">
  <apidoc:summary access="public" category="Spelling Dictionary Management"
	  bucket="XQuery Library Modules">
  <p>The spelling functions are designed to help you manage dictionary 
  documents in  MarkLogic Server. The spelling function
  module is installed as the following file:</p>
  <ul><li><code><em>install_dir</em>/Modules/MarkLogic/spell.xqy</code></li></ul>
  <p>where <code><em>install_dir</em></code> is the directory in which 
  MarkLogic Server is installed.</p>
  <p>To use the <code>spell.xqy</code> module in your own XQuery modules, 
  include the following line in your XQuery prolog:</p>
  <p><code>import module namespace spell = "http://marklogic.com/xdmp/spell" 
		  at "/MarkLogic/spell.xqy";
     </code></p>
  <p>The library uses the <code>spell:</code> namespace, predefined in 
     the server.  </p>
  <p>The spelling correction functions (<code>spell:is-correct</code> and 
  <code>spell:suggest</code>) are built-in functions and do not require the 
  <code>import module</code> statement in the XQuery prolog.
  </p>
  <p>There are also Spell Built-In functions, which you use to check if
	  words are spelled correctly according to the dictionaries and to
	  suggest alternate spellings.
  </p>
  </apidoc:summary>

<apidoc:function name="load" type="spell" lib="spell" 
	category="Spelling Dictionary Management" 
	bucket="XQuery Library Modules">
  <apidoc:summary>
  Add the words from the file specified in $path to the dictionary at $uri.  
  If a document exists with the specified URI, it is replaced with this one.
  Note that words that are 64 characters or greater will never be returned
  as suggestions from <code>spell:suggest</code> or
  <code>spell:suggest-detailed</code>.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="path" type="xs:string">
    The path to a file containing the dictionary.
    </apidoc:param>
    <apidoc:param name="uri" type="xs:string">The URI of the dictionary.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> empty-sequence() </apidoc:return>
  <apidoc:usage>Dictionaries loaded with the <code>spell:load</code> function 
  are automatically added to the following collections:
  <ul>
    <li>http://marklogic.com/xdmp/documents</li>
    <li>http://marklogic.com/xdmp/spell</li>
  </ul>
  </apidoc:usage>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace spell = "http://marklogic.com/xdmp/spell" 
		  at "/MarkLogic/spell.xqy";

  spell:load("c:\dictionaries\spell.xml", "/mySpell/spell.xml")
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="insert" type="spell" lib="spell" 
	category="Spelling Dictionary Management" 
	bucket="XQuery Library Modules">
  <apidoc:summary>
  Load the words in $dict into the dictionary at $uri. If there is no 
  document at $uri a new one will be created. If there is a document at 
  $uri it will be overwritten.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">The URI of the dictionary.
    </apidoc:param>
    <apidoc:param name="dict" type="element(spell:dictionary)">
    A dictionary document.
    </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 spell = "http://marklogic.com/xdmp/spell" 
		  at "/MarkLogic/spell.xqy";

  spell:insert("/mySpell/special.xml", 
     <dictionary xmlns="http://marklogic.com/xdmp/spell">
          <word>WebDAV</word>
     </dictionary> )

  => Creates a dictionary with only the word "WebDAV" 
     at the specifed URI
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="add-word" type="spell" lib="spell" 
	category="Spelling Dictionary Management" 
	bucket="XQuery Library Modules">
  <apidoc:summary>
	  Add the word $word to the dictionary at $uri. If the word
	  is already in the dictionary (case-sensitive), then this function
	  throws an exception.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">
    The URI of the dictionary.
    </apidoc:param>
    <apidoc:param name="word" type="xs:string">
    The word to add.
    </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 spell = "http://marklogic.com/xdmp/spell" 
		  at "/MarkLogic/spell.xqy";

  spell:add-word("/mySpell/spell.xml", "WebDAV")

  => adds the word "WebDAV" to the specifed dictionary
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="remove-word" type="spell" lib="spell" 
	category="Spelling Dictionary Management" 
	bucket="XQuery Library Modules">
  <apidoc:summary>
  Remove the word $word from the dictionary at $uri.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="uri" type="xs:string">
    The URI of the dictionary.
    </apidoc:param>
    <apidoc:param name="word" type="xs:string">
    The word to remove.
    </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 spell = "http://marklogic.com/xdmp/spell" 
		  at "/MarkLogic/spell.xqy";

  spell:remove-word("/mySpell/spell.xml", "Fiat")

  => removes the word "Fiat" from the specified dictionary
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="make-dictionary" type="spell" lib="spell" 
	category="Spelling Dictionary Management" 
	bucket="XQuery Library Modules">
  <apidoc:summary>
	  Creates a dictionary node from a sequence of words.  Use
	  <code>spell:load</code> to load the dictionary node into the 
	  database as a dictionary.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="words" type="xs:string*">
    The words from which to construct a dictionary.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return>element(spell:dictionary)</apidoc:return>

  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace spell = "http://marklogic.com/xdmp/spell" 
		  at "/MarkLogic/spell.xqy";

  let $words := ("words", "to", "go", "in", "the", "dictionary")
  return 
  spell:make-dictionary($words)

  => 
  <dictionary xmlns="http://marklogic.com/xdmp/spell">
    <word>words</word>
    <word>to</word>
    <word>go</word>
    <word>in</word>
    <word>the</word>
    <word>dictionary</word>
  </dictionary>

  ]]></pre>
  </apidoc:example>

  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace spell = "http://marklogic.com/xdmp/spell" 
		  at "/MarkLogic/spell.xqy";

  spell:make-dictionary(cts:words())

  => A spell:dictionary element containing all the words in the database.  
     Use spell:load to load this into the database as a dictionary.  
     This example requires a word lexicon on the database.  You can 
     construct the sequence of words any way you like.
  ]]></pre>
  </apidoc:example>
</apidoc:function>


</apidoc:module>
