lib/dict.rb

# 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-2003 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.

# SEE ALSO

- Ruby/DICT home page - http://www.caliban.org/ruby/
- The DICT development group - http://www.dict.org/
- RFC 2229 - ftp://ftp.isi.edu/in-notes/rfc2229.txt

# BUGS

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

# HISTORY

$Id: dict.rb,v 1.25 2003/04/19 06:53:41 ianmacd Exp $