List:Commits« Previous MessageNext Message »
From:jon Date:January 13 2006 5:02pm
Subject:svn commit - mysqldoc@docsrva: r803 - trunk/refman-5.1
View as plain text  
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>&lt;<replaceable>tag</replaceable>/&gt;</literal> if
+            and only if
+            <literal>&lt;<replaceable>tag</replaceable>/&gt;</literal> is
+            the root element.
+          </para>
+          
+          <para>
+            Example: <literal>/a</literal> has a match in
+            <literal>&lt;a&gt;&lt;b/&gt;&lt;/a&gt;</literal>
+            (it matches the outer tag), but does not match the inner
+            <replaceable>a</replaceable> element in
+            <literal>&lt;b&gt;&lt;a/&gt;&lt;/b&gt;</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>&lt;<replaceable>tag2</replaceable>/&gt;</literal>
+            if and only if it is a child of
+            <literal>&lt;<replaceable>tag1</replaceable>/&gt;</literal>,
+            and
+            <literal>&lt;<replaceable>tag1</replaceable>/&gt;</literal>
+            is the root element.
+          </para>
+          
+          <para>
+            Example: <literal>/a/b</literal> matches the
+            <replaceable>b</replaceable>element in the XML fragment
+            <literal>&lt;a&gt;&lt;b/&gt;&lt;/a&gt;</literal> because it
+            is a child of the root element <replaceable>a</replaceable>.
+            It does not have a match in
+            <literal>&lt;b&gt;&lt;a/&gt;&lt;/b&gt;</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>&lt;a&gt;&lt;c&gt;&lt;b/&gt;&lt;/c&gt;&lt;/a&gt;</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>&lt;a&gt;&lt;b&gt;&lt;c/&gt;&lt;/b&gt;&lt;/a&gt;</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>&lt;a&gt;&lt;b&gt;&lt;c/&gt;&lt;/b&gt;&lt;/a&gt;</literal>;
+            <literal>&lt;c&gt;&lt;a&gt;&lt;b/&gt;&lt;/a&gt;&lt;/b&gt;</literal>;
+            <literal>&lt;c&gt;&lt;b&gt;&lt;a/&gt;&lt;/b&gt;&lt;/c&gt;</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>&lt;a&gt;&lt;b/&gt;&lt;/a&gt;</literal> or
+            <literal>&lt;a&gt;&lt;b&gt;&lt;c/&gt;&lt;/b&gt;&lt;/a&gt;</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>&lt;a&gt;&lt;b/&gt;&lt;/a&gt;</literal>
+            or <literal>&lt;c&gt;&lt;b/&gt;&lt;/c&gt;</literal>.
+            However, the expression does not produce a match in the
+            fragment <literal>&lt;b&gt;&lt;a/&gt;&lt;/b&gt;</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>&lt;a&gt;&lt;b id="idA"/&gt;&lt;&lt;c/&gt;b
+            id="idB"/&gt;&lt;/a&gt;</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.1jon13 Jan