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.1.x
 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 recommendations</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="xmlSetValues">xmlSetValues</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.1.x
 280                 </revdescription>
 281             </revision>
 282         </revhistory>
 283     </refsection>
 284 </refentry>