Dico

7 Dico — a client program.

The dico program is a console-based utility for querying dictionary servers. It has two operation modes. In single query mode, the utility performs a query, displays its result and exits immediately. This mode is entered if a word or a URL was given in the command line. In interactive mode, the utility enters a read-and-eval loop, in which it reads requests from the keyboard, performs the necessary searches, and displays obtained results on the screen.

7.1 Single Query Mode

The simplest way to use dico utility is to invoke it with a word as an argument, e.g.:

$ dico entdeckung

In the example above, the utility will search definitions of the word ‘entdeckung’ using its default server name and database. The default server name is read from the initialization file (see Initialization File). If it is not present, a predefined value specified at configuration time (see Default Server) is used. The default database is ‘!’, which means “search in all available databases until a match is found, and then display all matches in that database”.

There are two ways to change these defaults. First, you can use command line options. Secondly, you can use a DICT URL. Which method to use depends on your preferences. Both methods provide the same functionality for querying word definitions. However, command line options allow the user to query additional data from the server, which is impossible using URLs.

7.1.1 Dico Command Line Options

To connect to a particular dictionary server, use the --host option, for example:

$ dico --host dico.org entdeckung

To search in a particular database, use the --database (-d) option. For example, to display definitions from all databases:

$ dico --database '*' entdeckung

Note single quotes around the asterisk.

To get a list of databases offered by the server, use the --dbs (-D) option. In this case you may not give any non-option arguments. For example:

$ dico --dbs

If you wish to get a list of matches, instead of definitions, use the --match (-m) option. For example, the following invocation will display all matches from all the databases:

$ dico --database '*' --match entdeckung

The match mode uses ‘.’ strategy by default (see strategy), which means a server-dependent default strategy, which suits best for interactive spell checking. To select another strategy, use the --strategy (-s) option.

If the remote server supports ‘xlev’ experimental capability (see XLEV, you may use the --levdist (--levenshtein-distance) option to set maximum Levenshtein distance, for example:

$ dico --levdist 2 --match entdeckung

Note that setting the distance too high is impractical and may imply unnecessary strain on the server.

To get a list of available matching strategies, with descriptions, use the --strategies (-S) option.

7.1.2 DICT URL

Another way to specify data for a query is by using URL, instead of a word to search, as in the example below:

$ dico dict://gnu.org.ua/d:entdeckung

A DICT URL consists of the following parts:

dict://user;pass@host:port/d:word:database:n
dict://user;pass@host:port/m:word:database:strat:n

The ‘/d’ syntax requests the definition of word, whereas the ‘/m’ syntax queries for matches, and is similar to the --match option. Some or all of ‘user;pass@’, ‘:port’, database, strat, and and n may be omitted. The meaning of all URL parts and their default values (if appropriate) are explained in the table below:

user

The user name to use in authentication. Similar to the --user option. If user is omitted and cannot be retrieved by other means, no authentication is attempted. See Autologin, for a detailed description of authentication procedure and sources which are used to obtain authentication credentials.

pass

A shared key (password) for that user. This part is similar to the --key command line option.

For compatibility with other URLs, dico tolerates a colon (instead of semicolon) as a delimiter between user and pass.

If user is given, but pass is not, dico will ask you to supply a password interactively (see Autologin).

host

Host name, IPv4 address, or IPv6 address (in square brackets) of the server to query. Same as the --host command line option.

port

Port number or service name (from /etc/services). If it is not present, the default of 2628 is used.

Same as the --port command line option.

word

The word to look for.

database

The database to search in. If not given, ‘!’ is assumed.

Same as the --database command line option.

strat

The matching strategy to use. If omitted, ‘.’ is assumed.

Same as the --strategy command line option.

n

Extract and display the nth definition of the word. If omitted, all definitions are displayed.

There is no command line option equivalent for this parameter, because it is used rarely.

Trailing colons may be omitted. For example, the following URLs might specify definitions or matches:

dict://dict.org/d:shortcake:
dict://dict.org/d:shortcake:*
dict://dict.org/d:shortcake:wordnet:
dict://dict.org/d:shortcake:wordnet:1
dict://dict.org/d:abcdefgh
dict://dict.org/d:sun
dict://dict.org/d:sun::1
dict://dict.org/m:sun
dict://dict.org/m:sun::soundex
dict://dict.org/m:sun:wordnet::1
dict://dict.org/m:sun::soundex:1
dict://dict.org/m:sun:::

7.2 Interactive Mode

If neither word nor URL nor any operation mode option were given on the command line, dico enters interactive mode. In this mode it reads commands from the standard input, executes them and displays results on the standard output. If the standard input is connected to a terminal, the readline and history facilities are enabled (see Command Line Editing in GNU Readline Library).

When in interactive mode, dico displays its prompt and waits for you to enter a command. The default prompt is the name of the program, followed by a ‘greater than’ sign and a single space:

dico> _

The input syntax is designed so as to save you the maximum amount of typing.

If you type any word, the default action is to look up its definition using the default server and database settings, for example:

dico> man
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
man  <n.>

    mwanamume

To match the word, instead of defining it, prefix it with a slash, much as you do in vi:

dico> /man
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
0) ``can''
1) ``man''
2) ``many''
3) ``map''
4) ``may''
5) ``men''

