4.3.11 Database Modules and Handlers

A database module is an external piece of software designed to handle a particular format of dictionary databases. This piece of software is built as a shared library that dicod loads at run time.

A handler is an instance of the database module loaded by dicod and configured for a specific database or a set of databases.

Database handlers are defined using the following block statement:

Configuration: load-module string { … } ¶

Create an instance of a database module. The argument specifies a unique name which will be used by subsequent parts of the configuration to refer to this handler. The ellipsis in the description above represents sub-statements. As of Dico version 2.11.90 only one sub-statement is defined:

load-module config: command string ¶

Sets the command line for this handler. It is similar to the shell’s command line in that it consists of a name of database module, optionally followed by a whitespace-separated list of its arguments. The name of the module specifies the disk file to load (see below for a detailed description of the loading sequence). Both command name and arguments are passed to the module initialization function (see dico_init).

For example:

load-module dict {
  command "dictorg dbdir=/var/dicodb";
}

This statement defines a handler named ‘dict’, which loads the module dictorg and passes its initialization function a single argument, ‘dbdir=/var/dicodb’. If the module name is not an absolute file name, as in this example, the loadable module will be searched in the module load path.

A common case is when the module does not require initialization arguments and its command string is the same as its name, e.g.:

load-module outline {
  command "outline";
}

The configuration syntax provides a shortcut for such usage:

load-module outline;

If load-module is used this way, it accepts a single string or a list of strings as its argument. In the latter case, it loads all modules listed in the argument. For example:

load-module (stratall,substr,word);

A module load path is an internal list of directories which dicod scans in order to find a loadable file name specified in the command statement. By default the search order is as follows:

1. Optional prefix search directories specified by the prepend-load-path directive (see below) and the --load-dir (-L) command line option.
2. GNU Dico module directory: $prefix/lib/dico.
3. Additional search directories specified by the module-load-path directive (see below).
4. The value of the environment variable LTDL_LIBRARY_PATH.
5. The system dependent library search path (e.g. on GNU/Linux it is defined by the file /etc/ld.so.conf and the environment variable LD_LIBRARY_PATH).

The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a colon-separated list of absolute directory names, for example ‘/usr/lib/mypkg:/lib/foo’.

In any of these directories, dicod first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to it:

1. the libtool archive suffix ‘.la’
2. the suffix used for native dynamic libraries on the host platform, e.g., ‘.so’, ‘.sl’, etc.

Configuration: module-load-path list ¶

This directive adds the directories listed in its argument to the module load path. Example:

module-load-path (/usr/lib/dico,/usr/local/dico/lib);

Configuration: prepend-load-path list ¶

Same as module-load-path, but adds directories to the beginning of the module load path.