.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::Dict 3pm"
.TH Net::Dict 3pm "2022-10-15" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Dict \- client API for accessing dictionary servers (RFC 2229)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::Dict;
\&
\&    $dict = Net::Dict\->new(\*(Aqdict.server.host\*(Aq);
\&    $h    = $dict\->define("word");
\&    foreach $i (@{$h}) {
\&        ($db, $def) = @{$i};
\&        . . .
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Net::Dict\*(C'\fR is a perl class for looking up words and their
definitions on network dictionary servers.
\&\f(CW\*(C`Net::Dict\*(C'\fR provides a simple \s-1DICT\s0 client \s-1API\s0 for the network
protocol described in \s-1RFC2229.\s0 Quoting from that \s-1RFC:\s0
.IP "\(bu" 4
The Dictionary Server Protocol (\s-1DICT\s0) is a \s-1TCP\s0 transaction based
query/response protocol that allows a client to access dictionary
definitions from a set of natural language dictionary databases.
.PP
An instance of Net::Dict represents a connection to a single
\&\s-1DICT\s0 server. For example, to connect to the dictionary
server at \f(CW\*(C`dict.org\*(C'\fR, you would write:
.PP
.Vb 1
\&    $dict = Net::Dict\->new(\*(Aqdict.org\*(Aq);
.Ve
.PP
A \s-1DICT\s0 server can provide any number of dictionaries,
which are referred to as \fIdatabases\fR.
Each database has a \fIname\fR and a \fItitle\fR.
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 \f(CW\*(C`dict.org\*(C'\fR server
has 11 databases, including a version of Webster's
dictionary from 1913. The name of the database is \fIweb1913\fR,
and the title is \fIWebster's Revised Unabridged Dictionary (1913)\fR.
.PP
To look up definitions for a word, you use the \f(CW\*(C`define\*(C'\fR method:
.PP
.Vb 1
\& $dref = $dict\->define(\*(Aqbanana\*(Aq);
.Ve
.PP
This returns a reference to a list; each entry in the list
is a reference to a two item list:
.PP
.Vb 1
\& [ $dbname, $definition ]
.Ve
.PP
The first entry is a \fIdatabase name\fR as introduced above.
The second entry is the text of a definition from
the specified dictionary.
.SS "\s-1MATCHING WORDS\s0"
.IX Subsection "MATCHING WORDS"
In addition the looking up word definitions,
you can lookup a list of words which match a given
pattern, using the \fB\fBmatch()\fB\fR method.
Each \s-1DICT\s0 server typically supports a number of \fIstrategies\fR
which can be used to match words against a pattern.
For example, using \fBprefix\fR strategy with a pattern \*(L"anti\*(R"
would find all words in databases which start with \*(L"anti\*(R":
.PP
.Vb 4
\& @mref = $dict\->match(\*(Aqanti\*(Aq, \*(Aqprefix\*(Aq);
\& foreach my $match (@{ $mref }) {
\&     ($db, $word) = @{ $match };
\& }
.Ve
.PP
Similarly the \fBsuffix\fR strategy is used to search for words
which end in a given pattern.
The \fB\fBstrategies()\fB\fR method is used to request a list of supported
strategies \- see \*(L"\s-1METHODS\*(R"\s0 for more details.
.SS "\s-1SELECTING DATABASES\s0"
.IX Subsection "SELECTING DATABASES"
By default Net::Dict will look in all databases on the \s-1DICT\s0 server.
This is specified with a special database name of \f(CW\*(C`*\*(C'\fR.
You can specify the database(s) to search explicitly,
as additional arguments to the \fBdefine\fR and \fBmatch\fR methods:
.PP
.Vb 1
\& $dref = $dict\->define(\*(Aqbanana\*(Aq, \*(Aqwn\*(Aq, \*(Aqweb1913\*(Aq);
.Ve
.PP
Rather than specify the databases to use every time,
you can change the default from '*' using the \f(CW\*(C`setDicts\*(C'\fR method:
.PP
.Vb 1
\& $dict\->setDicts(\*(Aqwn\*(Aq, \*(Aqweb1913\*(Aq);
.Ve
.PP
Any subsequent calls to \fBdefine\fR or \fBmatch\fR will refer to these databases,
unless over-ridden with additional arguments to the method.
You can find out what databases are available on a server
using the \f(CW\*(C`dbs\*(C'\fR method:
.PP
.Vb 1
\& %dbhash = $dict\->dbs();
.Ve
.PP
Each entry in the returned hash has the name of a database as the key,
and the corresponding title as the value.
.PP
There is another special database name \- \f(CW\*(C`!\*(C'\fR \- which says that
all databases should be searched, but as soon as a definition is
found, no further databases should be searched.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.Vb 1
\& $dict = Net::Dict\->new (HOST [,OPTIONS]);
.Ve
.PP
This is the constructor for a new Net::Dict object. \f(CW\*(C`HOST\*(C'\fR is the
name of the remote host on which a Dict server is running.
This is required, and must be an explicit host name.
.PP
The constructor makes a connection to the remote \s-1DICT\s0 server,
and sends the \s-1CLIENT\s0 command, to identify the client to the server.
.PP
\&\fBNote:\fR previous versions let you give an empty string
for the hostname, resulting in selection of default hosts.
This behaviour is no longer supported.
.PP
\&\f(CW\*(C`OPTIONS\*(C'\fR are passed in a hash like fashion, using key and value pairs.
Possible options are:
.IP "\fBPort\fR" 4
.IX Item "Port"
The port number to connect to on the remote machine for the
Dict connection (a default port number is 2628, according to \s-1RFC2229\s0).
.IP "\fBClient\fR" 4
.IX Item "Client"
The string to send as the \s-1CLIENT\s0 identifier.
If not set, then a default identifier for Net::Dict is sent.
.IP "\fBTimeout\fR" 4
.IX Item "Timeout"
Sets the timeout for the connection, in seconds.
Defaults to 120.
.IP "\fBDebug\fR" 4
.IX Item "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 \f(CW\*(C`debug\*(C'\fR method,
which is inherited from Net::Cmd.
More on the debug method can be found in Net::Cmd.
.PP
Making everything explicit, here's how you might call
the constructor in your client:
.PP
.Vb 5
\& $dict = Net::Dict\->new($HOST,
\&                        Port    => 2628,
\&                        Client  => "myclient v$VERSION",
\&                        Timeout => 120,
\&                        Debug   => 0);
.Ve
.PP
This will return \f(CW\*(C`undef\*(C'\fR if we failed to make the connection.
It will \f(CW\*(C`die\*(C'\fR if bad arguments are passed: no hostname,
unknown argument, etc.
.SH "METHODS"
.IX Header "METHODS"
Unless otherwise stated all methods return either a \fItrue\fR or \fIfalse\fR
value, with \fItrue\fR meaning that the operation was a success. When a method
states that it returns a value, failure will be returned as \fIundef\fR or an
empty list.
.ie n .SS "define ( $word [, @dbs] )"
.el .SS "define ( \f(CW$word\fP [, \f(CW@dbs\fP] )"
.IX Subsection "define ( $word [, @dbs] )"
returns a reference to an array, whose members are lists,
consisting of two elements: the dictionary name and the definition.
If no dictionaries are specified, those set by \fBsetDicts()\fR are used.
.ie n .SS "match ( $pattern, $strategy [, @dbs] )"
.el .SS "match ( \f(CW$pattern\fP, \f(CW$strategy\fP [, \f(CW@dbs\fP] )"
.IX Subsection "match ( $pattern, $strategy [, @dbs] )"
Looks for words which match \f(CW$pattern\fR according to the specified
matching \f(CW$strategy\fR.
Returns a reference to an array,
each entry of which is a reference to a two-element
array: database name, matching word.
.SS "dbs"
.IX Subsection "dbs"
Returns a hash with information on the databases available
on the \s-1DICT\s0 server.
The keys are the short names, or identifiers, of the databases;
the value is title of the database:
.PP
.Vb 5
\& %dbhash = $dict\->dbs();
\& print "Available dictionaries:\en";
\& while (($db, $title) = each %dbhash) {
\&     print "$db : $title\en";
\& }
.Ve
.PP
This is the \f(CW\*(C`SHOW DATABASES\*(C'\fR command from \s-1RFC 2229.\s0
.ie n .SS "dbInfo ( $dbname )"
.el .SS "dbInfo ( \f(CW$dbname\fP )"
.IX Subsection "dbInfo ( $dbname )"
Returns a string, containing description of
the dictionary \f(CW$dbname\fR.
.ie n .SS "setDicts ( @dicts )"
.el .SS "setDicts ( \f(CW@dicts\fP )"
.IX Subsection "setDicts ( @dicts )"
Specify the dictionaries that will be
searched during the successive \fBdefine()\fR or \fBmatch()\fR calls.
Defaults to '*'.
No existence checks are performed by this interface, so you'd better make
sure the dictionaries you specify are on the server (e.g. by calling
\&\fBdbs()\fR).
.SS "strategies"
.IX Subsection "strategies"
returns an array, containing an \s-1ID\s0 of a matching strategy
as a key and a verbose description as a value.
.PP
This method was previously called \fBstrats()\fR;
that name for the method is also currently supported,
for backwards compatibility.
.ie n .SS "auth ( $USER, $PASSPHRASE )"
.el .SS "auth ( \f(CW$USER\fP, \f(CW$PASSPHRASE\fP )"
.IX Subsection "auth ( $USER, $PASSPHRASE )"
Attempt to authenticate the specified user, using the scheme
described on page 18 of \s-1RFC 2229.\s0
The user should be known to the server, and \f(CW$PASSPHRASE\fR
is a shared secret known only to the server and the user.
.PP
For example, if you were using dictd from dict.org,
your configuration file might include the following:
.PP
.Vb 5
\& 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"
.Ve
.PP
To be able to access this database, you'd write
something like the following:
.PP
.Vb 2
\& $dict = Net::Dict\->new(\*(Aqdict.foobar.com\*(Aq);
\& $dict\->auth(\*(Aqconnor\*(Aq, \*(Aqthere can be only one\*(Aq);
.Ve
.PP
A subsequent call to the \f(CW\*(C`databases\*(C'\fR method would
reveal the \f(CW\*(C`private\*(C'\fR database now accessible.
Not all servers support the \s-1AUTH\s0 extension;
you can check this with the \fBhas_capability()\fR method,
described below.
.SS "serverInfo"
.IX Subsection "serverInfo"
Returns a string, containing the information about the server,
provided by the server:
.PP
.Vb 2
\& print "Server Info:\en";
\& print $dict\->serverInfo(), "\en";
.Ve
.PP
This is the \f(CW\*(C`SHOW SERVER\*(C'\fR command from \s-1RFC 2229.\s0
.ie n .SS "dbTitle ( $DBNAME )"
.el .SS "dbTitle ( \f(CW$DBNAME\fP )"
.IX Subsection "dbTitle ( $DBNAME )"
Returns the title string for the specified database.
This is the same string returned by the \f(CW\*(C`dbs()\*(C'\fR method
for all databases.
.SS "capabilities"
.IX Subsection "capabilities"
Returns a list of the capabilities supported by the \s-1DICT\s0 server,
as described on pages 7 and 8 of \s-1RFC 2229.\s0
.ie n .SS "has_capability ( $cap_name )"
.el .SS "has_capability ( \f(CW$cap_name\fP )"
.IX Subsection "has_capability ( $cap_name )"
Returns true (non-zero) if the \s-1DICT\s0 server supports the
specified capability; false (zero) otherwise. Eg
.PP
.Vb 3
\& if ($dict\->has_capability(\*(Aqauth\*(Aq)) {
\&     $dict\->auth(\*(Aqgenie\*(Aq, \*(Aqopen sesame\*(Aq);
\& }
.Ve
.SS "status"
.IX Subsection "status"
Send the \s-1STATUS\s0 command to the \s-1DICT\s0 server,
which will return some server-specific timing
or debugging information.
This may be useful when debugging or tuning a \s-1DICT\s0 server,
but probably won't be of interest to most users.
.SH "KNOWN BUGS AND LIMITATIONS"
.IX Header "KNOWN BUGS AND LIMITATIONS"
.IP "\(bu" 4
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.
.IP "\(bu" 4
The following \s-1DICT\s0 commands are not currently supported:
.Sp
.Vb 1
\& OPTION MIME
.Ve
.IP "\(bu" 4
No support for firewalls at the moment.
.IP "\(bu" 4
Site-wide configuration isn't supported. Previous documentation
suggested that it was.
.IP "\(bu" 4
Currently no way to specify that results of define and match
should be in \s-1HTML.\s0 This was also previously a config option
for the constructor, but it didn't do anything.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The distribution includes two example \s-1DICT\s0 clients:
\&\fBdict\fR is a basic command-line client, and \fBtkdict\fR
is a GUI-based client, created using Perl/Tk.
.PP
The \fBexamples\fR directory of the Net-Dict distribution
includes two basic examples.
\&\f(CW\*(C`simple.pl\*(C'\fR illustrates basic use of the module,
and \f(CW\*(C`portuguese.pl\*(C'\fR demos use of an English to Portuguese
dictionary. Thanks to Jose Joao Dias de Almeida for the examples.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1RFC 2229\s0 <https://tools.ietf.org/html/rfc2229> \-
the internet document which defines the \s-1DICT\s0 protocol.
.PP
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 \s-1CPAN.\s0
.PP
Digest::MD5 \- 
you'll need this module if you want to use the \fBauth\fR method.
.PP
dict.org <http://www.dict.org> \-
the home page for the \s-1DICT\s0 effort; has links to other resources,
including other libraries and clients, and \f(CW\*(C`dictd\*(C'\fR,
the reference \s-1DICT\s0 server.
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/neilbowers/Net\-Dict>
.SH "AUTHOR"
.IX Header "AUTHOR"
The first version of Net::Dict was written by
Dmitry Rubinstein <dimrub@wisdom.weizmann.ac.il>,
using Net::FTP and Net::SMTP as a pattern and a model for imitation.
.PP
The module was extended, and is now maintained, by
Neil Bowers <neil@bowers.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2002\-2014 Neil Bowers. All rights reserved.
.PP
Copyright (C) 2001 Canon Research Centre Europe, Ltd.
.PP
Copyright (c) 1998 Dmitry Rubinstein. All rights reserved.
.PP
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.