List:Commits« Previous MessageNext Message »
From:jon Date:January 13 2006 4:10am
Subject:svn commit - mysqldoc@docsrva: r798 - in trunk: refman-5.1 refman-common
View as plain text  
Author: jstephens
Date: 2006-01-13 05:10:07 +0100 (Fri, 13 Jan 2006)
New Revision: 798

Log:

Documenting new XPath functions ExtractValue() and UpdateXML() in 5.1.5
(Thanks, Bar!)



Modified:
   trunk/refman-5.1/functions.xml
   trunk/refman-common/news-5.1.xml
   trunk/refman-common/titles.en.ent

Modified: trunk/refman-5.1/functions.xml
===================================================================
--- trunk/refman-5.1/functions.xml	2006-01-13 04:00:46 UTC (rev 797)
+++ trunk/refman-5.1/functions.xml	2006-01-13 04:10:07 UTC (rev 798)
@@ -13653,7 +13653,265 @@
       </itemizedlist>
 
     </section>
+    
+    <section id="xml-functions">
+      <title>&title-xml-functions;</title>
+      
+      <para>
+        Beginning with MySQL 5.1.5, two functions providing basic XPath
+        (XML Path Language) capabilities are available.
+      </para>
+      
+      <itemizedlist>
+        <listitem>
+          <remark role="help-topic" condition="VALUES"/>
 
+          <remark role="help-syntax-begin"/>
+
+          <para>
+            <indexterm type="function">
+              <primary>ExtractValue()</primary>
+            </indexterm>
+
+            <literal>ExtractValue(<replaceable>xml_frag</replaceable>,
+              <replaceable>xpath_expr</replaceable>)</literal>
+          </para>
+
+          <remark role="help-syntax-end"/>
+
+          <remark role="help-description-begin"/>
+          
+          <para>
+            This function takes two string arguments, a fragment of XML
+            markup <replaceable>xml_frag</replaceable> and an XPath
+            expression <replaceable>xpath_expr</replaceable>, and returns
+            the value matched by <replaceable>xpath_expr</replaceable>.
+            If no match for <replaceable>xpath_expr</replaceable> is
+            found, this function returns an empty string.
+          </para>
+
+          <remark role="help-description-end"/>
+
+          <remark role="help-example"/>
+          
+<programlisting>
+mysql&gt; <userinput>SELECT</userinput>
+    -&gt;    <userinput>ExtractValue('&lt;a&gt;ccc&lt;b&gt;ddd&lt;/b&gt;&lt;/a&gt;', '/a') AS val1,</userinput>
+    -&gt;    <userinput>ExtractValue('&lt;a&gt;ccc&lt;b&gt;ddd&lt;/b&gt;&lt;/a&gt;', '/a/b') AS val2,</userinput>
+    -&gt;    <userinput>ExtractValue('&lt;a&gt;ccc&lt;b&gt;ddd&lt;/b&gt;&lt;/a&gt;', '//b') AS val3,</userinput>
+    -&gt;    <userinput>ExtractValue('&lt;a&gt;ccc&lt;b&gt;ddd&lt;/b&gt;&lt;/a&gt;', '/b') AS val4;</userinput>
+
++------+------+------+------+
+| val1 | val2 | val3 | val4 |
++------+------+------+------+
+| ccc  | ddd  | ddd  |      |
++------+------+------+------+
+</programlisting>
+        </listitem>
+        
+        <listitem>          
+          <remark role="help-topic" condition="VALUES"/>
+
+          <remark role="help-syntax-begin"/>
+
+          <para>
+            <indexterm type="function">
+              <primary>UpdateXML()</primary>
+            </indexterm>
+
+            <literal>UpdateXML(<replaceable>xml_target</replaceable>,
+              <replaceable>xpath_expr</replaceable>,
+              <replaceable>new_xml</replaceable>)</literal>
+          </para>
+
+          <remark role="help-syntax-end"/>
+
+          <remark role="help-description-begin"/>
+          
+          <para>
+            This function replaces a portion of a given fragment of XML
+            markup <replaceable>xml_target</replaceable> with a new XML
+            fragment <replaceable>new_xml</replaceable> and then returns
+            the changed XML. The portion of
+            <replaceable>xml_target</replaceable> that is replaced
+            matches an XPath expression
+            <replaceable>xpath_expr</replaceable> supplied by the user.
+            If no expression matching
+            <replaceable>xpath_expr</replaceable> is found, then the
+            function returns the original
+            <replaceable>xml_target</replaceable> XML fragment. All
+            three arguments must be strings.
+          </para>
+
+          <remark role="help-description-end"/>
+
+          <remark role="help-example"/>
+          
+<programlisting>
+mysql&gt; <userinput>SELECT</userinput>
+    -&gt;     <userinput>UpdateXML('&lt;a&gt;&lt;b&gt;ccc&lt;/b&gt;&lt;d&gt;&lt;/d&gt;&lt;/a&gt;', '/a', '&lt;e&gt;fff&lt;/e&gt;') AS val1,</userinput>
+    -&gt;     <userinput>UpdateXML('&lt;a&gt;&lt;b&gt;ccc&lt;/b&gt;&lt;d&gt;&lt;/d&gt;&lt;/a&gt;', '/b', '&lt;e&gt;fff&lt;/e&gt;') AS val2,</userinput>
+    -&gt;     <userinput>UpdateXML('&lt;a&gt;&lt;b&gt;ccc&lt;/b&gt;&lt;d&gt;&lt;/d&gt;&lt;/a&gt;', '//b', '&lt;e&gt;fff&lt;/e&gt;') AS val3,</userinput>
+    -&gt;     <userinput>UpdateXML('&lt;a&gt;&lt;b&gt;ccc&lt;/b&gt;&lt;d&gt;&lt;/d&gt;&lt;/a&gt;', '/a/d', '&lt;e&gt;fff&lt;/e&gt;') AS val4</userinput>
+    -&gt; <userinput>\G</userinput>
+
+*************************** 1. row ***************************
+val1: &lt;e&gt;fff&lt;/e&gt;
+val2: &lt;a&gt;&lt;b&gt;ccc&lt;/b&gt;&lt;d&gt;&lt;/d&gt;&lt;/a&gt;
+val3: &lt;a&gt;&lt;e&gt;fff&lt;/e&gt;&lt;d&gt;&lt;/d&gt;&lt;/a&gt;
+val4: &lt;a&gt;&lt;b&gt;ccc&lt;/b&gt;&lt;e&gt;fff&lt;/e&gt;&lt;/a&gt;
+</programlisting>
+        </listitem>
+      </itemizedlist>
+      
+      <para>
+        The XPath syntax supported by these functions is currently
+        subject to the following limitations:
+      </para>
+      
+      <itemizedlist>
+        <listitem>
+          <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.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            The following XPath functions are not supported:
+          </para>
+          
+          <itemizedlist>
+            <listitem>
+              <para>
+                <literal>id()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>lang()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>last()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>local-name()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>name()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>namespace-uri()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>normalize-space()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>starts-with()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>string()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>substring-after()</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>substring-before()</literal>
+              </para>
+            </listitem>    
+            
+            <listitem>
+              <para>
+                <literal>translate()</literal>
+              </para>
+            </listitem>        
+          </itemizedlist>
+          
+        </listitem>
+        
+        <listitem>
+          <para>
+            The following axes are not supported:
+          </para>
+          
+          <itemizedlist>
+            <listitem>
+              <para>
+                <literal>following-sibling</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>following</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>preceding-sibling</literal>
+              </para>
+            </listitem>
+            
+            <listitem>
+              <para>
+                <literal>preceding</literal>
+              </para>
+            </listitem>            
+          </itemizedlist>          
+        </listitem>        
+      </itemizedlist>
+      
+      <para>
+        We continue to develop and improve these and other aspects of
+        XML/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>
+    
+    
   </section>
 
   <section id="group-by-functions-and-modifiers">