Displayed is a list of matches retrieved using the default strategy. To see a definition for a particular match, type the number shown at its left. For example, to define “men”:

dico> 5
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
men <n.>

    wanaume

Define and match are two basic actions. To discern from them, the rest of dico commands begin with a command prefix, a single punctuation character selected for this purpose. The default command prefix is a dot, but it can be changed using the prefix command (see prefix).

We will discuss the dico commands in the following subsections.

7.2.1 Server Commands

The open command establishes connection to a remote server. It takes up to two arguments, first of them specifying the IP or host name of the server, and the optional second one specifying the port number to connect to. For example:

dico> .open gnu.org.ua

If any or both of its arguments are absent, the open command reuses the value supplied with its previous invocation, or, if it is issued for the first time, the default values. The default for server name is ‘gnu.org.ua’ and the default port number is 2628. Both values can be changed at configuration time, see Default Server for a detailed instruction.

When given one argument, open checks if it begins with a directory separator (‘/’). If so, the argument is handled as the full file name of a UNIX socket.

Note that you are not required to issue this command. If it is not given, dico will attempt to establish a connection using its default settings before executing any command that requires a connection to the server.

The close command closes the connection. It does not take any arguments.

7.2.2 Database and Strategy

The database command changes or displays the database name which is used by define and match commands. To display the database name, type the command without arguments:

dico> .database
!

To change the database, give its name as an argument to the command:

dico> .database *

Once the connection with the server is established, you may use command line completion facility to select the database from among those offered by the server. Typing TAB will show you a list of databases that begin with the characters you typed:

dico> .database enTAB
en-pl-naut  eng-afr     eng-deu     eng-swa

If you supply enough characters to identify a single choice, TAB will automatically select it. In the example above, typing a TAB after

dico> .database en-

completes the database name to:

dico> .database en-pl-naut

The strategy command displays or changes the default strategy name. As with database, the strategy completion is available for this command.

dico> .strategy
.
dico> .strategy dlev

If the remote server supports ‘xlev’ experimental capability (see XLEV), you can use the distance command to set the maximum Levenshtein distance for strategies that use Levenshtein algorithm. If used without arguments, this command displays the distance reported by the server and the configured distance, e.g.:

dico> .distance
Reported Levenshtein distance: 1
No distance configured

If used with a single numeric argument, it attempts to set the distance to the supplied value.

7.2.3 Informational Commands

The ls command lists available strategies (see SHOW STRAT):

dico> .ls
exact "Match words exactly"
prefix "Match word prefixes"
soundex "Match using SOUNDEX algorithm"
all "Match everything (experimental)"
lev "Match headwords within given Levenshtein distance"
dlev "Match headwords within given Damerau-Levenshtein
      distance"
re "POSIX 1003.2 (modern) regular expressions"
regexp "Old (basic) regular expressions"
suffix "Match word suffixes"
rev-qu "Reverse search in Quechua databases"

The ld command lists available databases (see SHOW DB):

dico> .ld
eng-swa "English-Swahili xFried/FreeDict Dictionary"
swa-eng "Swahili-English xFried/FreeDict Dictionary"
afr-eng "Afrikaans-English FreeDict Dictionary"
eng-afr "English-Afrikaans FreeDict Dictionary"

The info command displays information about a database, whose name is given as its argument. If used without arguments, it displays information about the current database.

