PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

NAME

Ruby/DICT - client-side DICT protocol library

SYNOPSIS

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

DESCRIPTION

Ruby/DICT is a client-side library implementation of the DICT protocol, as described in RFC 2229.

CLASS METHODS

DICT.new(hosts, port = DICT::DEFAULT_PORT, debug = false, verbose = false): 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.

INSTANCE METHODS

DICT#disconnect

Disconnect from the server.

DICT#define(database, word)

Obtain definitions for word from database. A list of valid databases can be obtained using DICT#show(DICT::DATABASES).

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.

On success, this returns an array of Struct:Definition objects. nil is returned on failure.

DICT#match(database, strategy, word)

Obtain matches for word from database using strategy.

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. nil is returned on failure.

DICT#show(data_type, database = '')

This method retrieves information on the databases and strategies offered by the server, plus information on the server itself.

data_type should be DICT::DB for a list of databases, DICT::SERVER for information on the server itself, DICT::STRATEGIES for information on strategies implemented by the server, and DICT::DB for information on a particular database.

If querying for information on a particular database, database should be set to its name.

A String is returned on success, while nil is returned on failure.

DICT#status

This method returns a single line String of status information from the server.

DICT#help

This method returns a String of help information from the server, describing the commands it implements.

DICT#client

This method sends a single line String of information describing a client application to the server.

DICT#auth(user, secret)

This method attempts to authenticate user to the server using secret. Note that secret is not literally passed to the server.

CONSTANTS

Ruby/DICT uses a lot of constants, mostly for the status codes returned by DICT servers. See the source for details.

Some of the more interesting other constants:

DICT::FIRST_DATABASE: Define or match, stopping at first database where match is found
DICT::ALL_DATABASES: Define or match, gathering matches from all databases
DICT::DEFAULT_MATCH_STRATEGY: Match using a server-dependent default strategy, which should be the best strategy available for interactive spell checking
DICT::DEFAULT_PORT: The default port used by DICT servers, namely 2628
DICT::ERROR: A Regex constant matching any server status code indicating an error

EXCEPTIONS

Exception classes are subclasses of the container class DICTError, which is, itself, a subclass of RuntimeError

ConnectError.new(message, code = 2): A ConnectError is raised if DICT::new is unable to connect to the chosen DICT server for any reason. Program execution will terminate.
ProtocolError.new(message, code = 3): 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.

AUTHOR

Written by Ian Macdonald <ian@caliban.org>

COPYRIGHT

BUGS

Send all bug reports, enhancement requests and patches to the author.

HISTORY

$Id: dict.rb,v 1.20 2002/05/24 08:44:58 ianmacd Exp $