Modified: trunk/refman-common/news-5.1.xml
===================================================================
--- trunk/refman-common/news-5.1.xml	2006-01-13 04:00:46 UTC (rev 797)
+++ trunk/refman-common/news-5.1.xml	2006-01-13 04:10:07 UTC (rev 798)
@@ -99,6 +99,19 @@
     </para>
 
     <itemizedlist>
+      
+      <listitem>
+        <para>
+          Added the XML functions <literal>ExtractValue()</literal> and
+          <literal>UpdateXML()</literal>.
+          <literal>ExtractValue()</literal> returns the content of a
+          fragment of XML matching a given XPath expression.
+          <literal>UpdateXML()</literal> replaces the element selected
+          from a fragment of XML by an XPath expression supplied by the
+          user with a second XML fragment (also user-supplied), and
+          returns the modified XML. See <xref linkend="xml-functions"/>.   
+        </para>
+      </listitem>
 
       <listitem>
         <para>

Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent	2006-01-13 04:00:46 UTC (rev 797)
+++ trunk/refman-common/titles.en.ent	2006-01-13 04:10:07 UTC (rev 798)
@@ -1715,6 +1715,7 @@
 <!ENTITY title-xa-restrictions "Restrictions on XA Transactions">
 <!ENTITY title-xa-statements "XA Transaction SQL Syntax">
 <!ENTITY title-xa-states "XA Transaction States">
+<!ENTITY title-xml-functions "XML Functions">
 <!ENTITY title-y2k-issues "Y2K Issues and Date Types">
 <!ENTITY title-year "The <literal>YEAR</literal> Type">
 <!ENTITY title-year-2000-compliance "Year 2000 Compliance">

Thread
svn commit - mysqldoc@docsrva: r798 - in trunk: refman-5.1 refman-commonjon13 Jan