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
|
<?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_shallow">
<refmeta>
<refentrytitle>shallow</refentrytitle>
<refmiscinfo>XPATH</refmiscinfo>
</refmeta>
<refnamediv>
<refname>shallow</refname>
<refpurpose>Returns a shallow copy of the given XML entity</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="xpf_syn_shallow">
<funcprototype id="xpf_proto_shallow">
<funcdef>entity <function>shallow</function></funcdef>
<paramdef><parameter>ent</parameter> entity</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="xpf_desc_shallow"><title>Description</title>
<para>
The function returns a shallow copy of the given XML entity, i.e. a root of a new document that consists of
only one node that is a copy of the given entity but have no children.
</para></refsect1>
<refsect1 id="xpf_params_shallow"><title>Parameters</title>
<refsect2><title>ent</title>
<para>The XML entity to copy</para></refsect2>
</refsect1>
<refsect1 id="xpf_ret_shallow"><title>Return Types</title><para>The function returns an XML entity.</para></refsect1>
<refsect1 id="xpf_errors_shallow"><title>Errors</title>
<table><title>Errors signalled by shallow()</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>XPFD6</errorcode></entry>
<entry><errorname>The argument of XPATH function shallow() is not an entity</errorname></entry>
<entry>To match XQuery standard, the function signal an error if <parameter>ent</parameter> is not an entity.</entry>
</row>
<row>
<entry><errorcode>XP001</errorcode></entry>
<entry><errorcode>XPFD7</errorcode></entry>
<entry><errorname>Persistent XML entities are not supported by XPATH function shallow()</errorname></entry>
<entry>This is an artificial restriction that is to be removed in future versions of Virtuoso.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="xpf_examples_shallow"><title>Examples</title>
<example id="xpf_ex_shallow"><title>Find Martha's spouse</title>
<para>
The idea of the following sample is from W3C's XQuery Use Cases (case 1.9.4.1.).
The query should find all persons whose name is "Marta"
and return entities that describes their spouses, with removed information about children.
</para>
<screen>
-- read the document, then...
let $doc := document("census.xml")
-- for every person named "Martha"...
for $m in $doc//person[@name="Martha"]
-- for all (i.e. 0 or 1) her spouses...
for $s in $m/@spouse => person
-- return <person> element with attributes preserved but with children removed
return shallow($s)
</screen>
</example>
</refsect1>
<refsect1 id="xpf_seealso_shallow"><title>See Also</title>
<para><link linkend="xpf_filter">filter()</link></para>
</refsect1>
</refentry>
|
