scilab/modules/xml/help/en_US/xmlXPath.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) 2012 - Scilab Enterprises - Calixte DENIZET
   5  *
   6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   7  *
   8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
   9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  10  * This file was originally licensed under the terms of the CeCILL v2.1,
  11  * and continues to be available under such terms.
  12  * For more information, see the COPYING file which you should have received
  13  * along with this program.
  14  *
  15 -->
  16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  17         xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
  18         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
  19         xmlns:scilab="http://www.scilab.org" xml:id="xmlXPath" xml:lang="en">
  20     <refnamediv>
  21         <refname>xmlXPath</refname>
  22         <refpurpose>Make a XPath query on a XML document</refpurpose>
  23     </refnamediv>
  24     <refsynopsisdiv>
  25         <title>Syntax</title>
  26         <synopsis>
  27             result = xmlXPath(xmlObj, queryStr)
  28             result = xmlXPath(xmlObj, queryStr, namespaces)
  29         </synopsis>
  30     </refsynopsisdiv>
  31     <refsection>
  32         <title>Arguments</title>
  33         <variablelist>
  34             <varlistentry>
  35                 <term>xmlObj</term>
  36                 <listitem>
  37                     <para>a XML mlist typed XMLDoc or XMLElem</para>
  38                 </listitem>
  39             </varlistentry>
  40             <varlistentry>
  41                 <term>queryStr</term>
  42                 <listitem>
  43                     <para>a Xpath query</para>
  44                 </listitem>
  45             </varlistentry>
  46             <varlistentry>
  47                 <term>namespaces</term>
  48                 <listitem>
  49                     <para>An optional matrix nx2 of strings</para>
  50                 </listitem>
  51             </varlistentry>
  52             <varlistentry>
  53                 <term>result</term>
  54                 <listitem>
  55                     <para>result can be a set of XMLElements or a number or a string or a boolean</para>
  56                 </listitem>
  57             </varlistentry>
  58         </variablelist>
  59     </refsection>
  60     <refsection>
  61         <title>Description</title>
  62         <para>
  63             Make a XPath query on a document or in starting on an element. If you need to use
  64             namespaces, then you must define them in using the optional argument. XML namespaces are
  65             defined in the first tag with the keyword "xmlns".
  66         </para>
  67         <para>
  68             For more information about XPath, you can read the
  69             <ulink url="http://www.w3.org/TR/1999/REC-xpath-19991116/">W3C recommandation</ulink>.
  70         </para>
  71     </refsection>
  72     <refsection>
  73         <title>Examples</title>
  74         <programlisting role="example"><![CDATA[
  75     doc = xmlRead("http://www.w3.org/TR/2009/REC-xml-names-20091208/xml-names-10-3e.xml");
  76
  77     // Retrieve the nodes with name equal to "note"
  78     xp = xmlXPath(doc, "//note");
  79     s = size(xp);
  80     for i=1:s(2)
  81         xmlDump(xp(i))
  82     end
  83
  84     // Count the nodes with name equal to "note"
  85     xp = xmlXPath(doc, "count(//note)")
  86
  87     // Retrieve the node with id="Philosophy"
  88     xp = xmlXPath(doc, "//*[@id=""Philosophy""]");
  89     s = size(xp);
  90     if (s(2) <> 0) then
  91         xmlDump(xp(1))
  92     end
  93
  94     // Retrieve the nodes with an attribute num equal to the number 5
  95     xp = xmlXPath(doc, "//*[number(@num)=5]");
  96     s = size(xp);
  97     if (s(2) <> 0) then
  98         xmlDump(xp(1))
  99     end
 100
 101     // Get the name and the content of all the attributes of nodes named 'emph'
 102     xp = xmlXPath(doc, "//emph/@*");
 103     xp.name
 104     xp.content
 105
 106     xmlDelete(doc);
 107
 108     // Query using namespaces
 109     t = "<root xmlns:scilab=""http://www.scilab.org"">"+..
 110         "<scilab:a att=""foo"" rib=""bar"">"+..
 111         "<b>Hello</b></scilab:a></root>"
 112     doc = xmlReadStr(t);
 113
 114     // We search for element named a
 115     xmlXPath(doc, "//a") // => nothing
 116     xmlXPath(doc, "//scilab:a", ["scilab" "http://www.scilab.org"]) // => OK
 117
 118     // This code will fail:
 119     // xmlXPath(doc, "//scilab:a") // => error
 120
 121     xmlDelete(doc);
 122
 123     // Query starting on an element
 124     t = "<root att=""attribute""><a a1=""A1"" a2=""A2"" a3=""A3"">"+..
 125         "<b>Hello</b><c>Scilab</c><b>World</b></a><b>Nothing</b></root>"
 126     doc = xmlReadStr(t);
 127     e = doc.root.children(1);
 128
 129     // Get the attributes of e
 130     xp = xmlXPath(e, "@*");
 131     xmlAsText(xp)
 132
 133     // Get the 'b' from e
 134     xp = xmlXPath(e, "b");
 135     xmlAsText(xp)
 136
 137     xmlDelete(doc);
 138     ]]></programlisting>
 139     <para>
 140         <emphasis role="bold">Getting the XML comments:</emphasis>
 141     </para>
 142     <programlisting ole="example"><![CDATA[
 143     doc = xmlRead(SCI+"/modules/ui_data/etc/newsfeed.xml");
 144     c = xmlXPath(doc, "//comment()");   // do not forget the trailing ()
 145     c.content'
 146
 147     xmlDelete(doc);
 148     ]]></programlisting>
 149     <screen><![CDATA[
 150 --> c.content'
 151  ans  =
 152 ! RSS Feed URL                                                        !
 153 ! automatic news change interval time (in ms), set to -1 to disable   !
 154 ! periodic feed update interval time (in ms), set to -1 to disable    !
 155 ]]></screen>
 156     </refsection>
 157     <refsection role="see also">
 158         <title>See also</title>
 159         <simplelist type="inline">
 160             <member>
 161                 <ulink url="http://www.w3.org/TR/1999/REC-xpath-19991116/">W3C XPath recommandation</ulink>
 162             </member>
 163             <member>
 164                 <ulink url="https://www.w3schools.com/xml/xpath_intro.asp">XPath tutorial</ulink>
 165             </member>
 166         </simplelist>
 167     </refsection>
 168     <refsection>
 169         <title>History</title>
 170         <revhistory>
 171             <revision>
 172                 <revnumber>5.4.0</revnumber>
 173                 <revremark>XML module introduced.</revremark>
 174             </revision>
 175         </revhistory>
 176     </refsection>
 177 </refentry>