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. By default, the main
  75                                 preferences file
  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="xmlSetValues">xmlSetValues</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>