[doc] restore (and update) en_US plot.xml after f88f57f
[scilab.git] / scilab / modules / functions / help / ru_RU / libraries / library.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) ????-2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2021 - 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:db="http://docbook.org/ns/docbook"
18           xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="library">
19     <refnamediv>
20         <refname>library</refname>
21         <refpurpose>тип данных библиотеки</refpurpose>
22     </refnamediv>
23     <refsection>
24         <title>Описание</title>
25         <para>
26             <emphasis role="bold">
27                 Из чего сделана библиотека функций, написанных на языке Scilab?
28             </emphasis>
29         </para>
30         <para>
31             Такая библиотека сделана из директории, содержащей
32             <itemizedlist>
33                 <listitem>
34                     редактируемый XML-файл, который всегда называется <literal>lib</literal>.
35                     Этот файл содержит
36                     <orderedlist>
37                         <listitem>
38                             имя библиотеки;
39                         </listitem>
40                         <listitem>
41                             список имён публичных функций, принадлежащих библиотеке.
42                         </listitem>
43                     </orderedlist>
44                     Этот файл сгенерирован с помощью <literal>genlib(..)</literal>.
45                     Его нельзя сделать вручную.
46                     <para/>
47                 </listitem>
48                 <listitem>
49                     набор двоичных файлов с расширением <literal>.bin</literal>,
50                     чьи основные имена являются именами функций возможно зарегистрированных
51                     в файле <literal>lib</literal>,
52                     <para/>
53                 </listitem>
54                 <listitem>
55                     и возможно -- но это необязательно для загрузки и использования
56                     библиотеки --, <literal>.sci</literal>-файлы исходников, написанные
57                     на языке Scilab, чья компиляция с помощью <code>genlib(..)</code>
58                     генерирует файлы <literal>lib</literal> и <literal>.bin</literal>.
59                     <para/>
60                     <warning>
61                         Если файл-исходник <literal>foo.sci</literal> функции
62                         <literal>foo()</literal> не предоставлен в директории библиотеки,
63                         то <literal>edit foo</literal> не может править его Scilab-код
64                         и откроет пустой файл с нуля.
65                     </warning>
66                     <para/>
67                 </listitem>
68             </itemizedlist>
69         </para>
70         <para>
71             <emphasis role="bold">
72                 Загрузка / декларирование библиотеки в сессии
73             </emphasis>:
74         </para>
75         <para>
76             <literal>load("/path/to/lib")</literal> загружает предназначенную библиотеку
77             в сессию Scilab: создаётся переменная, чьё имя является именем библиотеки
78             -- скажем <literal>libname</literal>. Относящийся к ней тип
79             <literal>type(libname)</literal> равен 14. Её <literal>typeof(libname)</literal>
80             соответствует <literal>"library"</literal>. Этот дескриптор библиотеки содержит
81             <itemizedlist>
82                 <listitem>
83                     путь к корневой директории библиотеки;
84                 </listitem>
85                 <listitem>
86                     список имён публичных функций, принадлежащих библиотеке.
87                 </listitem>
88             </itemizedlist>
89         </para>
90         <para>
91             Обе части могут быть получены либо с помощью функции <literal>libraryinfo()</literal>,
92             либо с помощью функции <literal>string()</literal>.
93         </para>
94         <para>
95             Пример: <literal>interpolationlib</literal> является родной библиотекой Scilab:
96             <screen>
97 --> interpolationlib
98  interpolationlib  =
99
100 Functions files location : SCI\modules\interpolation\macros\.
101 interp1  mesh2d  interpln  smooth
102
103 --> type(interpolationlib)
104  ans  =
105    14.
106
107 --> [typeof(interpolationlib), typeof(interpolationlib, "overload")]
108  ans  =
109   "library"  "f"
110
111 --> string(interpolationlib)
112  ans  =
113   "SCI\modules\interpolation\macros\"
114   "interp1"
115   "mesh2d"
116   "interpln"
117   "smooth"
118
119 --> [fnames, libpath] = libraryinfo("interpolationlib")
120  fnames  =
121   "interp1"
122   "mesh2d"
123   "interpln"
124   "smooth"
125
126  libpath  =
127   "SCI\modules\interpolation\macros\"
128 </screen>
129         </para>
130         <para>
131             <emphasis role="bold">Автозагрузка при первом вызове функции</emphasis>:
132         </para>
133         <para>
134             Если имя функции -- скажем, <literal>foo()</literal> -- принадлежащей
135             библиотеке, вызвана в сессии, то Scilab делает следующее:
136             <orderedlist>
137                 <listitem>
138                     Является ли <literal>foo</literal> именем встроенной функции?
139                     Если так, то эта встроенная функция вызывается. В противном
140                     случае,
141                     <para/>
142                 </listitem>
143                 <listitem>
144                     Является ли <literal>foo</literal> именем локальной переменной,
145                     возможно требуемой <literal>foo()</literal> (предполагая, что
146                     она уже была вызвана)? Если так, то используется эта переменная.
147                     В противном случае,
148                     <para/>
149                 </listitem>
150                 <listitem>
151                     Сканируются все загруженные библиотеки -- в обратном алфавитному порядку имён
152                     библиотек -- для поиска <literal>foo()</literal>. Первая найденная
153                     "загружается" из её <literal>.bin</literal>-файла и, наконец, вызывается.
154                     Следующие вызовы <literal>foo()</literal> будут переходить к шагу №2,
155                     который будет успешным, пока дескриптор <literal>foo</literal> не
156                     будет удалён по ходу дела.
157                     <para/>
158                 </listitem>
159             </orderedlist>
160         </para>
161         <para>
162             Без шага №3 пользовательская функция, не принадлежащая ни к одной библиотеке
163             и поэтому в случае удаления не может быть автоматически восстановлена.
164         </para>
165         <para>
166             <warning>
167                 Если файл<literal>foo.sci</literal> изменён, когда <literal>foo()</literal>
168                 уже была вызвана, то перекомпиляция и перегрузка её библиотеки не обновит
169                 текущее поведение <literal>foo()</literal>: <literal>foo()</literal>,
170                 является уже известной, поэтому Scilab остановится на шаге №2 без
171                 перегрузки обновлённой библиотеки и будет использовать прежнюю
172                 <literal>foo()</literal>. Введение <literal>clear foo</literal> перед
173                 следующим вызовом <literal>foo()</literal> заставит Scilab перейти
174                 к шагу №3 во время следующего вызова и таким образом загрузит и будет
175                 использовать обновлённую <literal>foo()</literal>.
176             </warning>
177         </para>
178         <para>
179             <emphasis role="bold">Одноимённые функции в разных библиотеках: libname.foo()</emphasis>
180         </para>
181         <para>
182             Если несколько загруженных библиотек имеют публичную функцию
183             <literal>foo()</literal>, то обратный алфавитный приоритет может быть
184             неуместным. К счастью, всегда можно заставить использовать содержимое
185             указанной библиотеки с помощью синтаксиса разделения точкой:
186             <literal>libname.foo(..)</literal> будет вызывать содержимое
187             <literal>foo()</literal>, принадлежащее библиотеке <literal>libname</literal>.
188         </para>
189     </refsection>
190     <refsection>
191         <title>Примеры</title>
192         <para>
193             <literal>interpolationlib</literal> является родной библиотекой Scilab:
194         </para>
195         <programlisting role="example"><![CDATA[
196 interpolationlib        //отображает содержимое библиотеки
197 type(interpolationlib)
198 [typeof(interpolationlib), typeof(interpolationlib, "overload")]
199 string(interpolationlib)
200 [fnames, libpath] = libraryinfo("interpolationlib")
201      ]]></programlisting>
202         <para>
203             Вывод иллюстрируется в разделе Описание выше.
204         </para>
205         <para/>
206         <para>
207             Вызовы обработки одноимённых функций:
208         </para>
209         <programlisting role="example"><![CDATA[
210 whereis(blanks)
211 clear blanks, isdef("blanks","l")
212 blanks(20)          // загрузка blanks() и её вызов
213 isdef("blanks","l") // она остаётся в workspace
214
215 // Построение библиотеки с нашей собственной одноимённой функцией blanks()
216 libDir = fullfile(TMPDIR, "mylib");
217 code = ["function r = blanks(n, nbsp)"
218         "    if nbsp, r = part(ascii(160),ones(1,n)),"
219         "    else r = ""ABC"","
220         "    end"
221         "endfunction" ];
222 mkdir(libDir);
223 mputl(code, libDir + filesep() + "blanks.sci");
224 genlib("mylib", libDir);    // Компиляция нашей собственной библиотеки
225
226 clear blanks
227 ascii(blanks(3)) // вызывается stringlib.blanks() ⇐ "stringlib" > "mylib"
228 clear blanks
229 ascii(mylib.blanks(3,%t)) // принудительный вызов mylib.blanks()
230 blanks(3)        // следующий вызов по умолчанию stringlib.blanks()
231      ]]></programlisting>
232         <screen><![CDATA[
233 --> whereis(blanks)
234  ans  =
235   "stringlib"
236
237 --> clear blanks, isdef("blanks","l")
238  ans  =
239   F
240
241 --> blanks(20)          // loads blanks() and calls it
242  ans  =
243   "                    "
244 --> isdef("blanks","l") // It stays in the workspace
245  ans  =
246   T
247
248 --> // Building a library with our own homonymous blanks() function
249 --> libDir = fullfile(TMPDIR, "mylib");
250 --> code = ["function r = blanks(n, nbsp)"
251   >         "    if nbsp, r = part(ascii(160),ones(1,n)),"
252   >         "    else r = ""ABC"","
253   >         "    end"
254   >         "endfunction" ];
255 --> mkdir(libDir);
256 --> mputl(code, libDir + filesep() + "blanks.sci");
257 --> genlib("mylib", libDir);    // Compiling our own library
258
259 --> clear blanks
260 --> ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
261  ans  =
262    32.   32.   32.
263
264 --> clear blanks
265 --> ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
266  ans  =
267    194.   160.   194.   160.   194.   160.
268
269 --> blanks(3)        // Next call is with the default stringlib.blanks()
270  ans  =
271   "   "
272 ]]></screen>
273     </refsection>
274     <refsection role="see also">
275         <title>Смотрите также</title>
276         <simplelist type="inline">
277             <member>
278                 <link linkend="load">load</link>
279             </member>
280             <member>
281                 <link linkend="lib">lib</link>
282             </member>
283             <member>
284                 <link linkend="genlib">genlib</link>
285             </member>
286             <member>
287                 <link linkend="libraryinfo">libraryinfo</link>
288             </member>
289             <member>
290                 <link linkend="string">string</link>
291             </member>
292             <member>
293                 <link linkend="whereis">whereis</link>
294             </member>
295             <member>
296                 <link linkend="librarieslist">librarieslist</link>
297             </member>
298         </simplelist>
299     </refsection>
300     <refsection role="history">
301         <title>История</title>
302         <revhistory>
303             <revision>
304                 <revnumber>6.0.0</revnumber>
305                 <revdescription>
306                     <itemizedlist>
307                         <listitem>
308                             Библиотека теперь содержать только функции, а не переменные
309                             любого типа.
310                         </listitem>
311                         <listitem>
312                             Файл lib теперь является редактируемым XML-файлом, а не бинарным.
313                         </listitem>
314                         <listitem>
315                             Если файл исходного кода foo.sci содержит несколько последовательных
316                             блоков function/endfunction, то только определённая foo() теперь
317                             записывается в библиотеку. Остальные определённые функции теперь
318                             являются приватными и известными только из foo().
319                         </listitem>
320                     </itemizedlist>
321                 </revdescription>
322             </revision>
323         </revhistory>
324     </refsection>
325 </refentry>