xmlGetValues

Parses and gets values of chosen tags attributes in a XML file of preferences

Syntax

Values = xmlGetValues(path2tag, attributes)
Values = xmlGetValues(path2tag, attributes, XMLsource)

Arguments

path2tag

unique string: in the XML source file, path targeting a chosen tag whose attributes must be read. The path is the list of nested tags leading to the required one, such as "/a/b/c/d", or equivalently "//b/c/d". It is case-sensitive.

attributes

vector or matrix of strings: names of attributes of the chosen tag, whose values must be read. The order of attributes does not matter wrt their actual order in the tag.

Attributes names are case-sensitive.
If needed, the name of a given attribute may be specified several times.

XMLsource

points to the XML document from which informations must be extracted. It can be one of the following:

unique string: path to the XML source file (where preferences are registered). By default, SCIHOME+'/XConfiguration.xml' is considered.
XML handle of type XMLdoc, as returned by a prior xmlRead(XMLsource) external instruction.

Values

matrix of strings: Values of the chosen attributes of the chosen tag:

If the set of chosen attributes is provided as a matrix with several rows, then only the first occurrence of the chosen tag is considered, and Values(i,j) is the value of its attributes(i,j).
Otherwise, if the names of attributes are provided in a row vector, then all occurences of the chosen tag are considered: Results are returned with one row per occurrence, and one colum per attribute. Thus, Values(i,j) is the value of the attributes(j) for the i^th occurrence of the tag in the document.

If some final values are expected to be numeric rather than literal (text), evstr() may be applied to them to get expected numbers.

Description

When an XML handle returned by xmlRead(..) is provided as XMLsource, xmlGetValues() uses it directly to parse the XML Preferences document opened by this prior xmlRead(..). This is useful when the same document must be parsed with multiple calls to xmlGetValues(), typically to address different XML tags. In this case, one should not forget to close the XML document after its whole processing.

When the path of the XML Preferences file is provided as XMLsource, xmlGetValues() opens the file, builds its DOM tree, parses the tree for the chosen tag and attributes, and finally deletes the tree and closes the file before returning results. This is what occurs with the default Xconfiguration.xml file when no explicit XMLsource is specified.

The path2tag argument must be a valid "XPath" according to the W3C recommandations. Examples are given herebelow. If the path uses a intermediate or a final tag that does not exist, or if one of the queried attributes does not exist, an error is yielded.

Examples

Example 1:

Your web and proxy settings for Scilab are stored in the default SCIHOME+'/XConfiguration.xml' preferences file. Let's consider the following excerpt of the file:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<interface height="600" path="1/" version="0.17" width="800">
    <general title="_(General)">
    ...
    </general>
    <web title="_(Web)">
        <body>
            <web command-browser="" command-mailer="" default-browser="true" default-mailer="true"/>
            <proxy enabled="false" host="" password="" port="" user=""/>
            <previous-proxy enabled="false" host="" password="" port="" user=""/>
        </body>
    </web>
    ...
</interface>

To get some informations about the proxy parameters (proxy tag), the required code will be:

proxy = xmlGetValues("//web/body/proxy", ["enabled", "host", "port"]);

Example 2:

xmlGetValues() can also be used to get values of a tag having multiple occurrences in the XMLsource file. For instance, your preferences for the Scilab's editor Scinotes are stored in the SCIHOME\scinotesConfiguration.xml file. The list of most recent files opened in Scinotes is stored in the following part and path:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<Setting version="0.42">
    <!-- SCINOTES configuration -->
    <Profile name="scinotes">
        <!-- .../... -->
        <!-- Recent Opened Files Section  -->
        <recentFiles>
            <document path="C:\Path\to\my\first\working\dir\ged_move_entity.sci"/>
            <document path="C:\Path\to\my\first\working\dir\ged_loop.sci"/>
            <document path="C:\Path\to\my\first\working\dir\test_legend_move.sce"/>
            <document path="C:\Path\to\another\working\dir2\clf.sci"/>
        </recentFiles>
        <!-- .../... -->
    </Profile>
</Setting>

Then, the following code will extract, return and display the column of recent files:

scinotesFile = SCIHOME + "/scinotesConfiguration.xml";
recent = xmlGetValues("//Setting/Profile/recentFiles/document", "path", scinotesFile);
mprintf("%s\n", recent)

C:\Path\to\my\first\working\dir\ged_move_entity.sci
C:\Path\to\my\first\working\dir\ged_loop.sci
C:\Path\to\my\first\working\dir\test_legend_move.sce
C:\Path\to\another\working\dir2\clf.sci

History

Version	Description
6.0.2	xmlGetValues() introduced, was formerly getPreferencesValue().

Report an issue
<< xmlGetOpenDocs	Traitement XML	xmlIsValidObject >>

Copyright (c) 2022-2024 (Dassault Systèmes)
Copyright (c) 2017-2022 (ESI Group)
Copyright (c) 2011-2017 (Scilab Enterprises)
Copyright (c) 1989-2012 (INRIA)
Copyright (c) 1989-2007 (ENPC)
with contributors

Last updated:
Thu Feb 14 14:59:58 CET 2019