[doc] misc. fix & improvements
[scilab.git] / 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>