dico> .info pl-en-naut
pl-en-naut - A Polish-English dictionary of nautical terms.
Copyright (C) 2008 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License, Version 1.2 or any later version published by the
Free Software Foundation; with no Invariant Sections, no
Front-Cover and Back-Cover Texts.

7.2.4 History Commands

Each issued command is stored in a history list and assigned a unique event number. When dico exits, it saves the command history to a file named .dico_history in your home directory. Upon startup, it retrieves the history from this file, so the history is preserved between sessions.

You can view the command history using the history command:

dico> .history
  1) .open dict.org
  2) entdeckung
  3) /geschwindigkeit

A number of editing commands is provided, that allow you to refer to previous events from the history list and to edit them. For example, to re-issue the 3rd event from the above list, type ‘!3’. The command with this index will be inserted at the dico prompt and you will be given a possibility to edit it. For a detailed description of all history-editing commands, please refer to Using History Interactively in GNU History User Manual.

7.2.5 Pager

When a command produces output that contains more lines than there are rows on the terminal, dico attempts to use a pager program to display it. The name (and arguments) of the pager program are taken from the dico internal variable, or, if it is not set, from the PAGER environment variable.

The dico pager setting can be examined or changed using the pager command. When used without arguments, it displays the current setting:

dico> .pager
less
(Pager set from environment)

When used with a single argument, it sets the pager:

dico> .pager "less -R"

The argument ‘-’ (a dash) disables pager.

7.2.6 Program Settings

The commands described in this subsection are designed mostly for use in dico initialization file (see Initialization File).

The autologin command sets the name of autologin file to be used for authentication. When used without arguments, it displays the current setting. The argument to autologin command is subject to tilde expansion, i.e. if it begins with ‘~/’, this prefix is replaced with the name of the current user home directory, followed by ‘/’. Similarly, a prefix ‘~login/’ is replaced by the home directory for user login, followed by a slash.

See Autologin, for a detailed discussion of the autologin feature.

The quiet command toggles the display of dico startup banner. When started, dico prints a short list of information useful for beginning users: the program version and warranty conditions and a command to get help, e.g.:

dico 2.10
Copyright (C) 2005-2016 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and
redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Type ? for help summary

dico>

If you find this output superfluous and useless, you can suppress it by setting

quiet yes

in your initialization file.

7.2.7 Session Transcript

Session transcript is a special mode, which displays raw DICT commands and answers as they are executed. It is useful for debugging purposes.

You enable session transcript by issuing the following command:

dico> .transcript yes
# or
dico> .transcript on

Starting from then, each DICT transaction will be displayed on standard error output, for example:

dico> .open
dico: Debug: S:220 Pirx.gnu.org.ua dicod (dico 2.10)
  <mime.xversion.xlev> <32004.1216639476@gnu.org.ua>
dico: Debug: C:CLIENT "dico 1.99.91"
dico: Debug: S:250 ok
dico: Debug: C:SHOW DATABASES
dico: Debug: S:110 26 databases present
…
dico: Debug: S:.
dico: Debug: S:250 ok
dico: Debug: C:SHOW STRATEGIES
dico: Debug: S:111 10 strategies present: list follows
dico: Debug: S:exact "Match words exactly"
dico: Debug: S:prefix "Match word prefixes"
dico: Debug: S:soundex "Match using SOUNDEX algorithm"
…
dico: Debug: S:.
dico: Debug: S:250 ok

In the example above, ellipses are used to replace long lists of data. As you see, session transcripts may produce large amount of output.

To turn the session transcript off, use the following command:

dico> .transcript no
# or
dico> .transcript off

Finally, to query the current state of session transcript, issue this command without arguments:

dico> .transcript
transcript is on

7.2.8 Other Commands

The prefix command queries or changes the current command prefix:

dico> .prefix
Command prefix is .
dico> .prefix @
dico> @prefix
Command prefix is @

The prompt command changes the dico command line prompt. For example, to change it to ‘dico$’, followed by a single space, type:

dico> .prompt "dico$ "
dico$ _

Note the use of quotes to include the space character in the argument.

The help command displays a short command usage summary. For convenience, a single question mark can be used instead of it:

dico> ?
/WORD                    Match WORD.
/                        Redisplay previous matches.
NUMBER                   Define NUMBERth match.
!NUMBER                  Edit NUMBERth previous command.

.open [HOST [PORT]]      Connect to a DICT server.
.close                   Close the connection.
…

The version command displays the package name and version number, and the warranty command displays the copyright statement.

