.\" DO NOT MODIFY THIS FILE! it was generated by rd2
.TH dict.rb 3 "May 2007"
.SH NAME
.PP
Ruby/DICT \- client\-side DICT protocol library
.SH SYNOPSIS
.nf
\&    require 'dict'
\&    
\&    dict = DICT.new('dict.org', DICT::DEFAULT_PORT)
\&    dict.client('a Ruby/DICT client')
\&    definitions = dict.define(DICT::ALL_DATABASES, 'ruby')
\&    
\&    if definitions
\&      definitions.each do |d|
\&        printf("From %s [%s]:\\n\\n", d.description, d.database)
\&        d.definition.each { |line| print line }
\&      end
\&    end
\&    
\&    dict.disconnect
.fi
.SH DESCRIPTION
.PP
Ruby/DICT is a client\-side library implementation of the DICT protocol,
as described in RFC 2229.
.SH CLASS METHODS
.TP
.fi
.B
DICT.new(hosts, port = DICT::DEFAULT_PORT, debug = false, verbose = false)
.PP
This creates a new instance of the DICT class. A DICT object has four
instance variables: capabilities, code, message and
msgid. capabilities is an array of Strings relating to
capabilities implemented on the server, code is the last status
code returned by the server, message is the text of the message
related to code, and msgid is the message ID returned by the
server.
.SH INSTANCE METHODS
.TP
.fi
.B
DICT#disconnect
.PP
Disconnect from the server.
.TP
.fi
.B
DICT#define(database, word)
.PP
Obtain definitions for word from database. A list of valid
databases can be obtained using DICT#show(DICT::DATABASES).

.PP
To show just the first definition found, use DICT::FIRST_DATABASE
as the database name. To show definitions from all databases, use
DICT::ALL_DATABASES.

.PP
On success, this returns an array of Struct:Definition objects.
\fInil\fP is returned on failure.
.TP
.fi
.B
DICT#match(database, strategy, word)
.PP
Obtain matches for word from database using strategy.

.PP
On success, a hash of arrays is returned. The keys of the hash are the
database names and the values are arrays of word matches that were found
in that database. \fInil\fP is returned on failure.
.TP
.fi
.B
DICT#show_server
.PP
This method retrieves information on the server itself.

.PP
A String is returned on success, while \fInil\fP is returned on failure.
.TP
.fi
.B
DICT#show_db
.PP
This method retrieves information on the databases offered by the server.

.PP
A Hash indexed on database name and containing database descriptions
is returned on success, while \fInil\fP is returned on failure.
.TP
.fi
.B
DICT#show_info(database)
.PP
This method retrieves information on a particular database offered by
the server.

.PP
A String is returned on success, while \fInil\fP is returned on failure.
.TP
.fi
.B
DICT#show_strat
.PP
This method retrieves information on the strategies offered by the server.

.PP
A Hash indexed on strategy name and containing strategy descriptions
is returned on success, while \fInil\fP is returned on failure.
.TP
.fi
.B
DICT#status
.PP
This method returns a single line String of status information from the
server.
.TP
.fi
.B
DICT#help
.PP
This method returns a String of help information from the server,
describing the commands it implements.
.TP
.fi
.B
DICT#client
.PP
This method sends a single line String of information describing a client
application to the server.
.TP
.fi
.B
DICT#auth(user, secret)
.PP
This method attempts to authenticate user to the server using
secret. Note that secret is not literally passed to the server.
.SH CONSTANTS
.PP
Ruby/DICT uses a lot of constants, mostly for the status codes
returned by DICT servers. See the source for details.
.PP
Some of the more interesting other constants:
.TP
.fi
.B
DICT::FIRST_DATABASE
Define or match, stopping at first database where match is found
.TP
.fi
.B
DICT::ALL_DATABASES
Define or match, gathering matches from all databases
.TP
.fi
.B
DICT::DEFAULT_MATCH_STRATEGY
Match using a server\-dependent default strategy, which should be the best
strategy available for interactive spell checking
.TP
.fi
.B
DICT::DEFAULT_PORT
The default port used by DICT servers, namely 2628
.TP
.fi
.B
DICT::ERROR
A Regex constant matching any server status code indicating an error
.SH EXCEPTIONS
.PP
Exception classes are subclasses of the container class DICTError, which is,
itself, a subclass of RuntimeError
.TP
.fi
.B
ConnectError.new(message, code = 2)
.PP
A ConnectError is raised if DICT::new is unable to connect to the chosen
DICT server for any reason. Program execution will terminate.
.TP
.fi
.B
ProtocolError.new(message, code = 3)
.PP
A ProtocolError exception can be used if a server operation returns a
status code matching DICT::ERROR. This does not happen automatically. The
code is stored in the code attribute of the instance of the DICT
object. Program execution will terminate.
.SH AUTHOR
.PP
Written by Ian Macdonald <ian@caliban.org>
.SH COPYRIGHT
.nf
\&    Copyright (C) 2002\-2007 Ian Macdonald
\&    
\&    This is free software; see the source for copying conditions.
\&    There is NO warranty; not even for MERCHANTABILITY or FITNESS
\&    FOR A PARTICULAR PURPOSE.
.fi
.SH SEE ALSO
.IP
.B
\(bu
Ruby/DICT home page \- http://www.caliban.org/ruby/
.IP
.B
\(bu
The DICT development group \- http://www.dict.org/
.IP
.B
\(bu
RFC 2229 \- ftp://ftp.isi.edu/in\-notes/rfc2229.txt
.SH BUGS
.PP
Send all bug reports, enhancement requests and patches to the
author.
.SH HISTORY
.PP
$Id: dict.rb,v 1.29 2007/05/20 00:01:36 ianmacd Exp $