![]() |
Dico |
GNU Dictionary Server |
Sergey Poznyakoff |
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 correspondingdatabase
block (see Databases). Optional argument args is a list of command line parameters obtained from cmdline inhandler
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 argumentdbh
is a database handle returned byopen-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 fromdescription
statement is used (see description). Otherwise, if nodescription
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 frominfo
statement is used (see info). If there is noinfo
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: Itscar
is a list of source languages, and itscdr
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
ormatch-word
callback.The data must be output to the current output port, e.g. using
display
orformat
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 theresult-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.
This document was generated on September 4, 2020 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.