<?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="en" xml:id="library">
    <refnamediv>
        <refname>library</refname>
        <refpurpose>library datatype
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            <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>
            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>
            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>
            <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>
            <emphasis role="bold">Homonymous functions in distinct libraries: libname.foo()</emphasis>
        </para>
        <para>
            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[
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="whereis">whereis</link>
            </member>
            <member>
                <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>
