* [#13855](https://bugzilla.scilab.org/13855): The documentation of `pause` was not up-to-date and could be improved.
* [#13985](https://bugzilla.scilab.org/13985): The display of lists was very loose and poor.
* [#14033](https://bugzilla.scilab.org/14033): `x_matrix` could not edit matrices of booleans, encoded integers or text. Matrices of real or complex numbers were poorly displayed.
+* [#14098](https://bugzilla.scilab.org/14098): The `genlib` and `library` help pages were outdated with respect to Scilab 6.
* [#14435](https://bugzilla.scilab.org/14435): Errors were not well handled in overloaded functions.
* [#14488](https://bugzilla.scilab.org/14488): The `frameflag=9` and `strf=".9."` values of these `plot2d` options were no longer accepted. Their documentation was ambiguous.
* [#14718](https://bugzilla.scilab.org/14718): `user` is removed for a while but was still documented.
<!--
* Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
* Copyright (C) ????-2008 - INRIA
- *
* Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - Samuel GOUGEON
*
* This file is hereby licensed under the terms of the GNU GPL v2.0,
* pursuant to article 5.3.4 of the CeCILL v.2.1.
* along with this program.
*
-->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="library">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+ xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="library">
<refnamediv>
<refname>library</refname>
- <refpurpose>library datatype description
+ <refpurpose>library datatype
</refpurpose>
</refnamediv>
- <refsynopsisdiv>
- <title>Syntax</title>
-
- </refsynopsisdiv>
<refsection>
<title>Description</title>
<para>
- A library is a data type with type number 14. It contains a path-name
- and a set of names. It allows automatic loading of variables using the
- following algorithm:
+ <emphasis role="bold">
+ What a library of functions written in Scilab language is made of?
+ </emphasis>
+ </para>
+ <para>
+ Such a library is made of a directory containing
+ <itemizedlist>
+ <listitem>
+ an editable XML file always named <literal>lib</literal>. This file contains
+ <orderedlist>
+ <listitem>
+ the name of the library
+ </listitem>
+ <listitem>
+ the list of names of public functions belonging to the library.
+ </listitem>
+ </orderedlist>
+ This file is generated by <literal>genlib(..)</literal>. It can't be made by hand.
+ <para/>
+ </listitem>
+ <listitem>
+ a set of binary files named with the <literal>.bin</literal> extension,
+ whose basenames are the names of functions possibly registered in the
+ <literal>lib</literal> file.
+ <para/>
+ </listitem>
+ <listitem>
+ and possibly -- but it's not mandatory to load and use the library --, the
+ <literal>.sci</literal> sources files written in Scilab language, whose
+ compilation with <code>genlib(..)</code> has generated the
+ <literal>lib</literal> and <literal>.bin</literal> files.
+ <para/>
+ <warning>
+ When the <literal>foo.sci</literal> source file of a foo()
+ function is not provided in the library's directory,
+ <literal>edit foo</literal> won't be able to edit its Scilab code, and
+ will open a empty file from scratch.
+ </warning>
+ <para/>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <emphasis role="bold">
+ Loading / declaring a library in the session
+ </emphasis>:
+ </para>
+ <para>
+ <literal>load("/path/to/lib")</literal> then loads the targeted library in the
+ Scilab session: a variable whose name is the library's name -- say
+ <literal>libname</literal> -- is created. Its dedicated <literal>type(libname)</literal>
+ is 14. Its <literal>typeof(libname)</literal> is <literal>"library"</literal>. This
+ library's handle contains
+ <itemizedlist>
+ <listitem>
+ the path to the library's root directory
+ </listitem>
+ <listitem>
+ the list of public functions names belonging to the library.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Both parts can be retrieved with either the libraryinfo() or the string() functions.
+ </para>
+ <para>
+ Example: <literal>interpolationlib</literal> is a native Scilab library:
+ <screen>
+--> interpolationlib
+ interpolationlib =
+
+Functions files location : SCI\modules\interpolation\macros\.
+interp1 mesh2d interpln smooth
+
+--> type(interpolationlib)
+ ans =
+ 14.
+
+--> [typeof(interpolationlib), typeof(interpolationlib, "overload")]
+ ans =
+ "library" "f"
+
+--> string(interpolationlib)
+ ans =
+ "SCI\modules\interpolation\macros\"
+ "interp1"
+ "mesh2d"
+ "interpln"
+ "smooth"
+
+--> [fnames, libpath] = libraryinfo("interpolationlib")
+ fnames =
+ "interp1"
+ "mesh2d"
+ "interpln"
+ "smooth"
+
+ libpath =
+ "SCI\modules\interpolation\macros\"
+</screen>
+ </para>
+ <para>
+ <emphasis role="bold">Autoloading when first calling a function</emphasis>:
</para>
<para>
- Suppose the Scilab user references the variable named <literal>foo</literal>.
- Scilab first looks if <literal>foo</literal> is the name of a primitive or of an
- already defined variable. If not, it looks for <literal>foo</literal> sequentially
- (the newest first) in all defined library .
+ When the name of a function -- say <literal>foo()</literal> -- belonging
+ to the library is called in the session, Scilab does the following:
+ <orderedlist>
+ <listitem>
+ Is <literal>foo</literal> the name of a builtin function?
+ If so, this builtin is called. Otherwise,
+ <para/>
+ </listitem>
+ <listitem>
+ Is <literal>foo</literal> the name of a local variable, possibly the
+ required foo() (provided that it has been already called)?
+ If so, this variable is used. Otherwise,
+ <para/>
+ </listitem>
+ <listitem>
+ All loaded libraries are scanned -- in anti-alphabetical order of libraries names --
+ for the searched foo(). The first found is then "loaded" from its
+ <literal>.bin</literal> file, and finally called. Next calls to foo()
+ will then go up to the step #2 that will be successful, unless
+ the <literal>foo</literal> handle has been cleared in the meantime.
+ <para/>
+ </listitem>
+ </orderedlist>
</para>
<para>
- Suppose <literal>foo</literal> belongs to the set of names of the library <literal>xlib</literal>
- then Scilab tries to load the file
- <xlib-path-name>/foo.bin. <xlib-path-name>/foo.bin must have been
- created using the <literal>save</literal> function
+ Without the step #3, a user's function not belonging to any library and that would
+ be cleared can not be automatically retrieved.
</para>
<para>
- Library are often used for collection of functions, but they can also
- be used for any collection of scilab variables
+ <warning>
+ If the <literal>foo.sci</literal> file is modified while foo() has been already
+ called, then recompiling and reloading its library won't update the current
+ foo() behavior: foo() being already known, Scilab will stop at the step #2,
+ without reloading the updated library, and will use the former foo().
+ Entering <literal>clear foo</literal> before the next call to foo(..)
+ will force Scilab going up to the step #3 during the next call, and so
+ load and use the updated foo().
+ </warning>
</para>
<para>
- If a function is defined in more than one library, the default search
- algorithm loads thode contained in the newest. It possible to force
- the use of a specific library using dot notation:
+ <emphasis role="bold">Homonymous functions in distinct libraries: libname.foo()</emphasis>
</para>
<para>
- <literal>xlib.foo</literal> loads the variable <literal>foo</literal> contained in <literal>xlib</literal>.
- if <literal>foo</literal> is a function
- and <literal>xlib.foo(args)</literal> executes the functions
+ If several loaded libraries have a foo() public function, the anti-alphabetical priority
+ can be unrelevant. Fortunately, it is always
+ possible to force to use the instance of a given library, with the dot-name's resolution
+ syntax:
+ <literal>libname.foo(..)</literal> will call the foo() instance belonging to the
+ <literal>libname</literal> library.
</para>
</refsection>
<refsection>
<title>Examples</title>
+ <para>
+ <literal>interpolationlib</literal> is a native Scilab library:
+ </para>
<programlisting role="example"><![CDATA[
-// elemlib is a predefined library
-elementary_functionlib //displays the contents of the library
-A=rand(3,3);
-cosm(A) //loads cosm and executes it
-whos -name cosm // now cosm is a variable
-elementary_functionlib.sinm //loads sinm from the library
-elementary_functionlib.cosm(A) //reloads cosm and executes it
- ]]></programlisting>
+interpolationlib //displays the contents of the library
+type(interpolationlib)
+[typeof(interpolationlib), typeof(interpolationlib, "overload")]
+string(interpolationlib)
+[fnames, libpath] = libraryinfo("interpolationlib")
+ ]]></programlisting>
+ <para>
+ The output is illustrated in the above Description section.
+ </para>
+ <para/>
+ <para>
+ Handling calls of homonymous functions:
+ </para>
+ <programlisting role="example"><![CDATA[
+whereis(blanks)
+clear blanks, isdef("blanks","l")
+blanks(20) // loads blanks() and calls it
+isdef("blanks","l") // It stays in the workspace
+
+// Building a library with our own homonymous blanks() function
+libDir = fullfile(TMPDIR, "mylib");
+code = ["function r = blanks(n, nbsp)"
+ " if nbsp, r = part(ascii(160),ones(1,n)),"
+ " else r = ""ABC"","
+ " end"
+ "endfunction" ];
+mkdir(libDir);
+mputl(code, libDir + filesep() + "blanks.sci");
+genlib("mylib", libDir); // Compiling our own library
+
+clear blanks
+ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
+clear blanks
+ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
+blanks(3) // Next call is with the default stringlib.blanks()
+ ]]></programlisting>
+ <screen><![CDATA[
+--> whereis(blanks)
+ ans =
+ "stringlib"
+
+--> clear blanks, isdef("blanks","l")
+ ans =
+ F
+
+--> blanks(20) // loads blanks() and calls it
+ ans =
+ " "
+--> isdef("blanks","l") // It stays in the workspace
+ ans =
+ T
+
+--> // Building a library with our own homonymous blanks() function
+--> libDir = fullfile(TMPDIR, "mylib");
+--> code = ["function r = blanks(n, nbsp)"
+ > " if nbsp, r = part(ascii(160),ones(1,n)),"
+ > " else r = ""ABC"","
+ > " end"
+ > "endfunction" ];
+--> mkdir(libDir);
+--> mputl(code, libDir + filesep() + "blanks.sci");
+--> genlib("mylib", libDir); // Compiling our own library
+
+--> clear blanks
+--> ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
+ ans =
+ 32. 32. 32.
+
+--> clear blanks
+--> ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
+ ans =
+ 194. 160. 194. 160. 194. 160.
+
+--> blanks(3) // Next call is with the default stringlib.blanks()
+ ans =
+ " "
+]]></screen>
</refsection>
<refsection role="see also">
<title>See also</title>
<simplelist type="inline">
<member>
+ <link linkend="load">load</link>
+ </member>
+ <member>
<link linkend="lib">lib</link>
</member>
<member>
+ <link linkend="genlib">genlib</link>
+ </member>
+ <member>
+ <link linkend="libraryinfo">libraryinfo</link>
+ </member>
+ <member>
<link linkend="string">string</link>
</member>
<member>
- <link linkend="load">load</link>
+ <link linkend="whereis">whereis</link>
</member>
<member>
- <link linkend="save">save</link>
+ <link linkend="librarieslist">librarieslist</link>
</member>
</simplelist>
</refsection>
+ <refsection role="history">
+ <title>History</title>
+ <revhistory>
+ <revision>
+ <revnumber>6.0.0</revnumber>
+ <revdescription>
+ <itemizedlist>
+ <listitem>
+ A library can now contain only functions, no longer any variables
+ of other types.
+ </listitem>
+ <listitem>
+ The lib file is now an editable XML file, no longer a binary one.
+ </listitem>
+ <listitem>
+ When a foo.sci source file contains several consecutive
+ function/endfunction blocks, only the defined foo()
+ is now registered in the library. Other defined functions are now
+ private and known only from foo().
+ </listitem>
+ </itemizedlist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </refsection>
</refentry>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ????-2008 - INRIA
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ja" xml:id="library">
- <refnamediv>
- <refname>library</refname>
- <refpurpose>ライブラリのデータ型の説明
- </refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <title>呼び出し手順</title>
- </refsynopsisdiv>
- <refsection>
- <title>説明</title>
- <para>
- ライブラリは型番号14のデータ型です.
- これには,パス名と名前の集合が含まれます.
- これにより,以下のアルゴリズムにより変数を自動的に
- ロードすることが可能になります:
- </para>
- <para>
- Scilabユーザが<literal>foo</literal>という名前の変数を参照すると
- 仮定します.
- Scilabはまず<literal>foo</literal>がプリミティブの名前または
- すでに定義ずみであるかどうかを調べます.
- そうでない場合,<literal>foo</literal>を(新しいものから順に)
- 順番に全ての定義済みのライブラリの中で探します.
- </para>
- <para>
- <literal>foo</literal> がライブラリ<literal>xlib</literal>の
- 名前の集合に属すると仮定すると,
- Scilabはファイル <xlib-path-name>/foo.bin をロード
- します.
- <xlib-path-name>/foo.bin は
- <literal>save</literal> 関数により作成されている必要があります.
- </para>
- <para>
- ライブラリはしばしば関数の集約に使用されますが,
- Scilab変数の集約にも使用することができます.
- </para>
- <para>
- ある関数が1つ以上のライブラリで定義されている場合,
- デフォルトの探索アルゴリズムは最新のライブラリに
- 含まれる関数をロードします.
- ドット表記により
- 特定のライブラリの関数を強制的に使用することも可能です:
- </para>
- <para>
- <literal>xlib.foo</literal> は
- <literal>xlib</literal>に含まれる変数<literal>foo</literal>
- をロードします.
- <literal>foo</literal>が関数の場合,
- <literal>xlib.foo(args)</literal>はこの関数を実行します.
- </para>
- </refsection>
- <refsection>
- <title>例</title>
- <programlisting role="example"><![CDATA[
-// elemlib は定義済みのライブラリです
-elementary_functionlib //ライブラリの中身を表示
-A=rand(3,3);
-cosm(A) //cosmをロードし実行
-whos -name cosm // ここでcosmは変数です
-elementary_functionlib.sinm //sinmをライブラリからロード
-elementary_functionlib.cosm(A) //cosmを再ロードし,実行
- ]]></programlisting>
- </refsection>
- <refsection role="see also">
- <title>参照</title>
- <simplelist type="inline">
- <member>
- <link linkend="lib">lib</link>
- </member>
- <member>
- <link linkend="string">string</link>
- </member>
- <member>
- <link linkend="load">load</link>
- </member>
- <member>
- <link linkend="save">save</link>
- </member>
- </simplelist>
- </refsection>
-</refentry>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ????-2008 - INRIA
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="library" xml:lang="pt">
- <refnamediv>
- <refname>library</refname>
- <refpurpose>descrição de tipo de dado bibilioteca</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <title>Seqüência de Chamamento</title>
-
- </refsynopsisdiv>
- <refsection>
- <title>Descrição</title>
- <para>Uma bibilioteca é um tipo de dado com número 14. Contém um nome de
- endereço e um conjunto de nomes. Permite o carregamento automático de
- variáveis utilizando o seguinte algoritmo:
- </para>
- <para>Suponha o usuário Scilab referencie a variável de nome
- <literal>foo</literal>. O Scilab procura primeiro se
- <literal>foo</literal> é o nome de uma primitiva, ou de uma variável já
- definida. Se naõ for, procura por <literal>foo</literal> seqüencialmente
- (a mais nova) em toda a biblioteca definida .
- </para>
- <para>
- Suponha que <literal>foo</literal> pertence ao conjunto de nomes da
- biblioteca <literal>xlib</literal>. Então o Scilab tenta carregar o
- arquivo <xlib-path-name>/foo.bin. <xlib-path-name>/foo.bin
- deve ter sido criado utilizando-se a função
- <literal>save</literal>.
- </para>
- <para>Bibliotecas geralmente são utilizadas para coleções de funções, mas
- também podem ser utilizadas para coleções de variáveis Scilab.
- </para>
- <para>Se uma função estiver definida em mais de uma biblioteca, o
- algoritmo de busca padrão carrega aquela contida na mais nova. É possível
- forçar o uso de uma biblioteca específica utilizando a notação de
- ponto:
- </para>
- <para>
- <literal>xlib.foo</literal> carrega a variável
- <literal>foo</literal> contida em <literal>xlib</literal>, if
- <literal>foo</literal> for uma função e <literal>xlib.foo(args)</literal>
- executa as funções.
- </para>
- </refsection>
- <refsection>
- <title>Exemplos</title>
- <programlisting role="example"><![CDATA[
-// elemlib é uma biblioteca predefinida
-elementary_functionlib //exibindo o conteúdo da biblioteca
-A=rand(3,3);
-cosm(A) //carregando cosm e executando-o
-whos -name cosm // agora, cosm é uma variável
-elementary_functionlib.sinm //carregando sinm da biblioteca
-elementary_functionlib.cosm(A) //carregando novamente cosm e executando-o
- ]]></programlisting>
- </refsection>
- <refsection role="see also">
- <title>Ver Também</title>
- <simplelist type="inline">
- <member>
- <link linkend="lib">lib</link>
- </member>
- <member>
- <link linkend="string">string</link>
- </member>
- <member>
- <link linkend="load">load</link>
- </member>
- <member>
- <link linkend="save">save</link>
- </member>
- </simplelist>
- </refsection>
-</refentry>
<!--
* Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
* Copyright (C) ????-2008 - INRIA
- *
* Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - Samuel GOUGEON
*
* This file is hereby licensed under the terms of the GNU GPL v2.0,
* pursuant to article 5.3.4 of the CeCILL v.2.1.
* For more information, see the COPYING file which you should have received
* along with this program.
*
- -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="genlib">
+-->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+ xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="genlib">
<refnamediv>
<refname>genlib</refname>
- <refpurpose>build library from functions in given directory</refpurpose>
+ <refpurpose>
+ builds a library from a set of *.sci files defining functions in a given directory
+ </refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Syntax</title>
- <synopsis>genlib(lib_name [[,dir_name, [ Force [,verb [,Names]]]])
- genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force] [,names=Names])
+ <synopsis>
+ genlib(lib_name)
+ genlib(lib_name, dir_name)
+ genlib(lib_name, dir_name, Force)
+ genlib(lib_name, dir_name, Force, verb)
+ genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force])
</synopsis>
</refsynopsisdiv>
<refsection>
<title>Arguments</title>
<variablelist>
<varlistentry>
- <term>lib_name: </term>
+ <term>lib_name</term>
<listitem>
- <para>Scilab string. The variable name of the library to (re)create.</para>
+ Scilab string: The identifying name ascribed to the library to build.
+ <para/>
</listitem>
</varlistentry>
<varlistentry>
- <term>dir_name: </term>
+ <term>dir_name</term>
<listitem>
- <para>Scilab string. The name of the directory to look for
- <literal>.sci</literal>-files.
- </para>
+ Scilab string: The pathname of the directory containing
+ <literal>.sci</literal> functions files, and where the <literal>lib</literal>
+ file generated and defining the library will be stored.
+ By default, the current working directory is considered.
+ <warning>
+ The <varname>dir_name</varname> directory and its <literal>lib</literal>
+ and <literal>.bin</literal> files must be writable.
+ </warning>
+ <para/>
</listitem>
</varlistentry>
<varlistentry>
<term>Force</term>
<listitem>
- <para>
- boolean value (default value is <literal>%f</literal>). Set it to
- <literal>%t</literal> to force the sci-files recompilation.
- </para>
+ boolean value (default value is <literal>%f</literal>). Set it to
+ <literal>%t</literal> to force the sci-files recompilation.
+ <para/>
</listitem>
</varlistentry>
<varlistentry>
<term>verb</term>
<listitem>
- <para>
- boolean values (default value is <literal>%f</literal>). Set it to
- <literal>%t</literal> to get information.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Names</term>
- <listitem>
- <para>a vector of strings, the names of function to include in the
- library. By default all the sci-files are taken into account
- </para>
+ boolean value (default value is <literal>%f</literal>). Set it to
+ <literal>%t</literal> to display more information during the build.
+ <para/>
</listitem>
</varlistentry>
</variablelist>
<refsection>
<title>Description</title>
<para>
- For each <literal>.sci</literal> file in <literal>dir_name</literal> (or only those
- specified by the <literal>Names</literal> argument), <literal>genlib</literal> executes a
- <literal>exec</literal> and saves the functions to the corresponding <literal>.bin</literal>
- file. The <literal>.sci</literal> file must not contain anything but Scilab
- functions. If a <literal>.bin</literal> file is newer than the associated
- <literal>.sci</literal> file, <literal>genlib</literal> does not translate and save the file.
+ <literal>genlib(..)</literal> selects all files belonging to the
+ <varname>dir_name</varname> directory and with the <literal>.sci</literal> extension.
+ If any, subdirectories are never considered. If it is required, they must be compiled
+ apart into independent libraries.
+ </para>
+ <para>
+ Then, an XML editable file named <literal>lib</literal> is created in the
+ <varname>dir_name</varname> directory. The name <varname>lib_name</varname>
+ of the library is recorded into it.
</para>
<para>
- This default behaviour can be changed if <literal>force</literal> is given and
- set to <literal>%t</literal>. In this latter case the recompilation is always
- performed for each <literal>.sci</literal> file.
+ Then, for each <literal>.sci</literal> file:
+ <itemizedlist>
+ <listitem>
+ If
+ <itemizedlist>
+ <listitem>
+ there is no related <literal>.bin</literal> file in <varname>dir_name</varname>
+ with the same basename (as for the initial build of the library), or
+ </listitem>
+ <listitem>
+ the content of the <literal>.sci</literal> file has changed since
+ the previous build,
+ </listitem>
+ </itemizedlist>
+ <para/>
+ <para>
+ the <literal>.sci</literal> file is compiled (<emphasis>almost</emphasis>
+ as it would be with <literal>exec(..)</literal>):
+ <itemizedlist>
+ <listitem>
+ <para>
+ If it contains at least one <literal>function .. endfunction</literal>
+ block, a <literal>.bin</literal> binary file with the same basename
+ is generated and stored in <varname>dir_name</varname>.
+ It contains the binary code of ALL functions defined in the
+ <literal>.sci</literal> source file.
+ <itemizedlist>
+ <listitem>
+ If the name of one of the function(s) defined in the
+ file is the basename of the <literal>.sci</literal>
+ file, this function is registered in the
+ <literal>lib</literal> file.
+ <para/>
+ </listitem>
+ <listitem>
+ Otherwise, no function from the <literal>.sci</literal>
+ file is registered: Its whole content is considered as
+ dead code.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <warning>
+ If a <literal>test.sci</literal> file defines the
+ <literal>test()</literal> function AND other functions like
+ sub(), sub() functions are then considered as private to
+ test(). For instance,
+ <table>
+ <tr>
+ <td>
+ <screen>
+function r = sub(a)
+ r = 2*a
+endfunction
+
+function test()
+ disp("A test")
+endfunction
+
+function r = other(b)
+ r = 2^b
+endfunction
+</screen>
+ </td>
+ <td>
+ is equivalent to
+ </td>
+ <td>
+ <screen>
+function test()
+ function r = sub(a)
+ r = 2*a
+ endfunction
+ function r = other(b)
+ r = 2^b
+ endfunction
+
+ disp("A test")
+endfunction
+</screen>
+ </td>
+ </tr>
+ </table>
+ Hence, sub() and other() won't exist out of test(), and
+ won't be registered in the library.
+ </warning>
+ </para>
+ </listitem>
+ <listitem>
+ Otherwise, no <literal>.bin</literal> file is generated: The whole
+ content of the <literal>.sci</literal> file is considered as dead code.
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ Otherwise: If the file's content has not changed and has already a function
+ entry in the <literal>lib</literal> file, this entry is kept.
+ </listitem>
+ </itemizedlist>
</para>
<para>
- When all <literal>.sci</literal> files have been processed, <literal>genlib</literal> creates a
- library variable named <literal>lib_name</literal> and saves it in the file
- <literal>lib</literal> in <literal>dir_name</literal>. If the Scilab variable
- <literal>lib_name</literal> is not protected (see <link linkend="predef">predef</link>) this
- variable is updated.
+ Finally, <literal>genlib(..)</literal> loads the created or updated library and sets
+ its identifier to a variable named <varname>lib_name</varname>, in the current scope.
+ If the variable <varname>lib_name</varname> already exists and is protected,
+ an error occurs: The library has been created but can't be loaded
+ (<link linkend="predef">predef all</link> can be used to unprotect the variable
+ named <varname>lib_name</varname> before running <literal>genlib(..)</literal>).
</para>
<para>
- If <literal>verbose</literal> is et to <literal>%t</literal> information are displayed during
- the build process.
+ If the option <literal>force=%t</literal> is used, all <literal>.sci</literal> files
+ are compiled, even if their content has not changed.
</para>
<para>
- If <literal>dir_name</literal> argument is not given and if <literal>lib_name</literal>
- Scilab variable exists and it is a library dir_name is taken equal to the
- <literal>lib_name</literal> library path (update mode).
+ When in the directory of a library some former .sci files have been removed while
+ all remaining .sci files are unchanged, rebuilding the library without the
+ <literal>force=%t</literal> will anyway update the list of library's members.
</para>
- </refsection>
- <refsection>
- <title>Restrictions</title>
<para>
- Scilab tacitly assumes that file <literal>foo.sci</literal> defines at least a
- function named <literal>foo</literal>. If subsidiary functions are included,
- they are made known to Scilab only after the function <literal>foo</literal>
- had been referenced.
+ If the option <literal>verbose</literal> is true, more information is displayed during
+ the build process.
</para>
</refsection>
<refsection role="see also">
<title>See also</title>
<simplelist type="inline">
<member>
- <link linkend="getd">getd</link>
+ <link linkend="library">library</link>
</member>
<member>
- <link linkend="exec">exec</link>
+ <link linkend="load">load</link>
</member>
<member>
- <link linkend="save">save</link>
+ <link linkend="getd">getd</link>
</member>
<member>
<link linkend="lib">lib</link>
</member>
</simplelist>
</refsection>
+ <refsection role="history">
+ <title>History</title>
+ <revhistory>
+ <revision>
+ <revnumber>6.0.0</revnumber>
+ <revdescription>
+ <itemizedlist>
+ <listitem>
+ The file <literal>names</literal> is no longer required.
+ The <literal>Names</literal> option is removed.
+ </listitem>
+ <listitem>
+ When a .sci file contains functions not named accordingly with the
+ file name, they are no longer public: They are visible and callable only
+ from the main function.
+ </listitem>
+ <listitem>
+ When a library named <varname>lib_name</varname> is already loaded, the
+ default <varname>dir_name</varname> directory is no longer its
+ directory (update mode), but always the current working one.
+ </listitem>
+ <listitem>
+ The generated <literal>lib</literal> file is now a human-readable XML
+ file, instead of a binary.
+ </listitem>
+ <listitem>
+ genlib() can no longer register any variable as full member of a library.
+ </listitem>
+ <listitem>
+ By default, any .sci file is now recompiled if its content has
+ changed, no longer if its modification date is newer than the .bin's one.
+ </listitem>
+ <listitem>
+ The generated <literal>.bin</literal> files can no longer be loaded
+ independently with load().
+ </listitem>
+ </itemizedlist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </refsection>
</refentry>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ????-2008 - INRIA
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- -->
-
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ja" xml:id="genlib">
-
- <refnamediv>
-
- <refname>genlib</refname>
-
- <refpurpose>指定したディレクトリの関数からライブラリを構築する </refpurpose>
-
- </refnamediv>
-
- <refsynopsisdiv>
-
- <title>呼び出し手順</title>
-
- <synopsis>genlib(lib_name [[,dir_name, [ Force [,verb [,Names]]]])
-
- genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force] [,names=Names])
-
- </synopsis>
-
- </refsynopsisdiv>
-
- <refsection>
-
- <title>引数</title>
-
- <variablelist>
-
- <varlistentry>
-
- <term>lib_name: </term>
-
- <listitem>
-
- <para>Scilab文字列. (再)作成するライブラリの変数名.</para>
-
- </listitem>
-
- </varlistentry>
-
- <varlistentry>
-
- <term>dir_name: </term>
-
- <listitem>
-
- <para>Scilab文字列.
-
- <literal>.sci</literal>-ファイルを探すディレクトリの名前.
-
- </para>
-
- </listitem>
-
- </varlistentry>
-
- <varlistentry>
-
- <term>Force</term>
-
- <listitem>
-
- <para>
-
- 論理値 (デフォルト値は <literal>%f</literal>).
-
- sci-ファイルの再コンパイルを強制的に行う場合,
-
- <literal>%t</literal>に設定してください.
-
- </para>
-
- </listitem>
-
- </varlistentry>
-
- <varlistentry>
-
- <term>verb</term>
-
- <listitem>
-
- <para>
-
- 論理値 (デフォルト値は <literal>%f</literal>).
-
- 情報を取得するには <literal>%t</literal> に設定してください.
-
- </para>
-
- </listitem>
-
- </varlistentry>
-
- <varlistentry>
-
- <term>Names</term>
-
- <listitem>
-
- <para>文字列のベクトルで, ライブラリに含まれる
-
- 関数の名前です.
-
- デフォルトで全ての sci-ファイルが取得されます.
-
- </para>
-
- </listitem>
-
- </varlistentry>
-
- </variablelist>
-
- </refsection>
-
- <refsection>
-
- <title>説明</title>
-
- <para>
-
- <literal>dir_name</literal>にある各<literal>.sci</literal>ファイル
-
- (または<literal>Names</literal>引数で指定されたファイルのみ)について,
-
- <literal>genlib</literal>は<literal>exec</literal>を
-
- 実行し,対応する<literal>.bin</literal>ファイルに関数を保存します.
-
- <literal>.sci</literal>ファイルにはScilab関数以外のものを含んでは
-
- いけません.
-
- ある<literal>.bin</literal>ファイルが対応する<literal>.sci</literal>ファイルよりも
-
- 新しい場合, <literal>genlib</literal>はこのファイルを変換/保存しません.
-
- </para>
-
- <para>
-
- このデフォルトの動作は<literal>force</literal>が指定され,
-
- <literal>%t</literal> に設定された場合に変更できます.
-
- この場合, 各<literal>.sci</literal>ファイル毎に常に再コンパイルが
-
- 行われます.
-
- </para>
-
- <para>
-
- 全ての<literal>.sci</literal> ファイルが処理された場合,
-
- <literal>genlib</literal>は<literal>lib_name</literal>という
-
- 名前のライブラリ変数を作成し,
-
- <literal>dir_name</literal>の中のファイル<literal>lib</literal>に
-
- この変数を保存します.
-
- Scilab変数
-
- <literal>lib_name</literal>が保護されていない場合
-
- (<link linkend="predef">predef</link>参照),
-
- この変数は更新されます.
-
- </para>
-
- <para>
-
- <literal>verbose</literal> に <literal>%t</literal>が
-
- 指定された場合, 構築処理中に情報が表示されます.
-
- </para>
-
- <para>
-
- <literal>dir_name</literal> 引数が指定されない場合に,
-
- Scilab変数<literal>lib_name</literal>が存在し,
-
- それがライブラリの場合,
-
- dir_name は,
-
- <literal>lib_name</literal>ライブラリパスに等しく
-
- 設定されます (更新モード).
-
- </para>
-
- </refsection>
-
- <refsection>
-
- <title>制約</title>
-
- <para>
-
- Scilab は, ファイル<literal>foo.sci</literal>が,
-
- 少なくとも<literal>foo</literal>という名前の関数を
-
- 定義すると仮定します.
-
- 補助関数が含まれる場合,これらは
-
- 関数<literal>foo</literal>が参照された後でのみ
-
- Scilabから既知となります.
-
- </para>
-
- </refsection>
-
- <refsection role="see also">
-
- <title>参照</title>
-
- <simplelist type="inline">
-
- <member>
-
- <link linkend="getd">getd</link>
-
- </member>
-
- <member>
-
- <link linkend="exec">exec</link>
-
- </member>
-
- <member>
-
- <link linkend="save">save</link>
-
- </member>
-
- <member>
-
- <link linkend="lib">lib</link>
-
- </member>
-
- </simplelist>
-
- </refsection>
-
-</refentry>
-
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ????-2008 - INRIA
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="genlib" xml:lang="pt">
- <refnamediv>
- <refname>genlib</refname>
- <refpurpose>constrói biblioteca a partir de funções em um
- diretório
- </refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <title>Seqüência de Chamamento</title>
- <synopsis>genlib(lib_name [[,dir_name, [ Force [,verb [,Names]]]])
- genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force] [,names=Names])
- </synopsis>
- </refsynopsisdiv>
- <refsection>
- <title>Parâmetros</title>
- <variablelist>
- <varlistentry>
- <term>lib_name:</term>
- <listitem>
- <para>string. O nome da variável biblioteca a ser (re)criada.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>dir_name:</term>
- <listitem>
- <para>string. O nome do diretório onde se deve procurar arquivos
- <literal>.sci</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Force</term>
- <listitem>
- <para>
- booleano (o padrão é <literal>%f</literal>). Para forçar
- recompilação de arquivos .sci, ajuste-o para
- <literal>%t</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>verb</term>
- <listitem>
- <para>
- booleano (o padrão é <literal>%f</literal>). Para obter
- informações ajuste-o para <literal>%t</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Names</term>
- <listitem>
- <para>vetor de strings, os nomes das funções a serem inclusas na
- bibilioteca. Por padrão, todos os arquivos sci são levados em
- conta.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsection>
- <refsection>
- <title>Descrição</title>
- <para>
- Para cada arquivo <literal>.sci</literal> em
- <literal>dir_name</literal> (ou apenas para aqueles especificados pelo
- argumento <literal>Names</literal>), <literal>genlib</literal> executa um
- <literal>exec</literal> e salva as funções no arquivo
- <literal>.bin</literal> correspondente. O arquivo <literal>.sci</literal>
- só pode conter instruções Scilab. Se um arquivo <literal>.bin</literal>
- for mais novo que o arquivo <literal>.sci</literal> assicuadi,
- <literal>genlib</literal> não traduz nem salva o arquivo.
- </para>
- <para>O comportamento padrão pode ser modificado se
- <literal>force</literal> for fornecido e ajustado para
- <literal>%t</literal>. Neste último caso, a recompilação é sempre feita
- para cada arquivo <literal>.sci</literal>.
- </para>
- <para>
- Quando todos os arquivos <literal>.sci</literal> tiverem sido
- processados, <literal>genlib</literal> cria uma biblioteca nomeada
- <literal>lib_name</literal> e a salva arquivo <literal>lib</literal> em
- <literal>dir_name</literal>. Se a variável Scilab
- <literal>lib_name</literal> não estiver protegida (ver <link linkend="predef">predef</link>), esta variável é atualizada.
- </para>
- <para>
- Se <literal>verb</literal> estiver ajustado para
- <literal>%t</literal> informações são exibidas durante o processo de
- construção.
- </para>
- <para>
- Seo argumento <literal>dir_name</literal> não for fornecido e se a
- variável Scilab <literal>lib_name</literal> existe e é uma variável
- dir_name é tomado como sendo igual a o endereço de bibilioteca
- <literal>lib_name</literal> (modo de atualização).
- </para>
- </refsection>
- <refsection>
- <title>Restrições</title>
- <para>
- Scilab assume implicitamente que <literal>foo.sci</literal> define
- pelo menos uma função de nome <literal>foo</literal>. Se funções
- subsidiárias estiverem inlusas, elas são tornadas conhecidas ao Scilab
- apenas depois que função <literal>foo</literal> tiver sido
- referencida.
- </para>
- </refsection>
- <refsection role="see also">
- <title>Ver Também</title>
- <simplelist type="inline">
- <member>
- <link linkend="getd">getd</link>
- </member>
- <member>
- <link linkend="exec">exec</link>
- </member>
- <member>
- <link linkend="save">save</link>
- </member>
- <member>
- <link linkend="lib">lib</link>
- </member>
- </simplelist>
- </refsection>
-</refentry>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) ????-2008 - INRIA
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+-->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+ xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="genlib">
+ <refnamediv>
+ <refname>genlib</refname>
+ <refpurpose>
+ строит библиотеку из набора *.sci-файлов, определяющих функции в указанной директории
+ </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <title>Синтаксис</title>
+ <synopsis>
+ genlib(lib_name)
+ genlib(lib_name, dir_name)
+ genlib(lib_name, dir_name, Force)
+ genlib(lib_name, dir_name, Force, verb)
+ genlib(lib_name [,path=dir_name] [,verbose=verb] [,force=Force])
+ </synopsis>
+ </refsynopsisdiv>
+ <refsection>
+ <title>Аргументы</title>
+ <variablelist>
+ <varlistentry>
+ <term>lib_name</term>
+ <listitem>
+ Scilab-строка: идентифицирующее имя присваиваемое библиотеку,
+ которую нужно построить.
+ <para/>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>dir_name</term>
+ <listitem>
+ Scilab-строка: путь к директории, содержащей файлы
+ <literal>.sci</literal>-функций, и где генерируется файл
+ <literal>lib</literal> и определяющая, где будет храниться
+ библиотека. По умолчанию рассматривается текущая рабочая директория.
+ <warning>
+ Директория <varname>dir_name</varname> directory и её <literal>lib</literal>-
+ и <literal>.bin</literal>-файлы должны иметь право на запись.
+ </warning>
+ <para/>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Force</term>
+ <listitem>
+ логическое значение (значение по умолчанию <literal>%f</literal>). Установите
+ его в <literal>%t</literal>, чтобы принудить к рекомпиляции sci-файлов.
+ <para/>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>verb</term>
+ <listitem>
+ логическое значение (значение по умолчанию <literal>%f</literal>).
+ Установите его в <literal>%t</literal>, чтобы отобразить больше
+ информации во время сборки.
+ <para/>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsection>
+ <refsection>
+ <title>Описание</title>
+ <para>
+ <literal>genlib(..)</literal> выбирает все файлы, принадлежащие директории
+ <varname>dir_name</varname> и с расширением <literal>.sci</literal>.
+ Поддиректории, если они есть, никогда не рассматриваются. Если требуется,
+ они должны компилироваться отдельно в независимые библиотеки.
+ </para>
+ <para>
+ Затем создаётся редактируемый XML-файл <literal>lib</literal> в директории
+ <varname>dir_name</varname>. Имя <varname>lib_name</varname> библиотеки
+ записывается в него.
+ </para>
+ <para>
+ Далее, для каждого <literal>.sci</literal>-файла:
+ <itemizedlist>
+ <listitem>
+ Если
+ <itemizedlist>
+ <listitem>
+ нет связанного <literal>.bin</literal>-файла в <varname>dir_name</varname>
+ с тем же базовым именем (что и для исходной сборки библиотеки), либо
+ </listitem>
+ <listitem>
+ содержимое <literal>.sci</literal>-файла было изменено
+ со времени предыдущей сборки,
+ </listitem>
+ </itemizedlist>
+ <para/>
+ <para>
+ <literal>.sci</literal>-файл скомпилирован (<emphasis>почти</emphasis>
+ как если бы это было с <literal>exec(..)</literal>):
+ <itemizedlist>
+ <listitem>
+ <para>
+ если он содержит по крайней мере один блок
+ <literal>function .. endfunction</literal>, то
+ двоичный <literal>.bin</literal>-файл с тем же базовым именем
+ генерируется и хранится в <varname>dir_name</varname>.
+ Он содержит бинарный код ВСЕХ функций, определённых в
+ <literal>.sci</literal>-файле исходного кода.
+ <itemizedlist>
+ <listitem>
+ Если имя одной из функций, определённой в файле,
+ является базовым именем <literal>.sci</literal>-файла,
+ то эта функция записывается в <literal>lib</literal>-файл.
+ <para/>
+ </listitem>
+ <listitem>
+ В противном случае, ни одна функция из <literal>.sci</literal>-файла не записывается: всё
+ её содержимое рассматривается как мёртвый код.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <warning>
+ Если файл <literal>test.sci</literal> определяет функцию
+ <literal>test()</literal> И другие функции, такие как
+ sub(), то функции sub() тогда рассматриваются как приватные для test(). Например,
+ <table>
+ <tr>
+ <td>
+ <screen>
+function r = sub(a)
+ r = 2*a
+endfunction
+
+function test()
+ disp("A test")
+endfunction
+
+function r = other(b)
+ r = 2^b
+endfunction
+</screen>
+ </td>
+ <td>
+ эквивалентно
+ </td>
+ <td>
+ <screen>
+function test()
+ function r = sub(a)
+ r = 2*a
+ endfunction
+ function r = other(b)
+ r = 2^b
+ endfunction
+
+ disp("A test")
+endfunction
+</screen>
+ </td>
+ </tr>
+ </table>
+ Следовательно, sub() и other() не существуют вне test() и
+ не будут записаны в библиотеку.
+ </warning>
+ </para>
+ </listitem>
+ <listitem>
+ В противном случае, <literal>.bin</literal>-файл не будет
+ генерироваться: всё содержимое <literal>.sci</literal>-файла
+ рассматривается как мёртвый код.
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ В противном случае: если содержимое файла не изменилось и уже имеет
+ содержимое функции в <literal>lib</literal>-файле, то это содержимое
+ сохраняется.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Наконец, <literal>genlib(..)</literal> загружает созданную или обновлённую
+ библиотеку и устанавливает её идентификатор в переменную, названную
+ <varname>lib_name</varname>, в текущей области просмотра. Если переменная
+ <varname>lib_name</varname> уже существует и защищена,то возникает ошибка:
+ библиотека была создана, но не может быть загружена
+ (<link linkend="predef">predef all</link> может использоваться для снятия
+ защиты с переменной, названной <varname>lib_name</varname> перед запуском
+ <literal>genlib(..)</literal>).
+ </para>
+ <para>
+ Если используется опция <literal>force=%t</literal>, то все
+ <literal>.sci</literal>-файлы компилируются, даже если их содержимое не
+ было изменено.
+ </para>
+ <para>
+ Когда из директории библиотеки некоторые старые .sci-файлы были удалены
+ и при этом оставшиеся .sci-файлы остались неизменными, то пересборка
+ библиотеки без <literal>force=%t</literal> в любом случае обновит
+ список членов библиотеки.
+ </para>
+ <para>
+ Если включена опция <literal>verbose</literal>, то во время сборки
+ отображается больше информации.
+ </para>
+ </refsection>
+ <refsection role="see also">
+ <title>Смотрите также</title>
+ <simplelist type="inline">
+ <member>
+ <link linkend="library">library</link>
+ </member>
+ <member>
+ <link linkend="load">load</link>
+ </member>
+ <member>
+ <link linkend="getd">getd</link>
+ </member>
+ <member>
+ <link linkend="lib">lib</link>
+ </member>
+ </simplelist>
+ </refsection>
+ <refsection role="history">
+ <title>История</title>
+ <revhistory>
+ <revision>
+ <revnumber>6.0.0</revnumber>
+ <revdescription>
+ <itemizedlist>
+ <listitem>
+ Больше не требуется файл <literal>names</literal>.
+ Опция <literal>Names</literal> удалена.
+ </listitem>
+ <listitem>
+ Если .sci-файл содержит функции, названные не в соответствии с именем
+ файла, то они теперь не являются публичными: их можно увидеть и
+ вызвать только из главной функции.
+ </listitem>
+ <listitem>
+ Если библиотека с именем <varname>lib_name</varname> уже загружена,
+ то директорией по умолчанию <varname>dir_name</varname> теперь
+ является не её директория (режим обновления), а текущая рабочая
+ директория.
+ </listitem>
+ <listitem>
+ Сгенерированный <literal>lib</literal>-файл теперь является
+ XML-файлом, который может прочитать человек, а не двоичный файл.
+ </listitem>
+ <listitem>
+ genlib() теперь не может записать какую-либо переменную в
+ качестве полноправного члена библиотеки.
+ </listitem>
+ <listitem>
+ По умолчанию любой .sci-файл теперь перекомпилируется,
+ если его содержимое было изменено, а не, если дата его изменения
+ новее, чем дата .bin-файла.
+ </listitem>
+ <listitem>
+ Генерируемые <literal>.bin</literal>-файлы более не могут
+ быть загружены независимо с помощью load().
+ </listitem>
+ </itemizedlist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </refsection>
+</refentry>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) ????-2008 - INRIA
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2021 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+ xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="library">
+ <refnamediv>
+ <refname>library</refname>
+ <refpurpose>тип данных библиотеки</refpurpose>
+ </refnamediv>
+ <refsection>
+ <title>Описание</title>
+ <para>
+ <emphasis role="bold">
+ Из чего сделана библиотека функций, написанных на языке Scilab?
+ </emphasis>
+ </para>
+ <para>
+ Такая библиотека сделана из директории, содержащей
+ <itemizedlist>
+ <listitem>
+ редактируемый XML-файл, который всегда называется <literal>lib</literal>.
+ Этот файл содержит
+ <orderedlist>
+ <listitem>
+ имя библиотеки;
+ </listitem>
+ <listitem>
+ список имён публичных функций, принадлежащих библиотеке.
+ </listitem>
+ </orderedlist>
+ Этот файл сгенерирован с помощью <literal>genlib(..)</literal>.
+ Его нельзя сделать вручную.
+ <para/>
+ </listitem>
+ <listitem>
+ набор двоичных файлов с расширением <literal>.bin</literal>,
+ чьи основные имена являются именами функций возможно зарегистрированных
+ в файле <literal>lib</literal>,
+ <para/>
+ </listitem>
+ <listitem>
+ и возможно -- но это необязательно для загрузки и использования
+ библиотеки --, <literal>.sci</literal>-файлы исходников, написанные
+ на языке Scilab, чья компиляция с помощью <code>genlib(..)</code>
+ генерирует файлы <literal>lib</literal> и <literal>.bin</literal>.
+ <para/>
+ <warning>
+ Если файл-исходник <literal>foo.sci</literal> функции
+ <literal>foo()</literal> не предоставлен в директории библиотеки,
+ то <literal>edit foo</literal> не может править его Scilab-код
+ и откроет пустой файл с нуля.
+ </warning>
+ <para/>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <emphasis role="bold">
+ Загрузка / декларирование библиотеки в сессии
+ </emphasis>:
+ </para>
+ <para>
+ <literal>load("/path/to/lib")</literal> загружает предназначенную библиотеку
+ в сессию Scilab: создаётся переменная, чьё имя является именем библиотеки
+ -- скажем <literal>libname</literal>. Относящийся к ней тип
+ <literal>type(libname)</literal> равен 14. Её <literal>typeof(libname)</literal>
+ соответствует <literal>"library"</literal>. Этот дескриптор библиотеки содержит
+ <itemizedlist>
+ <listitem>
+ путь к корневой директории библиотеки;
+ </listitem>
+ <listitem>
+ список имён публичных функций, принадлежащих библиотеке.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Обе части могут быть получены либо с помощью функции <literal>libraryinfo()</literal>,
+ либо с помощью функции <literal>string()</literal>.
+ </para>
+ <para>
+ Пример: <literal>interpolationlib</literal> является родной библиотекой Scilab:
+ <screen>
+--> interpolationlib
+ interpolationlib =
+
+Functions files location : SCI\modules\interpolation\macros\.
+interp1 mesh2d interpln smooth
+
+--> type(interpolationlib)
+ ans =
+ 14.
+
+--> [typeof(interpolationlib), typeof(interpolationlib, "overload")]
+ ans =
+ "library" "f"
+
+--> string(interpolationlib)
+ ans =
+ "SCI\modules\interpolation\macros\"
+ "interp1"
+ "mesh2d"
+ "interpln"
+ "smooth"
+
+--> [fnames, libpath] = libraryinfo("interpolationlib")
+ fnames =
+ "interp1"
+ "mesh2d"
+ "interpln"
+ "smooth"
+
+ libpath =
+ "SCI\modules\interpolation\macros\"
+</screen>
+ </para>
+ <para>
+ <emphasis role="bold">Автозагрузка при первом вызове функции</emphasis>:
+ </para>
+ <para>
+ Если имя функции -- скажем, <literal>foo()</literal> -- принадлежащей
+ библиотеке, вызвана в сессии, то Scilab делает следующее:
+ <orderedlist>
+ <listitem>
+ Является ли <literal>foo</literal> именем встроенной функции?
+ Если так, то эта встроенная функция вызывается. В противном
+ случае,
+ <para/>
+ </listitem>
+ <listitem>
+ Является ли <literal>foo</literal> именем локальной переменной,
+ возможно требуемой <literal>foo()</literal> (предполагая, что
+ она уже была вызвана)? Если так, то используется эта переменная.
+ В противном случае,
+ <para/>
+ </listitem>
+ <listitem>
+ Сканируются все загруженные библиотеки -- в обратном алфавитному порядку имён
+ библиотек -- для поиска <literal>foo()</literal>. Первая найденная
+ "загружается" из её <literal>.bin</literal>-файла и, наконец, вызывается.
+ Следующие вызовы <literal>foo()</literal> будут переходить к шагу №2,
+ который будет успешным, пока дескриптор <literal>foo</literal> не
+ будет удалён по ходу дела.
+ <para/>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ Без шага №3 пользовательская функция, не принадлежащая ни к одной библиотеке
+ и поэтому в случае удаления не может быть автоматически восстановлена.
+ </para>
+ <para>
+ <warning>
+ Если файл<literal>foo.sci</literal> изменён, когда <literal>foo()</literal>
+ уже была вызвана, то перекомпиляция и перегрузка её библиотеки не обновит
+ текущее поведение <literal>foo()</literal>: <literal>foo()</literal>,
+ является уже известной, поэтому Scilab остановится на шаге №2 без
+ перегрузки обновлённой библиотеки и будет использовать прежнюю
+ <literal>foo()</literal>. Введение <literal>clear foo</literal> перед
+ следующим вызовом <literal>foo()</literal> заставит Scilab перейти
+ к шагу №3 во время следующего вызова и таким образом загрузит и будет
+ использовать обновлённую <literal>foo()</literal>.
+ </warning>
+ </para>
+ <para>
+ <emphasis role="bold">Одноимённые функции в разных библиотеках: libname.foo()</emphasis>
+ </para>
+ <para>
+ Если несколько загруженных библиотек имеют публичную функцию
+ <literal>foo()</literal>, то обратный алфавитный приоритет может быть
+ неуместным. К счастью, всегда можно заставить использовать содержимое
+ указанной библиотеки с помощью синтаксиса разделения точкой:
+ <literal>libname.foo(..)</literal> будет вызывать содержимое
+ <literal>foo()</literal>, принадлежащее библиотеке <literal>libname</literal>.
+ </para>
+ </refsection>
+ <refsection>
+ <title>Примеры</title>
+ <para>
+ <literal>interpolationlib</literal> является родной библиотекой Scilab:
+ </para>
+ <programlisting role="example"><![CDATA[
+interpolationlib //отображает содержимое библиотеки
+type(interpolationlib)
+[typeof(interpolationlib), typeof(interpolationlib, "overload")]
+string(interpolationlib)
+[fnames, libpath] = libraryinfo("interpolationlib")
+ ]]></programlisting>
+ <para>
+ Вывод иллюстрируется в разделе Описание выше.
+ </para>
+ <para/>
+ <para>
+ Вызовы обработки одноимённых функций:
+ </para>
+ <programlisting role="example"><![CDATA[
+whereis(blanks)
+clear blanks, isdef("blanks","l")
+blanks(20) // загрузка blanks() и её вызов
+isdef("blanks","l") // она остаётся в workspace
+
+// Построение библиотеки с нашей собственной одноимённой функцией blanks()
+libDir = fullfile(TMPDIR, "mylib");
+code = ["function r = blanks(n, nbsp)"
+ " if nbsp, r = part(ascii(160),ones(1,n)),"
+ " else r = ""ABC"","
+ " end"
+ "endfunction" ];
+mkdir(libDir);
+mputl(code, libDir + filesep() + "blanks.sci");
+genlib("mylib", libDir); // Компиляция нашей собственной библиотеки
+
+clear blanks
+ascii(blanks(3)) // вызывается stringlib.blanks() ⇐ "stringlib" > "mylib"
+clear blanks
+ascii(mylib.blanks(3,%t)) // принудительный вызов mylib.blanks()
+blanks(3) // следующий вызов по умолчанию stringlib.blanks()
+ ]]></programlisting>
+ <screen><![CDATA[
+--> whereis(blanks)
+ ans =
+ "stringlib"
+
+--> clear blanks, isdef("blanks","l")
+ ans =
+ F
+
+--> blanks(20) // loads blanks() and calls it
+ ans =
+ " "
+--> isdef("blanks","l") // It stays in the workspace
+ ans =
+ T
+
+--> // Building a library with our own homonymous blanks() function
+--> libDir = fullfile(TMPDIR, "mylib");
+--> code = ["function r = blanks(n, nbsp)"
+ > " if nbsp, r = part(ascii(160),ones(1,n)),"
+ > " else r = ""ABC"","
+ > " end"
+ > "endfunction" ];
+--> mkdir(libDir);
+--> mputl(code, libDir + filesep() + "blanks.sci");
+--> genlib("mylib", libDir); // Compiling our own library
+
+--> clear blanks
+--> ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
+ ans =
+ 32. 32. 32.
+
+--> clear blanks
+--> ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
+ ans =
+ 194. 160. 194. 160. 194. 160.
+
+--> blanks(3) // Next call is with the default stringlib.blanks()
+ ans =
+ " "
+]]></screen>
+ </refsection>
+ <refsection role="see also">
+ <title>Смотрите также</title>
+ <simplelist type="inline">
+ <member>
+ <link linkend="load">load</link>
+ </member>
+ <member>
+ <link linkend="lib">lib</link>
+ </member>
+ <member>
+ <link linkend="genlib">genlib</link>
+ </member>
+ <member>
+ <link linkend="libraryinfo">libraryinfo</link>
+ </member>
+ <member>
+ <link linkend="string">string</link>
+ </member>
+ <member>
+ <link linkend="whereis">whereis</link>
+ </member>
+ <member>
+ <link linkend="librarieslist">librarieslist</link>
+ </member>
+ </simplelist>
+ </refsection>
+ <refsection role="history">
+ <title>История</title>
+ <revhistory>
+ <revision>
+ <revnumber>6.0.0</revnumber>
+ <revdescription>
+ <itemizedlist>
+ <listitem>
+ Библиотека теперь содержать только функции, а не переменные
+ любого типа.
+ </listitem>
+ <listitem>
+ Файл lib теперь является редактируемым XML-файлом, а не бинарным.
+ </listitem>
+ <listitem>
+ Если файл исходного кода foo.sci содержит несколько последовательных
+ блоков function/endfunction, то только определённая foo() теперь
+ записывается в библиотеку. Остальные определённые функции теперь
+ являются приватными и известными только из foo().
+ </listitem>
+ </itemizedlist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </refsection>
+</refentry>
projects / scilab.git / commitdiff