ad9438b328ae4640e4dbf45862070bbd473e3044
[scilab.git] / scilab / modules / xml / help / en_US / xmlGetValues.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) 2014 - Scilab Enterprises - Calixte DENIZET
5  * Copyright (C) 2017 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="xmlGetValues" xml:lang="en">
21     <refnamediv>
22         <refname>xmlGetValues</refname>
23         <refpurpose>Parses and gets values of chosen tags attributes in a XML file of preferences</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             Values = xmlGetValues(path2tag, attributes)
29             Values = xmlGetValues(path2tag, attributes, XMLsource)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>path2tag</term>
37                 <listitem>
38                     <para>
39                         unique string: in the XML source file, path targeting a chosen tag whose
40                         attributes must be read. The path is the list of nested tags leading to the
41                         required one, such as <literal>"/a/b/c/d"</literal>, or equivalently
42                         <literal>"//b/c/d"</literal>. It is case-sensitive.
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>attributes</term>
48                 <listitem>
49                     <para>
50                         vector or matrix of strings: names of attributes of the chosen tag, whose values
51                         must be read. The order of attributes does not matter wrt their actual order in
52                         the tag.
53                         <note>
54                             <itemizedlist>
55                                 <listitem>
56                                     Attributes names are case-sensitive.
57                                 </listitem>
58                                 <listitem>
59                                     If needed, the name of a given attribute may be specified several times.
60                                 </listitem>
61                             </itemizedlist>
62                         </note>
63                     </para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>XMLsource</term>
68                 <listitem>
69                     <para>
70                         points to the XML document from which informations must be extracted. It
71                         can be one of the following:
72                         <itemizedlist>
73                             <listitem>
74                                 unique string: path to the XML source file (where preferences are
75                                 registered). By default,
76                                 <literal>SCIHOME+'/XConfiguration.xml'</literal> is considered.
77                             </listitem>
78                             <listitem>
79                                 XML handle of type <literal>XMLdoc</literal>, as returned by a
80                                 prior <code>xmlRead(XMLsource)</code> external instruction.
81                             </listitem>
82                         </itemizedlist>
83                     </para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>Values</term>
88                 <listitem>
89                     <para>
90                         matrix of strings: Values of the chosen attributes of the chosen tag:
91                         <itemizedlist>
92                             <listitem>
93                                 If the set of chosen <varname>attributes</varname> is provided as a
94                                 matrix with several rows, then only the first occurrence of the chosen
95                                 tag is considered, and <varname>Values(i,j)</varname> is the value of
96                                 its <varname>attributes(i,j)</varname>.
97                             </listitem>
98                             <listitem>
99                                 Otherwise, if the names of <varname>attributes</varname> are
100                                 provided in a row vector, then
101                                 <emphasis role="italic">all occurences</emphasis> of the chosen tag
102                                 are considered: Results are returned with one row per occurrence,
103                                 and one colum per attribute. Thus, <varname>Values(i,j)</varname>
104                                 is the value of the <varname>attributes(j)</varname> for the
105                                 <literal>
106                                     i<superscript>th</superscript>
107                                 </literal>
108                                 occurrence of the
109                                 tag in the document.
110                             </listitem>
111                         </itemizedlist>
112                         If some final values are expected to be numeric rather than literal (text),
113                         <code>evstr()</code> may be applied to them to get expected numbers.
114                     </para>
115                 </listitem>
116             </varlistentry>
117         </variablelist>
118     </refsection>
119     <refsection>
120         <title>Description</title>
121         <para>
122             When an XML handle returned by <code>xmlRead(..)</code> is provided as
123             <varname>XMLsource</varname>, <function>xmlGetValues()</function> uses it
124             directly to parse the XML Preferences document opened by this prior
125             <code>xmlRead(..)</code>. This is useful when the same document must be parsed with
126             multiple calls to <function>xmlGetValues()</function>, typically to address
127             different XML tags. In this case, one should not forget to close the XML document after
128             its whole processing.
129         </para>
130         <para>
131             When the path of the XML Preferences file is provided as <varname>XMLsource</varname>,
132             <function>xmlGetValues()</function> opens the file, builds its DOM tree, parses
133             the tree for the chosen tag and attributes, and finally deletes the tree and closes the
134             file before returning results. This is what occurs with the default Xconfiguration.xml
135             file when no explicit <varname>XMLsource</varname> is specified.
136         </para>
137         <para>
138             The <varname>path2tag</varname> argument must be a valid "XPath" according to the
139             <ulink url="https://www.w3.org/TR/1999/REC-xpath-19991116/">W3C recommandations</ulink>.
140             Examples are given herebelow. If the path uses a intermediate or a final tag that does
141             not exist, or if one of the queried attributes does not exist, an error is yielded.
142         </para>
143     </refsection>
144     <refsection>
145         <title>Examples</title>
146         <emphasis role="bold">Example 1:</emphasis>
147         <para>
148             Your web and proxy settings for Scilab are stored in the default
149             <literal>SCIHOME+'/XConfiguration.xml'</literal> preferences file. Let's consider the
150             following excerpt of the file:
151             <programlisting role="xml"><![CDATA[
152     <?xml version="1.0" encoding="utf-8" standalone="no"?>
153     <interface height="600" path="1/" version="0.17" width="800">
154         <general title="_(General)">
155         ...
156         </general>
157         <web title="_(Web)">
158             <body>
159                 <web command-browser="" command-mailer="" default-browser="true" default-mailer="true"/>
160                 <proxy enabled="false" host="" password="" port="" user=""/>
161                 <previous-proxy enabled="false" host="" password="" port="" user=""/>
162             </body>
163         </web>
164         ...
165     </interface>
166               ]]></programlisting>
167         </para>
168         <para>
169             To get some informations about the proxy parameters (proxy tag), the required code
170             will be:
171             <programlisting role="scilab"><![CDATA[
172             proxy = xmlGetValues("//web/body/proxy", ["enabled", "host", "port"]);
173      ]]></programlisting>
174         </para>
175         <para>
176             <emphasis role="bold">Example 2:</emphasis>
177         </para>
178         <para>
179             <function>xmlGetValues()</function> can also be used to get values of a tag
180             having multiple occurrences in the <literal>XMLsource</literal> file. For instance,
181             your preferences for the Scilab's editor Scinotes are stored in the
182             <literal>SCIHOME\scinotesConfiguration.xml</literal> file. The list of most recent files
183             opened in Scinotes is stored in the following part and path:
184             <programlisting role="xml"><![CDATA[
185 <?xml version="1.0" encoding="utf-8" standalone="no"?>
186 <Setting version="0.42">
187     <!-- SCINOTES configuration -->
188     <Profile name="scinotes">
189         <!-- .../... -->
190         <!-- Recent Opened Files Section  -->
191         <recentFiles>
192             <document path="C:\Path\to\my\first\working\dir\ged_move_entity.sci"/>
193             <document path="C:\Path\to\my\first\working\dir\ged_loop.sci"/>
194             <document path="C:\Path\to\my\first\working\dir\test_legend_move.sce"/>
195             <document path="C:\Path\to\another\working\dir2\clf.sci"/>
196         </recentFiles>
197         <!-- .../... -->
198     </Profile>
199 </Setting>
200               ]]></programlisting>
201         </para>
202         <para>
203             Then, the following code will extract, return and display the column of recent files:
204             <programlisting role="example"><![CDATA[
205             scinotesFile = SCIHOME + "/scinotesConfiguration.xml";
206             recent = xmlGetValues("//Setting/Profile/recentFiles/document", "path", scinotesFile);
207             mprintf("%s\n", recent)
208      ]]></programlisting>
209             <screen><![CDATA[
210 C:\Path\to\my\first\working\dir\ged_move_entity.sci
211 C:\Path\to\my\first\working\dir\ged_loop.sci
212 C:\Path\to\my\first\working\dir\test_legend_move.sce
213 C:\Path\to\another\working\dir2\clf.sci
214 ]]></screen>
215         </para>
216     </refsection>
217     <refsection role="see also">
218         <title>See also</title>
219         <simplelist type="inline">
220             <member>
221                 <link linkend="setPreferencesValue">setPreferencesValue</link>
222             </member>
223             <member>
224                 <link linkend="xmlXPath">xmlXPath</link>
225             </member>
226             <member>
227                 <ulink url="https://www.w3.org/TR/1999/REC-xpath-19991116/">XML path language</ulink>
228             </member>
229             <member>
230                 <link linkend="xmlRead">xmlRead</link>
231             </member>
232             <member>
233                 <link linkend="xmlDelete">xmlDelete</link>
234             </member>
235             <member>
236                 <link linkend="atomsGetConfig">atomsGetConfig</link>
237             </member>
238             <member>
239                 <link linkend="printsetupbox">printsetupbox</link>
240             </member>
241             <member>
242                 <link linkend="csvDefault">csvDefault</link>
243             </member>
244         </simplelist>
245     </refsection>
246     <refsection role="history">
247         <title>History</title>
248         <revhistory>
249             <revision>
250                 <revnumber>6.0.2</revnumber>
251                 <revdescription>xmlGetValues() introduced, was formerly getPreferencesValue().
252                 </revdescription>
253             </revision>
254         </revhistory>
255     </refsection>
256 </refentry>