---

5.5.3 Guile API

This subsection describes callback functions that a Guile database module must provide. Each description begins with the function prototype and its entry in the virtual function table.

Callback functions can be subdivided into two groups: database functions and search functions.

Database callback functions are responsible for opening and closing databases and for returning information about them.

Guile Callback: open-db name . args ¶

Virtual table: (cons "open" open-db)

Open the database. The argument name contains database name as given in the name statement of the corresponding database block (see Databases). Optional argument args is a list of command line parameters obtained from cmdline in handler statement (see guile-cmdline). For example, if the configuration file contained:

database {
    name "foo";
    handler "guile db=file 1 no";
}

then the open-db callback will be called as:

(open-db "foo" '("db=file" "1" "no"))

The open-db callback returns a database handle, i.e. an opaque object that will subsequently be used to identify this database. This value, hereinafter named dbh, will be passed to another callback functions that need to access the database.

The return value #f or '() indicates an error.

Guile Callback: close-db dbh ¶

Virtual Table: (cons "close" close-db)

Close the database. This function is called during the cleanup procedure, before termination of dicod. The argument dbh is a database handle returned by open-db.

The return value from close-db is ignored. To communicate errors to the daemon, throw an exception.

Guile Callback: descr dbh ¶

Virtual Table: (cons "descr" descr)

Return a short textual description of the database, for use in SHOW DB output. If there is no description, returns #f or '().

The argument dbh is a database handle returned by open-db.

This callback is optional. If it is not defined, or if it returns #f ('()), the text from description statement is used (see description). Otherwise, if no description statement is present, an empty string will be returned.

Guile Callback: info dbh ¶

Virtual Table: (cons "info" info)

Return a verbose, eventually multi-line, textual description of the database, for use in SHOW INFO output. If there is no description, returns #f or '().

The argument dbh is a database handle returned by open-db.

This callback is optional. If it is not defined, or if it returns #f ('()), the text from info statement is used (see info). If there is no info statement, the string ‘No information available’ is used.

Guile Callback: lang dbh ¶

Virtual Table: (cons "lang" lang)

Return a cons of languages supported by this database: Its car is a list of source languages, and its cdr is a list of destination languages. For example, the following return value indicates that the database contains translations from English to French and Spanish:

 (cons (list "en") (list "fr" "es"))

A database is searched in a two-phase process. First, an appropriate callback is called to do the search: define-word is called for DEFINE searches and match-word is called for matches. This callback returns an opaque entity, called result handle, which is then passed to the output callback, which is responsible for outputting it.

Guile Callback: define-word dbh word ¶

Virtual Table: (cons "define" define-word)

Find definitions of word word in the database dbh. Return a result handle. If nothing is found, return #f or '().

The argument dbh is the database handle returned by open-db.

Guile Callback: match-word dbh strat key ¶

Virtual Table: (cons "match" match-word)

Find in the database dbh all headwords that match key, using strategy strat. Return a result handle. If nothing is found, return #f or '().

The key is a Dico Key object, which contains information about the word being looked for. To obtain the actual word, use the dico-key->word function (see dico-key->word).

The argument dbh is a database handle returned by open-db. The matching strategy strat is a special Scheme object that can be accessed using a set of functions described below (see Dico Scheme Primitives).

Guile Callback: result-count resh ¶

Virtual Table: (cons "result-count" result-count)

Return the number of elements in the result set resh.

Guile Callback: output resh n ¶

Virtual Table: (cons "output" output)

Output nth result from the result set resh. The argument resh is a result handle returned by define-word or match-word callback.

The data must be output to the current output port, e.g. using display or format primitives. If resh represents a match result, the output must not be quoted or terminated by newlines.

It is guaranteed that the output callback will be called as many times as there are elements in resh (as determined by the result-count callback) and that for each subsequent call the value of n equals its value from the previous call incremented by one.

At the first call n equals 0.