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