Author: jstephens
Date: 2006-01-13 18:02:10 +0100 (Fri, 13 Jan 2006)
New Revision: 803
Log:
Added XPath mini-tutorial; moved a couple of paragraphs around in description of
XPath functions. (Stefan)
Modified:
trunk/refman-5.1/functions.xml
Modified: trunk/refman-5.1/functions.xml
===================================================================
--- trunk/refman-5.1/functions.xml 2006-01-13 12:30:11 UTC (rev 802)
+++ trunk/refman-5.1/functions.xml 2006-01-13 17:02:10 UTC (rev 803)
@@ -13771,6 +13771,146 @@
</itemizedlist>
<para>
+ Descriptions and examples of some basic XPath expressions
+ follow:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>/<replaceable>tag</replaceable></literal>
+ </para>
+
+ <para>
+ Matches
+ <literal><<replaceable>tag</replaceable>/></literal> if
+ and only if
+ <literal><<replaceable>tag</replaceable>/></literal> is
+ the root element.
+ </para>
+
+ <para>
+ Example: <literal>/a</literal> has a match in
+ <literal><a><b/></a></literal>
+ (it matches the outer tag), but does not match the inner
+ <replaceable>a</replaceable> element in
+ <literal><b><a/></b></literal>
+ because in this instance it is the child of another element.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>/<replaceable>tag1</replaceable>/<replaceable>tag2</replaceable></literal>
+ </para>
+
+ <para>
+ Matches
+ <literal><<replaceable>tag2</replaceable>/></literal>
+ if and only if it is a child of
+ <literal><<replaceable>tag1</replaceable>/></literal>,
+ and
+ <literal><<replaceable>tag1</replaceable>/></literal>
+ is the root element.
+ </para>
+
+ <para>
+ Example: <literal>/a/b</literal> matches the
+ <replaceable>b</replaceable>element in the XML fragment
+ <literal><a><b/></a></literal> because it
+ is a child of the root element <replaceable>a</replaceable>.
+ It does not have a match in
+ <literal><b><a/></b></literal> because in
+ this case, <replaceable>b</replaceable> is the root element
+ (and hence the child of no other element). Nor does the
+ XPath expression have a match in
+ <literal><a><c><b/></c></a></literal>;
+ here, <replaceable>b</replaceable> is a descendant of
+ <replaceable>a</replaceable>, but not actually a child of
+ <replaceable>a</replaceable>.
+ </para>
+
+ <para>
+ This construct is extendable to three or more elements. For
+ example, the XPath expression <literal>/a/b/c</literal>
+ matches the <replaceable>c</replaceable> element in the
+ fragment
+ <literal><a><b><c/></b></a></literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>//<replaceable>tag</replaceable></literal>
+ </para>
+
+ <para>
+ Matches any <replaceable>tag</replaceable>.
+ </para>
+
+ <para>
+ Example: <literal>//a</literal> will match the
+ <replaceable>a</replaceable> element in any of the
+ following:
+ <literal><a><b><c/></b></a></literal>;
+ <literal><c><a><b/></a></b></literal>;
+ <literal><c><b><a/></b></c></literal>.
+ </para>
+
+ <para>
+ <literal>//</literal> can be combined with
+ <literal>/</literal>. For example, <literal>//a/b</literal>
+ matches the <replaceable>b</replaceable> element in either
+ of the fragments
+ <literal><a><b/></a></literal> or
+ <literal><a><b><c/></b></a></literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The <literal>*</literal> operator acts as a
+ <quote>wildcard</quote> element. For example, the expression
+ <literal>/*/b</literal> matches the
+ <replaceable>b</replaceable> element in either of the XML
+ fragments <literal><a><b/></a></literal>
+ or <literal><c><b/></c></literal>.
+ However, the expression does not produce a match in the
+ fragment <literal><b><a/></b></literal>
+ because <replaceable>b</replaceable> must be a child of some
+ other element. The wildcard may be used in any position: the
+ expression <literal>/*/b/*</literal> will match any child of
+ a <replaceable>b</replaceable> element that is itself not
+ the root element.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ It is also possible to match an element based on the value
+ of one or more of its attributes. This done using the syntax
+ <literal><replaceable>tag</replaceable>[@<replaceable>attribute</replaceable>="<replaceable>value</replaceable>"]</literal>.
+ For example, the expression
+ <literal>//b[@id="idB"]</literal> matches the second
+ <replaceable>b</replaceable> element in the fragment
+ <literal><a><b id="idA"/><<c/>b
+ id="idB"/></a></literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ A discussion in depth of XPath syntax and usage are beyond the
+ scope of this Manual. Please see the
+ <ulink url="http://www.w3.org/TR/xpath">XML Path Language
+ (XPath) 1.0 standard</ulink> for definitive information. A
+ useful resource for those new to XPath or wishing a refresher in
+ the basics is the
+ <ulink url="http://www.zvon.org/xxl/XPathTutorial/">Zvon.org
+ XPath Tutorial</ulink>, which is available in several
+ languages.
+ </para>
+
+ <para>
The XPath syntax supported by these functions is currently
subject to the following limitations:
</para>
@@ -13780,8 +13920,10 @@
<para>
Nodeset-to-nodeset comparison (such as
<literal>'/a/b[@c=@d]'</literal>) is not supported. Only
- '/a/b[@c=<replaceable>"const"</replaceable>]' is currently
- possible.
+ comparisons of the form
+ <literal>[@<replaceable>attribute</replaceable>="<replaceable>const</replaceable>"]</literal>,
+ where <replaceable>const</replaceable> is a constant value,
+ are currently possible.
</para>
</listitem>
@@ -13901,20 +14043,8 @@
<para>
We continue to develop and improve these and other aspects of
- XML/XPath functionality in MySQL 5.1 and onwards.
+ XML and XPath functionality in MySQL 5.1 and onwards.
</para>
-
- <para>
- A discussion in depth of XPath syntax and usage are beyond the
- scope of this Manual. Please see the
- <ulink url="http://www.w3.org/TR/xpath">XML Path Language
- (XPath) 1.0 standard</ulink> for definitive information. A
- useful resource for those new to XPath or wishing a refresher in
- the basics is the
- <ulink url="http://www.zvon.org/xxl/XPathTutorial/">Zvon.org
- XPath Tutorial</ulink>, which is available in several
- languages.
- </para>
</section>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r803 - trunk/refman-5.1 | jon | 13 Jan |
