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_server

This method retrieves information on the server itself.

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

DICT#show_db

This method retrieves information on the databases offered by the server.

A Hash indexed on database name and containing database descriptions is returned on success, while nil is returned on failure.

DICT#show_info(database)

This method retrieves information on a particular database offered by the server.

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

DICT#show_strat

This method retrieves information on the strategies offered by the server.

A Hash indexed on strategy name and containing strategy descriptions 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

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.

BUGS

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

HISTORY

$Id: dict.rb,v 1.29 2007/05/20 00:01:36 ianmacd Exp $