Dico |
|
GNU Dictionary Server |
Sergey Poznyakoff |
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 ignored4.
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:
- Command line options --user and --password.
- An URL given as a command line argument (see user).
- 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 onedefault
statement in autologin file. Its exact location does not matter, it will always be matched after all explicitmachine
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.
Footnotes
(4)
The same holds true for interactive mode as well, but you will hardly need comments on a terminal.
This document was generated on September 4, 2020 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.