Finally, the quit command leaves the dico shell. Typing end-of-file character (C-d) has the same effect.

7.2.9 Dico Command Summary

For convenience, this subsection lists all available dico commands along with their short description and a reference to the part of this manual where they are described in detail. The command names are given without prefix.

open host port

Connect to a DICT server. Both arguments are optional. If any of them is absent, the value supplied with the previous open command is used. If there was no previous value, the default is used, i.e., ‘gnu.org.ua’ for host, and 2628 for port.

See open.

close

Close the connection.

See close.

autologin [file]

Set or display the autologin file name.

See Autologin.

sasl [bool]

Without argument, show whether the SASL authentication is enabled. With argument, enable or disable it, depending on the value of bool. See Autologin.

database [name]

Set or display the current database name.

See database.

strategy [name]

Set or display the current strategy name.

See strategy.

distance [num]

Set or query Levenshtein distance. This command takes effect only if the remote server supports ‘xlev’ experimental capability (see XLEV).

See distance.

ls

List available matching strategies.

See ls.

ld

List all accessible databases.

See ld.

info [db]

Display information about the database db, or the current database, if used without argument.

prefix [c]

Set or display the command prefix.

See prefix.

transcript [bool]

Set or display session transcript mode.

See Session Transcript.

verbose [number]

Set or display debugging verbosity level. Currently (as of version 2.10) it is a no-op.

prompt string

Change command line prompt.

See prompt.

pager string

Change or display pager settings.

See Pager.

history

Display command history.

See History Commands.

help

Display short command usage summary.

See help.

version

Print program version.

See version.

warranty

Print copyright statement.

See warranty.

quiet bool

Toggle display of dico welcome banner. This command can be used only in initialization file.

See quiet.

quit

Quit the shell.

See quit.

7.3 Initialization File

When you start dico, it automatically executes commands from its initialization files (or init files, for short), normally called .dico. Two init files are read: the one located in your home directory, and the one from the current working directory. It is not an error if any or both of these files are absent.

These files contain a series of dico commands, as described in Interactive Mode, with the only difference that no command prefix is used by default. The ‘#’ character introduces a comment: any characters from (and including) ‘#’ up to the newline character are ignored⁴.

Init files are useful to change the defaults for your dico invocation. Consider, for example, this init file:

# An example init file for dico

# Turn the welcome banner off
quiet yes
# Set the location of autologin file
autologin ~/.dicologin
# Use this server by default
open dict.org
# Search in all databases
database *
# Finally, set the custom command prefix
prefix :

Notice, that if you wish to change your command prefix, it is preferable to do it as a last command in your init file, as shown in this example.

7.4 Autologin

After connecting to a remote server, dico checks if the server supports authentication and attempts to authenticate itself if so. To do this dico needs a set of parameters called user credentials. The exact set of credentials depends on the authentication mechanism being used, with user name and password being the two most important ones.

The user credentials can be supplied from the following sources:

1. Command line options --user and --password.
2. An URL given as a command line argument (see user).
3. Autologin files.

These three sources are consulted in that order, i.e., a user name supplied with the --user command line option takes precedence over the one found in an URL and over any names supplied by autologin files.

If, after consulting all these sources, the user name is established, while the password is not, the resulting action depends on whether the standard input is connected to a terminal. If it is, dico will ask the user to supply a password. If it is not, authentication is aborted and connection to the server is closed.

Some authentication mechanisms require additional credentials. For example, GSSAPI authentication requires a service name. These credentials can be supplied only in autologin file.

Autologin file is a plaintext file that contains authentication information for various DICT servers. At most two autologin files are consulted: first the session-specific file, if it is supplied by autologin command (see autologin) or by the --autologin command line option, next the default file .dicologin in the user’s home directory. The default autologin file is examined only if no matching record was found in the session-specific one.

The autologin file format is similar to that of .netrc file used by ftp utility.

Comments are introduced by a pound sign. Anything starting from ‘#’ up to the end of physical line is ignored.

Empty lines and comments are ignored.

Non-empty lines constitute statements. Tokens in a statement are separated with spaces, tabs, or newlines. A valid statement must begin with one of the following:

machine name

This statement contains parameters for authenticating on machine name.

default

This statement contains parameters for authenticating on any machine, except those explicitly listed in machine statements. There can be at most one default statement in autologin file. Its exact location does not matter, it will always be matched after all explicit machine statements.

