1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="xpf_document_literal">
<refmeta>
<refentrytitle>document-literal</refentrytitle>
<refmiscinfo>XPATH</refmiscinfo>
</refmeta>
<refnamediv>
<refname>document-literal</refname>
<refpurpose>Parses given XML text and returns the resulting XML data.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="xpf_syn_document_literal">
<funcprototype id="xpf_proto_document_literal">
<funcdef>node-set <function>document-literal</function></funcdef>
<paramdef><parameter>document_text</parameter> varchar</paramdef>
<paramdef><optional><parameter>cache_uri</parameter> varchar</optional></paramdef>
<paramdef><optional><parameter>parser_mode</parameter> integer</optional></paramdef>
<paramdef><optional><parameter>content_encoding</parameter> varchar</optional></paramdef>
<paramdef><optional><parameter>content_language</parameter> varchar</optional></paramdef>
<paramdef><optional><parameter>dtd_validator_config</parameter> varchar</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="xpf_desc_document_literal"><title>Description</title>
<para>
The function tries to parse an XML text as if it is obtained from a location
specified by <parameter>cache_uri</parameter>. On success, it returns
the root entity of the "XML Tree" document; the result is identical to
the entity created by <link linkend="fn_xtree_doc">xtree_doc()</link> Virtuoso/PL function.
</para>
<para>
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 <parameter>cache_uri</parameter> specifies the URI used as a key if the parsed document is cached.
If <parameter>cache_uri</parameter> is not specified or the specified value is equal to an empty string,
then no caching is performed.
If the specified <parameter>cache_uri</parameter> 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.
</para>
<para>
The <parameter>cache_uri</parameter> 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.
</para>
<para>
The <parameter>document_text</parameter> argument may be a sequence, not a single string.
In this case a node-set is returned as if <function>document-literal</function> 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.
</para>
<para>
Note that the <function>document-literal</function> is not a part of XPATH 1.0
or XQuery 1.0 standard library.
</para>
</refsect1>
<refsect1 id="xpf_params_document_literal"><title>Parameters</title>
<refsect2><title>document_text</title>
<para>well formed XML or HTML text</para></refsect2>
<refsect2><title>cache_uri</title>
<para>The URI that is used to
resolve all relative URIs (i.e. to convert them into absolute in order to locate and load subdocuments) and
to change 'local' absolute references to relative when in HTML mode.</para></refsect2>
<refsect2><title>parser_mode</title>
<para>0, 1 or 2; 0 - XML parser mode, 1 - HTML parser mode, 2 - 'dirty HTML'
mode (with quiet recovery after any syntax error)</para></refsect2>
<refsect2><title>content_encoding</title>
<para>string with content encoding type of <parameter>document_text</parameter>; valid are 'ASCII', 'ISO',
'UTF8', 'ISO8859-1', 'LATIN-1' etc., defaults are 'UTF-8' for XML mode and 'LATIN-1' for
HTML mode.</para></refsect2>
<refsect2><title>content_language</title>
<para>string with language tag of content of <parameter>document_text</parameter>; valid names are listed in
IETF RFC 1766, default is 'x-any' (it means 'mix of words from various human languages')</para></refsect2>
<refsect2><title>dtd_validator_config</title>
<para>configuration string for DTD validator, default is "Include=ERROR IdCache=ENABLE" meaning that DTD
should be read but validation should be disabled; errors on including subdocuments should be
reported as errors and thus should abort the processing; a dictionary of element's IDs should be created
in order to support XQuery 'pointer operator'.
See <link linkend="dtd_config">Configuration Options of the DTD Validator</link> for details.</para></refsect2>
</refsect1>
<refsect1 id="xpf_ret_document_literal"><title>Return Types</title><para>Node-set</para></refsect1>
<refsect1 id="xpf_errors_document_literal"><title>Errors</title>
<table><title>Errors signalled by document-literal()</title>
<tgroup cols="4">
<thead><row><entry>SQLState</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry></row></thead>
<tbody>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPF15</errorcode></entry>
<entry><errorname>Too many arguments passed to XPATH function document-literal()</errorname></entry>
<entry>The number of parameters may vary only from 1 to 6.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="xpf_examples_document_literal"><title>Examples</title>
<example id="xpf_ex_document_literal1"><title>Simple reading of a standalone XML document</title>
<para>Read a short document from string</para>
<screen>document-literal("<html><body><p>Hello</p></body></html>")</screen>
</example>
<example id="xpf_ex_document_literal2"><title>Simple reading of a non-standalone document</title>
<para>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'</para>
<screen><![CDATA[
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' )
]]></screen>
</example>
</refsect1>
<refsect1 id="xpf_seealso_document_literal"><title>See Also</title>
<para><link linkend="xpf_document">document()</link></para>
<para><link linkend="fn_xtree_doc">xtree_doc()</link></para>
<para><link linkend="fn_xper_doc">xper_doc()</link></para>
</refsect1>
</refentry>
|
