[doc] misc. patchs & small improvements
[scilab.git] / scilab / modules / xml / help / ru_RU / 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="ru">
21     <refnamediv>
22         <refname>xmlGetValues</refname>
23         <refpurpose>
24             Проводит синтаксическую проверку и получает значения атрибутов выбранных тегов в
25             XML-файле настроек
26         </refpurpose>
27     </refnamediv>
28     <refsynopsisdiv>
29         <title>Синтаксис</title>
30         <synopsis>
31             Values = xmlGetValues(path2tag, attributes)
32             Values = xmlGetValues(path2tag, attributes, XMLsource)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Аргументы</title>
37         <variablelist>
38             <varlistentry>
39                 <term>path2tag</term>
40                 <listitem>
41                     <para>
42                         уникальная строка: в файле исходного XML-кода, путь, указывающий на выбранный тег,
43                         чьи атрибуты нужно прочитать. Путь является списком вложенных тегов, стоящих спереди
44                         от требуемого так, что <literal>"/a/b/c/d"</literal>, или, эквивалентно,
45                         <literal>"//b/c/d"</literal>. Регистр учитывается.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>attributes</term>
51                 <listitem>
52                     <para>
53                         вектор или матрица строк: имена атрибуты выбранного тега, чьи значения нужно прочитать.
54                         Порядок атрибутов не имеет значения относительно их фактического порядка в теге.
55                         <note>
56                             <itemizedlist>
57                                 <listitem>
58                                     Имена атрибутов чувствительны к регистру.
59                                 </listitem>
60                                 <listitem>
61                                     На самом деле имена указанного атрибута могут быть
62                                     определены несколько раз.
63                                 </listitem>
64                             </itemizedlist>
65                         </note>
66                     </para>
67                 </listitem>
68             </varlistentry>
69             <varlistentry>
70                 <term>XMLsource</term>
71                 <listitem>
72                     <para>
73                         указывает на XML-документ из которого нужно извлечь информацию.
74                         Это может быть одно из следующих:
75                         <itemizedlist>
76                             <listitem>
77                                 уникальная строка: путь до исходного XML-файла. По умолчанию
78                                 рассматривается файл главных настроек
79                                 <literal>SCIHOME+'/XConfiguration.xml'</literal>.
80                             </listitem>
81                             <listitem>
82                                 XML-указатель типа <literal>XMLdoc</literal>, возвращаемой
83                                 ранее в качестве внешней инструкции <code>xmlRead(XMLsource)</code>,
84                             </listitem>
85                         </itemizedlist>
86                     </para>
87                 </listitem>
88             </varlistentry>
89             <varlistentry>
90                 <term>Values</term>
91                 <listitem>
92                     <para>
93                         матрица строковых значений: значения выбранных атрибутов выбранного тега:
94                         <itemizedlist>
95                             <listitem>
96                                 Если набор выбранных атрибутов <varname>attributes</varname> 
97                                 указан в виде матрицы с несколькими строками, то используется
98                                 только первое появление выбранного тега, и <varname>Values(i,j)</varname> - это
99                                 значение его атрибутов <varname>attributes(i,j)</varname>.
100                             </listitem>
101                             <listitem>
102                                 В противном случае, если имена атрибутов <varname>attributes</varname>
103                                 указаны в виде вектора-строки, то рассматриваются
104                                 <emphasis role="italic">все появления</emphasis> выбранного тега: 
105                                 результаты возвращаются с одной строкой на появление, и одним
106                                 столбцом на атрибут. Таким образом, <varname>Values(i,j)</varname> - это
107                                 значение атрибутов <varname>attributes(j)</varname> для
108                                 <literal>i</literal>-той встречи тега в документе.
109                             </listitem>
110                         </itemizedlist>
111                         Если ожидаются какие-либо конечные значения в виде чисел, а не литералов
112                         (текста), то <code>evstr()</code> может быть применён к ним для получения
113                         ожидаемых чисел.
114                     </para>
115                 </listitem>
116             </varlistentry>
117         </variablelist>
118     </refsection>
119     <refsection>
120         <title>Описание</title>
121         <para>
122             Когда XML-указатель, возвращённый с помощью <code>xmlRead(..)</code>, указан
123             в качестве <varname>XMLsource</varname>, то <function>xmlGetValues()</function>
124             исползует его напрямую для проверки синтаксиса  XML-документа настроек, открытого
125             ранее с помощью <code>xmlRead(..)</code>. Это полезно, когда синтаксис одного и того
126             же документа нужно проверить множеством вызовов <function>xmlGetValues()</function>,
127             обычно для обращения к разным XML-тегам. В этом случае не следует забывать
128             закрыть XML-документ после всей обработки.
129         </para>
130         <para>
131             Когда путь до XML-файла настроек указан в качестве <varname>XMLsource</varname>,
132             то <function>xmlGetValues()</function> открывает файл, строит его DOM-дерево,
133             проверяет синтаксис дерева для выбранного тега и атрибутов, и, наконец, удаляет
134             дерево и закрывает файл перед тем, как вернуть результаты. Это то, что происходит
135             по умолчанию в соответствии с файлом настроек Xconfiguration.xml, когда нет явного
136             указания <varname>XMLsource</varname>.
137         </para>
138         <para>
139             Аргумент <varname>path2tag</varname> должен быть корректным путём "XPath",
140             соответствующим <ulink url="https://www.w3.org/TR/1999/REC-xpath-19991116/">рекомендациям W3C</ulink>.
141             Далее приведены примеры. Если путь исползует промежуточный или конечный тег, который
142             не существует, или, если один из ряда атрибутов не существует, то выдаётся ошибка.
143         </para>
144     </refsection>
145     <refsection>
146         <title>Примеры</title>
147         <emphasis role="bold">Пример 1:</emphasis>
148         <para>
149             Ваши интернет- и прокси-настройки для Scilab хранятся по умолчанию в файле настроек
150             <literal>SCIHOME+'/XConfiguration.xml'</literal>. Рассмотрим следующий отрывок файла:
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             Чтобы получить информацию прокси-параметров (тег proxy), требуемый код должен быть:
170             <programlisting role="scilab"><![CDATA[
171             proxy = xmlGetValues("//web/body/proxy", ["enabled", "host", "port"]);
172      ]]></programlisting>
173         </para>
174         <para>
175             <emphasis role="bold">Пример 2:</emphasis>
176         </para>
177         <para>
178             <function>xmlGetValues()</function> может также использоваться для получения значений
179             тега, имеющих множество появлений в файле <literal>XMLsource</literal>. Например,
180             ваши настройки в редакторе Scinotes Scilab'а хэранятся в файле
181             <literal>SCIHOME\scinotesConfiguration.xml</literal>. Список последних файлов,
182             открытых в Scinotes в следующей части и пути:
183             <programlisting role="xml"><![CDATA[
184 <?xml version="1.0" encoding="utf-8" standalone="no"?>
185 <Setting version="0.42">
186     <!-- SCINOTES configuration -->
187     <Profile name="scinotes">
188         <!-- .../... -->
189         <!-- Recent Opened Files Section  -->
190         <recentFiles>
191             <document path="C:\Path\to\my\first\working\dir\ged_move_entity.sci"/>
192             <document path="C:\Path\to\my\first\working\dir\ged_loop.sci"/>
193             <document path="C:\Path\to\my\first\working\dir\test_legend_move.sce"/>
194             <document path="C:\Path\to\another\working\dir2\clf.sci"/>
195         </recentFiles>
196         <!-- .../... -->
197     </Profile>
198 </Setting>
199               ]]></programlisting>
200         </para>
201         <para>
202             Тогда следующий год извлечёт, вернёт и выведет на экран столбец недавних файлов:
203             <programlisting role="example"><![CDATA[
204             scinotesFile = SCIHOME + "/scinotesConfiguration.xml";
205             recent = xmlGetValues("//Setting/Profile/recentFiles/document", "path", scinotesFile);
206             mprintf("%s\n", recent)
207      ]]></programlisting>
208             <screen><![CDATA[
209 C:\Path\to\my\first\working\dir\ged_move_entity.sci
210 C:\Path\to\my\first\working\dir\ged_loop.sci
211 C:\Path\to\my\first\working\dir\test_legend_move.sce
212 C:\Path\to\another\working\dir2\clf.sci
213 ]]></screen>
214         </para>
215     </refsection>
216     <refsection role="see also">
217         <title>Смотрите также</title>
218         <simplelist type="inline">
219             <member>
220                 <link linkend="setPreferencesValue">setPreferencesValue</link>
221             </member>
222             <member>
223                 <link linkend="xmlXPath">xmlXPath</link>
224             </member>
225             <member>
226                 <ulink url="https://www.w3.org/TR/1999/REC-xpath-19991116/">язык XML-пути</ulink>
227             </member>
228             <member>
229                 <link linkend="xmlRead">xmlRead</link>
230             </member>
231             <member>
232                 <link linkend="xmlDelete">xmlDelete</link>
233             </member>
234             <member>
235                 <link linkend="atomsGetConfig">atomsGetConfig</link>
236             </member>
237             <member>
238                 <link linkend="printsetupbox">printsetupbox</link>
239             </member>
240             <member>
241                 <link linkend="csvDefault">csvDefault</link>
242             </member>
243         </simplelist>
244     </refsection>
245     <refsection role="history">
246         <title>История</title>
247         <revhistory>
248             <revision>
249                 <revnumber>6.0.2</revnumber>
250                 <revdescription>
251                     Введена xmlGetValues(), которая раньше была getPreferencesValue().
252                 </revdescription>
253             </revision>
254         </revhistory>
255     </refsection>
256 </refentry>