During the lookup, dico searches the autologin file for a machine statement whose name matches the remote server name as given by --host command line option, host part of an URL (see urls), or the argument to the open command (see open). If it reaches end of the file without having found such an entry, it uses the default value, if available.

Once a matching entry is found, its subsequent tokens are analyzed. The following tokens are recognized:

login name

Supply user name for this server.

password string

Supply a password.

noauth

Do not perform authentication on this machine.

sasl

Enable SASL authentication.

nosasl

Disable SASL authentication.

mechanisms list

Declare acceptable SASL mechanisms. The list argument is a comma-separated list of mechanism names, without intervening whitespace. Multiple mechanisms may be given, in which case the corresponding lists are concatenated.

service name

Declare service name, for authentication methods that need it. If this token is omitted, the default service name ‘dico’ is used.

realm name

Declare realm for authentication.

host name

Set host name for this machine. By default, it is determined automatically.

Consider the following autologin entry, for example:

machine a.net user smith password guessme
machine b.net
  sasl
  mechanisms gssapi,digest-md5
  realm example.net
  service dico
  user smith password guessme
default noauth

When connecting to the server ‘a.net’, dico will attempt the usual APOP authentication as user ‘smith’ with password ‘guessme’. When connecting to the machine ‘b.net’, it will use SASL authentication, via either GSSAPI or DIGEST-MD5 mechanisms, with realm name ‘example.net’, service name ‘dico’ and the same user name and password, as for ‘a.net’.

The authentication mechanism is suppressed if the --noauth option has been given in the command line, or a matching entry was found in one of the autologin files, which contained the noauth keyword.

7.5 Dico invocation

This section contains a short summary of dico command line options.

Command Line

The following table summarizes the four existing ways of dico invocation:

dico [options] word

Connect to the dictionary and define or match a word.

See dico options.

dico [options] url

Connect to the dictionary and define or match a word, supplied in the url.

See urls.

dico [options] opmode

Connect to the dictionary and query the information required by opmode option, which is one of --dbs, --strategies, --serverhelp, --info, or --serverinfo. See below (see Operation modes) for a description.

dico [options]

Start interactive shell. See Interactive Mode.

Server selection options:

--host=server

Connect to this server.

See –host.

--port=port

-p port

Specify the port to connect to. The argument port can be either a port number or its symbolic service name, as listed in /etc/services.

--database=name

-d name

Select a database to search. The name can be either a name of one of the databases offered by the server (as returned by --dbs option), or one of the predefined database names: ‘!’ or ‘*’.

See –database.

--source=addr

Set source address for TCP connections.

Operation modifiers

--match

-m

Match instead of define.

See –match.

--strategy=name

-s name

Select a strategy for matching. The argument is either a name of one of the matching strategies supported by server (as displayed by --strategies option) or a dot (‘.’) meaning a server-dependent default strategy.

This option implies --match.

See –strategy.

--levdist=n

--levenshtein-distance=n

Sets maximum Levenshtein distance. Allowed values of n are between 1 and 9 inclusively. This option has effect only if the remote server supports ‘xlev’ extension (see XLEV).

See –levdist.

--quiet

-q

Do not print the normal dico welcome banner when entering interactive shell.

See quiet.

Operation modes

--dbs

-D

Show available databases.

See –dbs.

--strategies

-S

Show available search strategies.

See –strategies.

--serverhelp

-H

Show server help.

--info=dbname

-i dbname

Show information about database dbname.

--serverinfo

-I

Show information about the server.

Authentication

--noauth

-a

Disable authentication.

See Autologin.

--sasl

Enable SASL authentication, if the server supports it. See Autologin.

--nosasl

Disable SASL authentication. See Autologin.

--user=name

-u name

Set user name for authentication.

See Autologin.

--key=string

-k string

--password=string

Set shared secret for authentication.

See Autologin.

--autologin=name

Set the name of autologin file to use.

See Autologin.

--client=string

-c string

Additional text for client command, instead of the default ‘GNU dico 2.10’.

Debugging options

--transcript

-t

Enable session transcript. See Session Transcript, for a description.

--verbose

-v

Increase debugging verbosity level.

--time-stamp

Include time stamp in the debugging output.

--source-info

Include source line information in the debugging output.

Other options

--help

-h

Display a short description of command line options.

--usage

Display a short usage message

--version

Print program version.