.TH LEXICON 2
.SH NAME
lexicon - dict client
.SH SYNOPSIS
.EX
include "bufio.m";
include "lexicon.m";
lexicon := load Lexicon Lexicon->PATH;

open:   fn(addr: string): (ref Lex, string);
fopen:  fn(fd: ref Sys->FD): (ref Lex, string);

Lex: adt {
	lexicons:       fn(l: self ref Lex): (list of (string, string), string);
	strategies:     fn(l: self ref Lex): (list of (string, string), string);
	serverinfo:     fn(l: self ref Lex): (string, string);
	lexiconinfo:    fn(l: self ref Lex, lexicon: string):
				(string, string);
	match:          fn(l: self ref Lex, word, lexicon, strategy: string):
				(list of (string, string), string);
	define:         fn(l: self ref Lex, word, lexicon: string):
				(list of (string, string, string, string), string);
	setdebug:       fn(l: self ref Lex, debug: int);
};
.EE
.SH DESCRIPTION
.B Lex
represents a connection to a dict server.  The dict protocol is specified in rfc2229.

.B Open
dials
.I addr
and performs the dict handshake.
.B Fopen
uses
.I fd
as connection and performs the dict handshake on it.  Both functions return a tuple
.RI ( "ref Lex" ", " err )
with
.I err
non-nil when an error occurred.

Once connected, the
.B lex
provides the following routines, they all have tuples of the form
.RI ( results ", " err )
with
.I err
non-nil in case of an error.

.TP
.IB lex .lexicons()
Return list of lexicons available at the server.  Each tuple is of the form
.RI ( "short name" ", " "descriptive name" ).
.TP
.IB lex .strategies()
Return list of strategies available at the server.  Each tuple is of the form
.RI ( "short name" ", " "descriptive name" ).
.TP
.IB lex .serverinfo()
Return information about the server.
.TP
.IB lex .lexiconinfo(\fIlexicon\fP)
Return information about
.IR lexicon .
.TP
.IB lex .match(\fIname\fP", "\fIlexicon\fP", "\fIstrategy\fP)
Find words in
.I lexicon
that match
.I word
using
.IR strategy .
Each tuple in the result is of the form
.RI ( lexicon ", " word ).
.TP
.IB lex .define(\fIword\fP", "\fIlexicon\fP)
Retrieve definition for
.I word
in
.I lexicon .
Each tuple in the result is of the form
.RI ( word ", " "lexicon name" ", " "lexicon description" ", " "definition" ).
.TP
.IB lex .setdebug(\fIdebug\fP)
Set debugging to
.IR debug .
``0'' suppresses all debug information, ``1'' prints all protocol messages to standard error.
.PP
For
.B match
and
.B define
special values for
.I lexicon
are recognized (by the dict server):  ``!'' for querying all databases until a match has been found, and ``*'' for querying all databases and continuing even when matches have been found.
.SH SOURCE
.B /appl/lib/lexicon.b
.SH SEE ALSO
.IR hdict (1)
.PP
``A Dictionary Server Protocol'', rfc2229.
.SH CAVEATS
Many `features' from the specification are unsupported. These include authentication, MIME responses, dict URL's, command pipelining and extensions.
.SH BUGS
Support for automatically reconnecting is missing.
.br
The error codes returned by the dict server are not parsed other than to determine whether the operation was successful.  However, the error messages returned by the functions contain the full error response from the server.
