The function tries to parse an XML text as if it is obtained from a location specified by cache_uri. On success, it returns the root entity of the "XML Tree" document; the result is identical to the entity created by xtree_doc() Virtuoso/PL function.
When XPath processor parses a document, it saves it in a temporary cache. If a cached document is accessed again then no actual retrieval or parsing is made and a cached value is returned. The cache persists till the end of execution of a XPath query or till the end of the XSLT transformation if the XPath expression is a part of XSLT stylesheet. The cache_uri specifies the URI used as a key if the parsed document is cached. If cache_uri is not specified or the specified value is equal to an empty string, then no caching is performed. If the specified cache_uri is not equal to an empty string then it should distinct from URIs of other XML resources that are sources of the XPath query, to prevent confusion.
The cache_uri is also used by XML parser as a base URI to resolve relative URIs of external entities, so it is a good idea to specify some absolute URI if the parsed text is not a "standalone" document.
The document_text argument may be a sequence, not a single string. In this case a node-set is returned as if document-literal is applied to string-value of every element of the sequence. It is obvious that caching should not be used if there's a chance that the sequence may have more than one distinct element.
Note that the document-literal is not a part of XPATH 1.0 or XQuery 1.0 standard library.
Node-set
SQLState | Error Code | Error Text | Description |
---|---|---|---|
XP001 | XPF15 | Too many arguments passed to XPATH function document-literal() | The number of parameters may vary only from 1 to 6. |
Read a short document from string
document-literal("Hello")
Read a non-standalone document from local mirror but access its subdocuments as if it is retrieved directly from 'http://www.example.com/sales/prices.xml', so e.g. the subdocument that is referenced as 'termsandconditions.xml' is retrieved from 'http://www.example.com/sales/termsandconditions.xml'
document-literal(' <!DOCTYPE price-list SYSTEM "http://www.example.com/dtd/sales.dtd" [ <!ENTITY t_and_c SYSTEM "termsandconditions.xml"> <!ENTITY prices_oct2002 SYSTEM "prices/2002/oct.xml"> ]> <price-list> &t_and_c; &prices_oct2002; </price-list> ', 'http://webcache.localdomain/examplesales/prices.xml' )