PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">


Ruby/DICT - client-side DICT protocol library


require 'dict'

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 }



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

CLASS METHODS, 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.



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.


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


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


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.


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:


Define or match, stopping at first database where match is found


Define or match, gathering matches from all databases


Match using a server-dependent default strategy, which should be the best strategy available for interactive spell checking


The default port used by DICT servers, namely 2628


A Regex constant matching any server status code indicating an error


Exception classes are subclasses of the container class DICTError, which is, itself, a subclass of RuntimeError, 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., 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.


Written by Ian Macdonald <>


Copyright (C) 2002 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.



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


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