Net::Dict(3pm)

📦
version 2.22 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Net::Dict(3pm) — NAME 💖

Net::Dict — client API for accessing dictionary servers (RFC 2229)

okay so this is the page from User Contributed Perl Documentation, and bestie, it's literally the whole vibe of talking to dictionary servers from Perl. 💅

✨ SYNOPSIS ✨

use Net::Dict;

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

🦋 DESCRIPTION 🦋

Net::Dict is a perl class for looking up words and their definitions on network dictionary servers. It gives you a simple DICT client API for the network protocol described in RFC2229. And quoting that RFC directly, because why paraphrase legends:

  • 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.

So one instance of Net::Dict = one connection to a single DICT server. For example, to connect to the dictionary server at dict.org, you'd write:

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

A DICT server can flex any number of dictionaries, and those are called databases. Every database has a name and a title. The name is a short identifier, usually literally one word, used to refer to that database. The title is a brief one-line description of it. 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 that 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.

🔍 MATCHING WORDS 🔍

Not only can you look up word definitions, you can also look up a list of words that match a given pattern, using the match() method. Each DICT server typically supports a bunch of strategies you can use to match words against a pattern. For example, using the prefix strategy with a pattern anti would find all the words in databases which start with anti:

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

Similarly the suffix strategy is for searching words which end in a given pattern. And the strategies() method is how you request a list of supported strategies — peep "METHODS" for the details. 💅

🎀 SELECTING DATABASES 🎀

By default Net::Dict will look in all databases on the DICT server. That's specified with a special database name of *. You can nail down the database(s) to search explicitly, as extra arguments to the define and match methods:

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

Rather than specify the databases every single time (exhausting, honestly), you can change the default from * using the setDicts method:

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

Any subsequent calls to define or match will refer to these databases, unless over-ridden with additional arguments to the method. And you can find out what databases are available on a server using the dbs method:

%dbhash = $dict->dbs();

Each entry in the returned hash has the name of a database as the key, and the corresponding title as the value. 🫶

There's another special database name — ! — which says that all databases should be searched, but as soon as a definition is found, no further databases should be searched. Iconic shortcut behavior. ✨

👑 CONSTRUCTOR 👑

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

This is the constructor for a brand new Net::Dict object. HOST is the name of the remote host on which a Dict server is running. This is required, and it must be an explicit host name — no vibes, actual 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, which resulted in selection of default hosts. This behaviour is no longer supported. So don't do that, bestie, it's giving deprecated.

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 (we love a fully spelled-out moment), 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. 💀 So like, pass the right args.

🌸 METHODS 🌸

Unless otherwise stated, all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.

🍓 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 setDicts() are used.

🍓 match ( $pattern, $strategy [, @dbs] )

Looks for words which match $pattern according to the specified matching $strategy. Returns a reference to an array, each entry of which is a reference to a two-element array: database name, matching word.

🍓 dbs

Returns a hash with information on the databases available on the DICT server. The keys are the short names, or identifiers, of the databases; the value is title of the database:

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

This is the SHOW DATABASES command from RFC 2229. 👑

🍓 dbInfo ( $dbname )

Returns a string, containing description of the dictionary $dbname.

🍓 setDicts ( @dicts )

Specify the dictionaries that will be searched during the successive define() or match() calls. Defaults to *. No existence checks are performed by this interface, so you'd better make sure the dictionaries you specify are actually on the server (e.g. by calling dbs()). Fr fr, it will not warn you. 🙈

🍓 strategies

returns an array, containing an ID of a matching strategy as a key and a verbose description as a value.

This method was previously called strats(); that name for the method is also currently supported, for backwards compatibility. Slay for legacy support. 💅

🍓 auth ( $USER, $PASSPHRASE )

Attempt to authenticate the specified user, using the scheme described on page 18 of RFC 2229. The user should be known to the server, and $PASSPHRASE is a shared secret known only to the server and the user. 🤫

For example, if you were using dictd from dict.org, your configuration file might include the following:

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"

To be able to access this database, you'd write something like the following:

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

A subsequent call to the databases method would reveal the private database now accessible. Not all servers support the AUTH extension; you can check this with the has_capability() method, described below. 🔥

🍓 serverInfo

Returns a string, containing the information about the server, provided by the server:

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

This is the SHOW SERVER command from RFC 2229.

🍓 dbTitle ( $DBNAME )

Returns the title string for the specified database. This is the same string returned by the dbs() method for all databases.

🍓 capabilities

Returns a list of the capabilities supported by the DICT server, as described on pages 7 and 8 of RFC 2229.

🍓 has_capability ( $cap_name )

Returns true (non-zero) if the DICT server supports the specified capability; false (zero) otherwise. Eg

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

🍓 status

Send the STATUS command to the DICT server, which will return some server-specific timing or debugging information. This may be useful when debugging or tuning a DICT server, but probably won't be of interest to most users. It's giving "devs only" energy. 😌

💀 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. (So that old doc was lying to you, bestie. 😭)
  • 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 distribution includes two example DICT clients: dict is a basic command-line client, and tkdict is a GUI-based client, created using Perl/Tk. 🎀

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 ⭐

  • RFC 2229 <https://tools.ietf.org/html/rfc2229> — the internet document which defines the DICT protocol.
  • 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 🧚

<https://github.com/neilbowers/Net-Dict>

okay wait, there's more of this page, keep reading bestie, we're not done yet 💖

👑 AUTHOR 💖

Okay so the origin story, because every icon has one:

  • The very first version of Net::Dict was written by Dmitry Rubinstein <dimrub@wisdom.weizmann.ac.il>, and he built it using Net::FTP and Net::SMTP as a pattern and a model for imitation. mentor energy fr fr 🧚
  • The module was then extended, and is now maintained, by Neil Bowers <neil@bowers.com> 🫶

The way this thing has a whole pass-the-torch lineage… it's giving legacy. It's giving main character energy across generations. 💅

Copyright (C) 2002-2014 Neil Bowers. All rights reserved.

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. periodt. ✨

bestie, that's the whole legal bit, no cap — three copyright holders, one shared vibe, same terms as Perl itself. Don't be weird about it. 💖

And that's a wrap on Net::Dict! 🦋 This page came from perl v5.36.0, dated 2022-10-15, and it's the manual page for Net::Dict(3pm) — so if you ever need to cite it in a group chat, you now have all the receipts. 🌈⭐ Go look up some words, bestie. You ate. 👑💜

📦 where this page comes from