scilab/modules/core/help/ru_RU/types/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>