lib loads a library of Scilab functions and variables, and sets its name

## Syntax

    namelib = lib(lib_dir)

## Arguments

lib_dir

  single path of the directory containing the lib file of the library to load. The `TMPDIR`, `SCIHOME`, `SCI`, `home` possible prefixes may be used and are expanded according to the value of corresponding predefined variables. Example: `lib("SCI/modules/atoms/atoms_internals")` will work.

namelib

  Scilab variable (of type 14 and typeof "library") addressing the loaded library (its handle). This output argument is mandatory. Otherwise, lib() sets `ans` as library's identifier, whose value will be overwritten and lost shortly after.

## Description

A Scilab library can be built with the `genlib()` function. It is made of

- a dedicated directory `lib_dir`.
- a set of .bin files created by genlib() in the directory. These files contain the binary code of compiled Scilab functions.
- a file named `lib`. This file is an XML one and so is editable. It registers the list of *.bin files (and so features) belonging to the library.

All other files belonging to `lib_dir` and not registered in the `lib` file are ignored. In particular, the original source *.sci files compiled by genlib() to create *.bin ones may indifferently remain in the directory or be removed.

`lib()` only reads the `lib` file, builds the library object accordingly, and returns its handle as `namelib`.

Then, `namelib` allows

- to get the path to the library (= `lib_dir`).
- to get the list of functions belonging to the library
- to address functions members, resolving possible names conflicts.

For more information about libraries and their assets with respect to a simple set of unbundled functions as created and loaded by `getd()`, please see the dedicated page.

`load(lib_dir+"/lib")` may be used instead of `lib()` to load the library. The library identifier is then the default one set when compiling and creating the library with `genlib()`. Its name is registered in the `lib` file.

Hence, `lib()` (re)sets the library name, while `load()` does not allow to set it.

- `namelib` is created in the current scope. It is NOT a global object. Hence, if `lib()` is used inside a function, `namelib` (and so the access to the library) will not survive when leaving the function, unless it is returned as output object.

- If `lib_dir` contains some subdirectories where some other (sub)libraries are stored, `lib(lib_dir)` does not load them recursively. If needed, `lib()` must be called for each of them.

## Examples

Loading an existing Scilab sublibrary:

    // atomsDisp() is a function belonging to the atoms_internallib Scilab sub-library.
    // This sub-library is loaded only inside the atoms manager. Outside it, the library
    // -- and so all its functions -- are unknown:
    atomsDisp("abc")

    --> atomsDisp("abc")

    Undefined variable: atomsDisp

Let's load the library with lib():

    thislib = lib("SCI/modules/atoms/macros/atoms_internals");
    thislib   // display from the library identifier

    --> thislib = lib("SCI/modules/atoms/macros/atoms_internals")
     thislib  =

    Functions files location : SCI\modules\atoms\macros\atoms_internals.

    atomsDESCRIPTIONadd  atomsDepTreeFlat  atomsAUWriteAccess  atomsDESCRIPTIONread
    atomsCompatibleVersions  atomsCloseProgressBar  atomsAutoloadLoad  atomsToremoveList
    ...
    atomsCategoryGet  atomsInstallRegister  atomsDisp  atomsToremoveRegister
    atomsRmfields  atomsGetDepParents  atomsSetInstalledList  atomsLoadInstalledStruct
    atomsDESCRIPTIONcat  atomsReadDesc  atomsDESCRIPTIONrm  atomsOpenProgressBar
    ...

Now use its atomsDisp() function:

    isdef("atomsDisp", "l") // is false: we have not yet called it.
    atomsDisp("lib() test") // This automatically scans all loaded libraries
                            //  searching for "atomsDisp". It is found in
                            //  "thislib" and automatically loaded from it.
                            // It now exists for any further calls:
    isdef("atomsDisp", "l")
    clear atomsDisp         // If it is cleared...
    whos -name atoms
    atomsDisp("Test")       // It is then automatically recovered from its library
    whos -name atoms

    --> isdef("atomsDisp", "l")
     ans  =
      F
    --> atomsDisp("lib() test")
    Testing lib()

    --> isdef("atomsDisp", "l")
     ans  =
      T
    --> clear atomsDisp         // If it is cleared...
    --> whos -name atoms        //  .. no longer defined
    Name                     Type           Size           Bytes
    atomsguilib              library                       466
    atomslib                 library                       2488

    --> atomsDisp("Test")
    Test

    --> whos -name atoms
    Name                     Type           Size           Bytes
    atomsDisp                function                      3300
    atomsguilib              library                       466
    atomslib                 library                       2488

If we delete the library handle, its members not already called become unreachable:

    clear thislib
    atomsDisp("abc")                                // still callable, since already loaded
    winid = atomsOpenProgressbar("Message", %t);    // => error

    --> atomsDisp("abc")
    abc

    --> winid = atomsOpenProgressBar("Message", %t);

    Undefined variable: atomsOpenProgressBar

Let's now use load() to reload the library:

    // The default name of the library is "atomsinternalslib"
    // It is not loaded at the Scilab startup:
    atomsinternalslib      // => error
    // Let's load it:
    load("SCI/modules/atoms/macros/atoms_internals/lib"); // We refer to the "lib" file
    or(librarieslist()=="atomsinternalslib")              // OK, now true
    whos -name at
    winid = atomsOpenProgressBar("Message", %t);         // now it works
    close(winid)

    --> atomsinternalslib
    Undefined variable: atomsinternalslib

    --> load("SCI/modules/atoms/macros/atoms_internals/lib");

    --> or(librarieslist()=="atomsinternalslib")
     ans  =
      T

    --> whos -name at
    Name                     Type           Size           Bytes
    atomsDisp                function                      3300
    atomsguilib              library                       466
    atomsinternalslib        library                       5586
    atomslib                 library                       2488

    --> winid = atomsOpenProgressBar("Message", %t);     // now it works

## See also

- load
- librarieslist
- libraryinfo
- library
- genlib
- whereis
- getd

## History

6.0 lib() no longer needs the `names` file (ignored). It now uses the `lib` file, that is now mandatory.