.. _doc:

===
doc
=== 

Abre um documento a partir de um URI

Descrição
~~~~~~~~~
A função fn:doc devolve o nó de documento do recurso que está no URI indicado.

Se você acessa documentos no sistema de arquivos, a implementação pode exigir 
que o nome do arquivo comece com file:///, que os diretórios sejam separados por 
barras e que cada espaço no nome seja escrito como %20.

URIs relativos também são aceitos. Se $uri for relativo, ele é resolvido a 
partir do URI base do contexto estático. Esse URI base pode ser definido pelo 
processador fora da consulta ou declarado no prólogo da consulta.

Repare que fn:doc devolve o nó de documento, e não o elemento raiz. Por isso, o 
elemento raiz precisa entrar no caminho (catalog, no exemplo).

Cada processador interpreta o URI passado a fn:doc de um jeito. Alguns, como o 
Saxon, vão até o endereço e buscam o recurso que está lá. Outros, como os 
embutidos em bancos de dados XML, tratam os URIs só como nomes: o processador 
pode procurar o nome num catálogo interno para achar o documento ligado a ele.

As implementações também têm liberdade em como tratam erros ao buscar 
documentos, como lidam com tipos MIME diferentes e se validam ou não os 
documentos contra um schema ou uma DTD.

A função fn:doc é estável: devolve o mesmo resultado sempre que é chamada dentro 
de uma consulta. Se você chamá-la mais de uma vez com o mesmo argumento, na 
mesma consulta, o resultado é o mesmo, mesmo que o recurso em $uri tenha mudado. 
Além disso, os nós de documento devolvidos em cada chamada são idênticos entre 
si.

Não confunda fn:doc com a função fn:document do XSLT, que não existe em XQuery. 
A fn:document se comporta de outro jeito: aceita vários URIs, permite indicar um 
URI base e tem um tratamento próprio para identificadores de fragmento.

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - **Parâmetros**
     - **Descrição**
   * - uri:string()
     - o URI do documento

Exemplos
~~~~~~~~
.. list-table::
   :widths: 50 50
   :header-rows: 1

   * - **XPath**
     - **Resultado**
   * - doc('http://www.functx.com/input/order.xml')
     - the document node of the document at http://www.functx.com/input/order.xml.

Veja também
~~~~~~~~~~~

.. toctree::
   :titlesonly:
   :glob:

* :ref:`doc-available`.
* :ref:`collection`.
* :ref:`document-uri`.
* :ref:`functx_open-ref-document`.