* Bug 14098 [doc]: genlib() and library pages updated for Scilab 6
[scilab.git] / scilab / modules / core / help / en_US / 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="en" xml:id="library">
19     <refnamediv>
20         <refname>library</refname>
21         <refpurpose>library datatype
22         </refpurpose>
23     </refnamediv>
24     <refsection>
25         <title>Description</title>
26         <para>
27             <emphasis role="bold">
28                 What a library of functions written in Scilab language is made of?
29             </emphasis>
30         </para>
31         <para>
32             Such a library is made of a directory containing
33             <itemizedlist>
34                 <listitem>
35                     an editable XML file always named <literal>lib</literal>. This file contains
36                     <orderedlist>
37                         <listitem>
38                             the name of the library
39                         </listitem>
40                         <listitem>
41                             the list of names of public functions belonging to the library.
42                         </listitem>
43                     </orderedlist>
44                     This file is generated by <literal>genlib(..)</literal>. It can't be made by hand.
45                     <para/>
46                 </listitem>
47                 <listitem>
48                     a set of binary files named with the <literal>.bin</literal> extension,
49                     whose basenames are the names of functions possibly registered in the
50                     <literal>lib</literal> file.
51                     <para/>
52                 </listitem>
53                 <listitem>
54                     and possibly -- but it's not mandatory to load and use the library --, the
55                     <literal>.sci</literal> sources files written in Scilab language, whose
56                     compilation with <code>genlib(..)</code> has generated the
57                     <literal>lib</literal> and <literal>.bin</literal> files.
58                     <para/>
59                     <warning>
60                         When the <literal>foo.sci</literal> source file of a foo()
61                         function is not provided in the library's directory,
62                         <literal>edit foo</literal> won't be able to edit its Scilab code, and
63                         will open a empty file from scratch.
64                     </warning>
65                     <para/>
66                 </listitem>
67             </itemizedlist>
68         </para>
69         <para>
70             <emphasis role="bold">
71                 Loading / declaring a library in the session
72             </emphasis>:
73         </para>
74         <para>
75             <literal>load("/path/to/lib")</literal> then loads the targeted library in the
76             Scilab session: a variable whose name is the library's name -- say
77             <literal>libname</literal> -- is created. Its dedicated <literal>type(libname)</literal>
78             is 14. Its <literal>typeof(libname)</literal> is <literal>"library"</literal>. This
79             library's handle contains
80             <itemizedlist>
81                 <listitem>
82                     the path to the library's root directory
83                 </listitem>
84                 <listitem>
85                     the list of public functions names belonging to the library.
86                 </listitem>
87             </itemizedlist>
88         </para>
89         <para>
90             Both parts can be retrieved with either the libraryinfo() or the string() functions.
91         </para>
92         <para>
93             Example: <literal>interpolationlib</literal> is a native Scilab library:
94             <screen>
95 --> interpolationlib
96  interpolationlib  =
97
98 Functions files location : SCI\modules\interpolation\macros\.
99 interp1  mesh2d  interpln  smooth
100
101 --> type(interpolationlib)
102  ans  =
103    14.
104
105 --> [typeof(interpolationlib), typeof(interpolationlib, "overload")]
106  ans  =
107   "library"  "f"
108
109 --> string(interpolationlib)
110  ans  =
111   "SCI\modules\interpolation\macros\"
112   "interp1"
113   "mesh2d"
114   "interpln"
115   "smooth"
116
117 --> [fnames, libpath] = libraryinfo("interpolationlib")
118  fnames  =
119   "interp1"
120   "mesh2d"
121   "interpln"
122   "smooth"
123
124  libpath  =
125   "SCI\modules\interpolation\macros\"
126 </screen>
127         </para>
128         <para>
129             <emphasis role="bold">Autoloading when first calling a function</emphasis>:
130         </para>
131         <para>
132             When the name of a function -- say <literal>foo()</literal> -- belonging
133             to the library is called in the session, Scilab does the following:
134             <orderedlist>
135                 <listitem>
136                     Is <literal>foo</literal> the name of a builtin function?
137                     If so, this builtin is called. Otherwise,
138                     <para/>
139                 </listitem>
140                 <listitem>
141                     Is <literal>foo</literal> the name of a local variable, possibly the
142                     required foo() (provided that it has been already called)?
143                     If so, this variable is used. Otherwise,
144                     <para/>
145                 </listitem>
146                 <listitem>
147                     All loaded libraries are scanned -- in anti-alphabetical order of libraries names --
148                     for the searched foo(). The first found is then "loaded" from its
149                     <literal>.bin</literal> file, and finally called. Next calls to foo()
150                     will then go up to the step #2 that will be successful, unless
151                     the <literal>foo</literal> handle has been cleared in the meantime.
152                     <para/>
153                 </listitem>
154             </orderedlist>
155         </para>
156         <para>
157             Without the step #3, a user's function not belonging to any library and that would
158             be cleared can not be automatically retrieved.
159         </para>
160         <para>
161             <warning>
162                 If the <literal>foo.sci</literal> file is modified while foo() has been already
163                 called, then recompiling and reloading its library won't update the current
164                 foo() behavior: foo() being already known, Scilab will stop at the step #2,
165                 without reloading the updated library, and will use the former foo().
166                 Entering <literal>clear foo</literal> before the next call to foo(..)
167                 will force Scilab going up to the step #3 during the next call, and so
168                 load and use the updated foo().
169             </warning>
170         </para>
171         <para>
172             <emphasis role="bold">Homonymous functions in distinct libraries: libname.foo()</emphasis>
173         </para>
174         <para>
175             If several loaded libraries have a foo() public function, the anti-alphabetical priority
176             can be unrelevant. Fortunately, it is always
177             possible to force to use the instance of a given library, with the dot-name's resolution
178             syntax:
179             <literal>libname.foo(..)</literal> will call the foo() instance belonging to the
180             <literal>libname</literal> library.
181         </para>
182     </refsection>
183     <refsection>
184         <title>Examples</title>
185         <para>
186             <literal>interpolationlib</literal> is a native Scilab library:
187         </para>
188         <programlisting role="example"><![CDATA[
189 interpolationlib        //displays the contents of the library
190 type(interpolationlib)
191 [typeof(interpolationlib), typeof(interpolationlib, "overload")]
192 string(interpolationlib)
193 [fnames, libpath] = libraryinfo("interpolationlib")
194      ]]></programlisting>
195         <para>
196             The output is illustrated in the above Description section.
197         </para>
198         <para/>
199         <para>
200             Handling calls of homonymous functions:
201         </para>
202         <programlisting role="example"><![CDATA[
203 whereis(blanks)
204 clear blanks, isdef("blanks","l")
205 blanks(20)          // loads blanks() and calls it
206 isdef("blanks","l") // It stays in the workspace
207
208 // Building a library with our own homonymous blanks() function
209 libDir = fullfile(TMPDIR, "mylib");
210 code = ["function r = blanks(n, nbsp)"
211         "    if nbsp, r = part(ascii(160),ones(1,n)),"
212         "    else r = ""ABC"","
213         "    end"
214         "endfunction" ];
215 mkdir(libDir);
216 mputl(code, libDir + filesep() + "blanks.sci");
217 genlib("mylib", libDir);    // Compiling our own library
218
219 clear blanks
220 ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
221 clear blanks
222 ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
223 blanks(3)        // Next call is with the default stringlib.blanks()
224      ]]></programlisting>
225         <screen><![CDATA[
226 --> whereis(blanks)
227  ans  =
228   "stringlib"
229
230 --> clear blanks, isdef("blanks","l")
231  ans  =
232   F
233
234 --> blanks(20)          // loads blanks() and calls it
235  ans  =
236   "                    "
237 --> isdef("blanks","l") // It stays in the workspace
238  ans  =
239   T
240
241 --> // Building a library with our own homonymous blanks() function
242 --> libDir = fullfile(TMPDIR, "mylib");
243 --> code = ["function r = blanks(n, nbsp)"
244   >         "    if nbsp, r = part(ascii(160),ones(1,n)),"
245   >         "    else r = ""ABC"","
246   >         "    end"
247   >         "endfunction" ];
248 --> mkdir(libDir);
249 --> mputl(code, libDir + filesep() + "blanks.sci");
250 --> genlib("mylib", libDir);    // Compiling our own library
251
252 --> clear blanks
253 --> ascii(blanks(3)) // stringlib.blanks() is called ⇐ "stringlib" > "mylib"
254  ans  =
255    32.   32.   32.
256
257 --> clear blanks
258 --> ascii(mylib.blanks(3,%t)) // forced call to mylib.blanks()
259  ans  =
260    194.   160.   194.   160.   194.   160.
261
262 --> blanks(3)        // Next call is with the default stringlib.blanks()
263  ans  =
264   "   "
265 ]]></screen>
266     </refsection>
267     <refsection role="see also">
268         <title>See also</title>
269         <simplelist type="inline">
270             <member>
271                 <link linkend="load">load</link>
272             </member>
273             <member>
274                 <link linkend="lib">lib</link>
275             </member>
276             <member>
277                 <link linkend="genlib">genlib</link>
278             </member>
279             <member>
280                 <link linkend="libraryinfo">libraryinfo</link>
281             </member>
282             <member>
283                 <link linkend="string">string</link>
284             </member>
285             <member>
286                 <link linkend="whereis">whereis</link>
287             </member>
288             <member>
289                 <link linkend="librarieslist">librarieslist</link>
290             </member>
291         </simplelist>
292     </refsection>
293     <refsection role="history">
294         <title>History</title>
295         <revhistory>
296             <revision>
297                 <revnumber>6.0.0</revnumber>
298                 <revdescription>
299                     <itemizedlist>
300                         <listitem>
301                             A library can now contain only functions, no longer any variables
302                             of other types.
303                         </listitem>
304                         <listitem>
305                             The lib file is now an editable XML file, no longer a binary one.
306                         </listitem>
307                         <listitem>
308                             When a foo.sci source file contains several consecutive
309                             function/endfunction blocks, only the defined foo()
310                             is now registered in the library. Other defined functions are now
311                             private and known only from foo().
312                         </listitem>
313                     </itemizedlist>
314                 </revdescription>
315             </revision>
316         </revhistory>
317     </refsection>
318 </refentry>