NAME

SYNOPSIS

    use Net::Dict;

    $dict = Net::Dict->new('dict.server.host');
    $h    = $dict->define("word");
    foreach $i (@{$h}) {
        ($db, $def) = @{$i};
        . . .
    }

DESCRIPTION

•

The Dictionary Server Protocol (DICT) is a TCP transaction based query/response protocol that allows a client to access dictionary definitions from a set of natural language dictionary databases.

An instance of Net::Dict represents a connection to a single DICT server. For example, to connect to the dictionary server at "dict.org", you would write:

    $dict = Net::Dict->new('dict.org');

A DICT server can provide any number of dictionaries, which are referred to as databases. Each database has a name and a title. The name is a short identifier, typically just one word, used to refer to that database. The title is a brief one-line description of the database. For example, at the time of writing, the "dict.org" server has 11 databases, including a version of Webster's dictionary from 1913. The name of the database is web1913, and the title is Webster's Revised Unabridged Dictionary (1913).

To look up definitions for a word, you use the "define" method:

 $dref = $dict->define('banana');

This returns a reference to a list; each entry in the list is a reference to a two item list:

 [ $dbname, $definition ]

The first entry is a database name as introduced above. The second entry is the text of a definition from the specified dictionary.

 @mref = $dict->match('anti', 'prefix');
 foreach my $match (@{ $mref }) {
     ($db, $word) = @{ $match };
 }

 $dref = $dict->define('banana', 'wn', 'web1913');

 $dict->setDicts('wn', 'web1913');

 %dbhash = $dict->dbs();

CONSTRUCTOR

 $dict = Net::Dict->new (HOST [,OPTIONS]);

This is the constructor for a new Net::Dict object. "HOST" is the name of the remote host on which a Dict server is running. This is required, and must be an explicit host name.

The constructor makes a connection to the remote DICT server, and sends the CLIENT command, to identify the client to the server.

Note: previous versions let you give an empty string for the hostname, resulting in selection of default hosts. This behaviour is no longer supported.

"OPTIONS" are passed in a hash like fashion, using key and value pairs. Possible options are:

Port

The port number to connect to on the remote machine for the Dict connection (a default port number is 2628, according to RFC2229).

Client

The string to send as the CLIENT identifier. If not set, then a default identifier for Net::Dict is sent.

Timeout

Sets the timeout for the connection, in seconds. Defaults to 120.

Debug

The debug level - a non-zero value will resulting in debugging information being generated, particularly when errors occur. Can be changed later using the "debug" method, which is inherited from Net::Cmd. More on the debug method can be found in Net::Cmd.

Making everything explicit, here's how you might call the constructor in your client:

 $dict = Net::Dict->new($HOST,
                        Port    => 2628,
                        Client  => "myclient v$VERSION",
                        Timeout => 120,
                        Debug   => 0);

This will return "undef" if we failed to make the connection. It will "die" if bad arguments are passed: no hostname, unknown argument, etc.

METHODS

 %dbhash = $dict->dbs();
 print "Available dictionaries:\n";
 while (($db, $title) = each %dbhash) {
     print "$db : $title\n";
 }

 database private {
     data  "/usr/local/dictd/db/private.dict.dz"
     index "/usr/local/dictd/db/private.index"
     access { user connor }
 }

 user connor "there can be only one"

 $dict = Net::Dict->new('dict.foobar.com');
 $dict->auth('connor', 'there can be only one');

 print "Server Info:\n";
 print $dict->serverInfo(), "\n";

 if ($dict->has_capability('auth')) {
     $dict->auth('genie', 'open sesame');
 }

KNOWN BUGS AND LIMITATIONS

• Need to add methods for getting lists of databases and strategies in the order they're returned by the remote server. Suggested by Aleksey Cheusov.
• The following DICT commands are not currently supported:

   OPTION MIME
      

• No support for firewalls at the moment.
• Site-wide configuration isn't supported. Previous documentation suggested that it was.
• Currently no way to specify that results of define and match should be in HTML. This was also previously a config option for the constructor, but it didn't do anything.

EXAMPLES

The examples directory of the Net-Dict distribution includes two basic examples. "simple.pl" illustrates basic use of the module, and "portuguese.pl" demos use of an English to Portuguese dictionary. Thanks to Jose Joao Dias de Almeida for the examples.

SEE ALSO

Net::Cmd - a module which provides methods for a network command class, such as Net::FTP, Net::SMTP, as well as Net::Dict. Part of the libnet distribution, available from CPAN.

Digest::MD5 - you'll need this module if you want to use the auth method.

dict.org <http://www.dict.org> - the home page for the DICT effort; has links to other resources, including other libraries and clients, and "dictd", the reference DICT server.

REPOSITORY

AUTHOR

The module was extended, and is now maintained, by Neil Bowers <neil@bowers.com>

COPYRIGHT

Copyright (C) 2001 Canon Research Centre Europe, Ltd.

Copyright (c) 1998 Dmitry Rubinstein. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.