* Bug 16148: xmlSetValues() <= setPreferencesValue()
[scilab.git] / scilab / modules / xml / help / en_US / xmlSetValues.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) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2019 - Samuel GOUGEON
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="xmlSetValues" xml:lang="en">
20     <refnamediv>
21         <refname>xmlSetValues</refname>
22         <refpurpose>Sets some attribute=value in an XML document for a given tag/XPath</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             xmlSetValues(xpath, attributes_values)
28             xmlSetValues(xpath, attributes_values, doc)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>xpath</term>
36                 <listitem>
37                     <para>a string: XPath request pointing to the chosen tag in the XML document.</para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>attributes_values</term>
42                 <listitem>
43                     <para>a 2xN matrix of strings: the (attribute,value) pairs to set.</para>
44                 </listitem>
45             </varlistentry>
46         </variablelist>
47         <variablelist>
48             <varlistentry>
49                 <term>doc</term>
50                 <listitem>
51                     <para>
52                         mlist typed XMLDoc: the XML document in which to write values.
53                         By default, it is the main Scilab preferences file
54                         (<literal>SCIHOME + '/XConfiguration.xml'</literal>).
55                     </para>
56                 </listitem>
57             </varlistentry>
58         </variablelist>
59     </refsection>
60     <refsection>
61         <title>Description</title>
62         <para>
63             When no explicit XML document <varname>doc</varname> is indicated,
64             <literal>xmlSetValues</literal> opens the main Scilab preferences file
65             <literal>SCIHOME + '/XConfiguration.xml'</literal>, looks for the tag pointed to by
66             <varname>xpath</varname>, updates some of its attributes and related values as
67             provided by <varname>attributes_values</varname>, and closes the file.
68         </para>
69         <para>
70             <literal>xmlSetValues</literal> can also be used on-the-fly on an already open XML
71             document <varname>doc</varname>. In this case, the document is kept open after
72             leaving <literal>xmlSetValues</literal>. This mode is useful when several
73             tags must be updated in the same document.
74         </para>
75         <para>
76             Attributes to update must already exist for the given tag.
77             <literal>xmlSetValues</literal> is not able to create new ones.
78         </para>
79         <para>
80             All valid XPath requests are possible. For example to write the XPath request to
81             set proxy settings in the main Scilab configuration file:
82         </para>
83         <simplelist type="inline">
84             <member>
85                 <para>
86                     Opens <literal>SCIHOME+'/XConfiguration.xml'</literal> and gets the
87                     nodes names to access to the expected node:
88                 </para>
89                 <programlisting role="xml"><![CDATA[
90 <?xml version="1.0" encoding="utf-8" standalone="no"?>
91 <interface height="600" path="1/" version="0.17" width="800">
92     <general title="_(General)">
93     ...
94     </general>
95     <web title="_(Web)">
96         <body>
97             <web command-browser="" command-mailer="" default-browser="true" default-mailer="true"/>
98             <proxy enabled="false" host="" password="" port="" user=""/>
99             <previous-proxy enabled="false" host="" password="" port="" user=""/>
100         </body>
101     </web>
102     ...
103 </interface>
104           ]]></programlisting>
105                 <para>
106                     The path will be <literal>"/interface/web/body/proxy"</literal>
107                     (or to simplify <literal>"//web/body/proxy"</literal>).
108                 </para>
109             </member>
110         <warning>
111             Modifying incorrectly some preferences can alter the Scilab's behaviour.
112         </warning>
113         </simplelist>
114     </refsection>
115     <refsection>
116         <title>Examples</title>
117         <programlisting role="example"><![CDATA[
118 // Get the current values
119 prev = xmlGetValues("//web/body/proxy", ["enabled", "host", "port"]);
120 xmlSetValues("//web/body/proxy", ["enabled", "host", "port"; "true", "my.proxy.org", "1234"]);
121
122 // Ok that's work
123 xmlGetValues("//web/body/proxy", ["enabled", "host", "port"])
124
125 // We restore the previous values
126 xmlSetValues("//web/body/proxy", ["enabled", "host", "port" ; prev]);
127 xmlGetValues("//web/body/proxy", ["enabled", "host", "port"])
128  ]]></programlisting>
129     </refsection>
130     <refsection role="see also">
131         <title>See also</title>
132         <simplelist type="inline">
133             <member>
134                 <link linkend="xmlGetValues">xmlGetValues</link>
135             </member>
136         </simplelist>
137     </refsection>
138     <refsection role="history">
139         <title>History</title>
140         <revhistory>
141             <revision>
142                 <revnumber>6.1.0</revnumber>
143                 <revdescription>
144                     xmlSetValues() introduced, replacing setPreferencesValue().
145                 </revdescription>
146             </revision>
147         </revhistory>
148     </refsection>
149 </refentry>