DragonFly On-Line Manual Pages
DICT(1) DICT(1)
NAME
dict - DICT Protocol Client
SYNOPSIS
dict word
dict [options] [word]
dict [options] dict://host:port/d:word:database
dict [options] dict://host:port/m:word:database:strategy
DESCRIPTION
dict is a client for the Dictionary Server Protocol (DICT), a TCP
transaction based query/response protocol that provides access to
dictionary definitions from a set of natural language dictionary
databases. Exit status is 0 if operation succeeded, or non-zero
otherwise.
See EXIT STATUS section.
OPTIONS
-h server or --host server
Specifies the hostname for the DICT server. Server/port
combinations can be specified in the configuration file. If no
servers are specified in the configuration file or or on the
command line, dict will fail. (This is a compile-time option,
./configure --enable-dictorg, which is disabled by default.) If
IP lookup for a server expands to a list of IP addresses (as
dict.org does currently), then each IP will be tried in the
order listed.
-p service or --port service
Specifies the port (e.g., 2628) or service (e.g., dict) for
connections. The default is 2628, as specified in the DICT
Protocol RFC. Server/port combinations can be specified in the
configuration file.
-d dbname or --database dbname
Specifies a specific database to search. The default is to
search all databases (a "*" from the DICT protocol). Note that
a "!" in the DICT protocol means to search all of the databases
until a match is found, and then stop searching.
-m or --match
Instead of printing a definition, perform a match using the
specified strategy.
-s strategy or --strategy strategy
Specify a matching strategy. By default, the server default
match strategy is used. This is usually "exact" for
definitions, and some form of spelling-correction strategy for
matches ("." from the DICT protocol). The available strategies
are dependent on the server implementation. For a list of
available strategies, see the -S or --strats option.
-C or --nocorrect
Usually, if a definition is requested and the word cannot be
found, spelling correction is requested from the server, and a
list of possible words are provided. This option disables the
generation of this list.
-c file or --config file
Specify the configuration file. The default is to try ~/.dictrc
and /usr/local/etc/dict.conf, using the first file that exists.
If a specific configuration file is specified, then the defaults
will not be tried.
-D or --dbs
Query the server and display a list of available databases.
-S or --strats
Query the server and display a list of available search
strategies.
-H or --serverhelp
Query the server and display the help information that it
provides.
-i dbname or --info dbname
Request information on the specified database (usually the
server will provide origination, descriptive, or other
information about the database or its contents).
-I or --serverinfo
Query the server and display information about the server.
-M or --mime
Send OPTION MIME command to the server.
NOTE: Server's capabilities are not checked.
-f or --formatted
Enables formatted output, i.e. output convenient for
postprocessing by standard UNIX utilities. No, it is not XML ;-)
Also error and warning messages like
" No matches...", " Invalid strategy..." etc. are sent to
stderr, not to stdout.
Format:
-I, -i, -H and similar:
host<TAB>port
<SPC><SPC>line1
<SPC><SPC>line2
...
-S:
host<TAB>port<TAB>strategy1<TAB>short description1
host<TAB>port<TAB>strategy2<TAB>short description2
...
-D:
host<TAB>port<TAB>database1<TAB>database description1
host<TAB>port<TAB>database2<TAB>database description2
...
-m:
host<TAB>port<TAB>database1<TAB>match1
host<TAB>port<TAB>database2<TAB>match2
...
-a or --noauth
Disable authentication (i.e., don't send an AUTH command).
-u user or --user user
Specifies the username for authentication.
-k key or --key key
Specifies the shared secret for authentication.
-V or --version
Display version information.
-L or --license
Display copyright and license information.
--help Display help information.
-v or --verbose
Be verbose.
-r or --raw
Be very verbose: show the raw client/server interaction.
--pipesize
Specify the buffer size for pipelineing commands. The default
is 256, which should be sufficient for general tasks and be
below the MTU for most transport media. Larger values may
provide faster or slower throughput, depending on MTU. If the
buffer is too small, requests will be serialized. Values less
than 0 and greater than one million are silently changed to
something more reasonable.
--client text
Specifies additional text to be sent using the CLIENT command.
--debug flag
Set a debugging flag. Valid flags are:
verbose
The same as -v or --verbose.
raw The same as -r or --raw.
scan Debug the scanner for the configuration file.
parse Debug the parser for the configuration file.
pipe Debug TCP pipelining support (see the DICT RFC and
RFC1854).
serial Disable pipelining support.
time Perform transaction timing.
CONFIGURATION
The configuration file currently has a very simple format. Lines are
used to specify servers, for example:
server dict.org
or, with options:
server dict.org { port 8080 }
server dict.org { user username secret }
server dict.org { port dict user username secret }
the port and user options may be specified in any order. The port
option is used to specify an optional port (e.g., 2628) or service
(e.g., dict) for the TCP/IP connection. The user option is used to
specify a username and shared secret to be used for authentication to
this particular server.
Servers are tried in the order listed until a connection is made. If
none of the specified servers are available, and the compile-time
option (./configure --enable-dictorg) is enabled, then an attempt will
be made to connect on localhost and on dict.org at the standard part
(2628). (This option is disabled by default.) We expect that dict.org
will point to one or more DICT servers (perhaps in round-robin fashion)
for the foreseeable future (starting in July 1997), although it is
difficult to predict anything on the Internet for more than about 3-6
months.
EXIT STATUS
0 Successful completion
20 No matches found
21 Approximate matches found
22 No databases available
23 No strategies available
30 Unexpected response code from server
31 Server is temporarily unavailable
32 Server is shutting down
33 Syntax error, command not recognized
34 Syntax error, illegal parameters
35 Command not implemented
36 Command parameter not implemented
37 Access denied
38 Authentication failed
39 Invalid database
40 Invalid strategy
41 Connection to server failed
CREDITS
dict was written by Rik Faith (faith@cs.unc.edu) and is distributed
under the terms of the GNU General Public License. If you need to
distribute under other terms, write to the author.
The main libraries used by this programs (zlib, regex, libmaa) are
distributed under different terms, so you may be able to use the
libraries for applications which are incompatible with the GPL --
please see the copyright notices and license information that come with
the libraries for more information, and consult with your attorney to
resolve these issues.
BUGS
If a dict: URL is given on the command line, only the first one is
used. The rest are ignored.
If a dict: URL contains a specifier for the nth definition or match of
a word, it will be ignored and all the definitions or matches will be
provided. This violates the RFC, and will be corrected in a future
release.
If a dict: URL contains a shared secret, it will not be parsed
correctly.
When OPTION MIME command is sent to the server (-M option) , server's
capabilities are not checked.
FILES
~/.dictrc
User's dict configuration file
/usr/local/etc/dict.conf
System dict configuration file
SEE ALSO
dictd(8), dictzip(1), http://www.dict.org, RFC 2229
15 February 1998 DICT(1)
dict(n) Tcl Built-In Commands dict(n)
______________________________________________________________________________
NAME
dict - Manipulate dictionaries
SYNOPSIS
dict option arg ?arg ...?
______________________________________________________________________________
DESCRIPTION
Performs one of several operations on dictionary values or variables
containing dictionary values (see the DICTIONARY VALUES section below
for a description), depending on option. The legal options (which may
be abbreviated) are:
dict append dictionaryVariable key ?string ...?
This appends the given string (or strings) to the value that the
given key maps to in the dictionary value contained in the given
variable, writing the resulting dictionary value back to that
variable. Non-existent keys are treated as if they map to an
empty string. The updated dictionary value is returned.
dict create ?key value ...?
Return a new dictionary that contains each of the key/value
mappings listed as arguments (keys and values alternating, with
each key being followed by its associated value.)
dict exists dictionaryValue key ?key ...?
This returns a boolean value indicating whether the given key
(or path of keys through a set of nested dictionaries) exists in
the given dictionary value. This returns a true value exactly
when dict get on that path will succeed.
dict filter dictionaryValue filterType arg ?arg ...?
This takes a dictionary value and returns a new dictionary that
contains just those key/value pairs that match the specified
filter type (which may be abbreviated.) Supported filter types
are:
dict filter dictionaryValue key ?globPattern ...?
The key rule only matches those key/value pairs whose |
keys match any of the given patterns (in the style of |
string match.)
dict filter dictionaryValue script {keyVariable valueVariable}
script The script rule tests for matching by assigning the key
to the keyVariable and the value to the valueVariable,
and then evaluating the given script which should result
in a boolean value (with the key/value pair only being
included in the result of the dict filter when a true
value is returned.) Note that the first argument after
the rule selection word is a two-element list. If the
script returns with a condition of TCL_BREAK, no further
key/value pairs are considered for inclusion in the
resulting dictionary, and a condition of TCL_CONTINUE is
equivalent to a false result. The key/value pairs are
tested in the order in which the keys were inserted into
the dictionary.
dict filter dictionaryValue value ?globPattern ...?
The value rule only matches those key/value pairs whose |
values match any of the given patterns (in the style of |
string match.)
dict for {keyVariable valueVariable} dictionaryValue body
This command takes three arguments, the first a two-element list
of variable names (for the key and value respectively of each
mapping in the dictionary), the second the dictionary value to
iterate across, and the third a script to be evaluated for each
mapping with the key and value variables set appropriately (in
the manner of foreach.) The result of the command is an empty
string. If any evaluation of the body generates a TCL_BREAK
result, no further pairs from the dictionary will be iterated
over and the dict for command will terminate successfully
immediately. If any evaluation of the body generates a
TCL_CONTINUE result, this shall be treated exactly like a normal
TCL_OK result. The order of iteration is the order in which the
keys were inserted into the dictionary.
dict get dictionaryValue ?key ...?
Given a dictionary value (first argument) and a key (second
argument), this will retrieve the value for that key. Where
several keys are supplied, the behaviour of the command shall be
as if the result of dict get $dictVal $key was passed as the
first argument to dict get with the remaining arguments as
second (and possibly subsequent) arguments. This facilitates
lookups in nested dictionaries. For example, the following two
commands are equivalent:
dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong
If no keys are provided, dict get will return a list containing
pairs of elements in a manner similar to array get. That is, the
first element of each pair would be the key and the second
element would be the value for that key.
It is an error to attempt to retrieve a value for a key that is
not present in the dictionary.
dict incr dictionaryVariable key ?increment?
This adds the given increment value (an integer that defaults to
1 if not specified) to the value that the given key maps to in
the dictionary value contained in the given variable, writing
the resulting dictionary value back to that variable. Non-
existent keys are treated as if they map to 0. It is an error to
increment a value for an existing key if that value is not an
integer. The updated dictionary value is returned.
dict info dictionaryValue
This returns information (intended for display to people) about
the given dictionary though the format of this data is dependent
on the implementation of the dictionary. For dictionaries that
are implemented by hash tables, it is expected that this will
return the string produced by Tcl_HashStats, similar to array
statistics.
dict keys dictionaryValue ?globPattern?
Return a list of all keys in the given dictionary value. If a
pattern is supplied, only those keys that match it (according to
the rules of string match) will be returned. The returned keys
will be in the order that they were inserted into the
dictionary.
dict lappend dictionaryVariable key ?value ...?
This appends the given items to the list value that the given
key maps to in the dictionary value contained in the given
variable, writing the resulting dictionary value back to that
variable. Non-existent keys are treated as if they map to an
empty list, and it is legal for there to be no items to append
to the list. It is an error for the value that the key maps to
to not be representable as a list. The updated dictionary value
is returned.
dict map {keyVariable valueVariable} dictionaryValue body
This command applies a transformation to each element of a
dictionary, returning a new dictionary. It takes three
arguments: the first is a two-element list of variable names
(for the key and value respectively of each mapping in the
dictionary), the second the dictionary value to iterate across,
and the third a script to be evaluated for each mapping with the
key and value variables set appropriately (in the manner of
lmap). In an iteration where the evaluated script completes
normally (TCL_OK, as opposed to an error, etc.) the result of
the script is put into an accumulator dictionary using the key
that is the current contents of the keyVariable variable at that
point. The result of the dict map command is the accumulator
dictionary after all keys have been iterated over.
If the evaluation of the body for any particular step generates
a break, no further pairs from the dictionary will be iterated
over and the dict map command will terminate successfully
immediately. If the evaluation of the body for a particular step
generates a continue result, the current iteration is aborted
and the accumulator dictionary is not modified. The order of
iteration is the natural order of the dictionary (typically the
order in which the keys were added to the dictionary; the order
is the same as that used in dict for).
dict merge ?dictionaryValue ...?
Return a dictionary that contains the contents of each of the
dictionaryValue arguments. Where two (or more) dictionaries
contain a mapping for the same key, the resulting dictionary
maps that key to the value according to the last dictionary on
the command line containing a mapping for that key.
dict remove dictionaryValue ?key ...?
Return a new dictionary that is a copy of an old one passed in
as first argument except without mappings for each of the keys
listed. It is legal for there to be no keys to remove, and it
also legal for any of the keys to be removed to not be present
in the input dictionary in the first place.
dict replace dictionaryValue ?key value ...?
Return a new dictionary that is a copy of an old one passed in
as first argument except with some values different or some
extra key/value pairs added. It is legal for this command to be
called with no key/value pairs, but illegal for this command to
be called with a key but no value.
dict set dictionaryVariable key ?key ...? value
This operation takes the name of a variable containing a
dictionary value and places an updated dictionary value in that
variable containing a mapping from the given key to the given
value. When multiple keys are present, this operation creates or
updates a chain of nested dictionaries. The updated dictionary
value is returned.
dict size dictionaryValue
Return the number of key/value mappings in the given dictionary
value.
dict unset dictionaryVariable key ?key ...?
This operation (the companion to dict set) takes the name of a
variable containing a dictionary value and places an updated
dictionary value in that variable that does not contain a
mapping for the given key. Where multiple keys are present, this
describes a path through nested dictionaries to the mapping to
remove. At least one key must be specified, but the last key on
the key-path need not exist. All other components on the path
must exist. The updated dictionary value is returned.
dict update dictionaryVariable key varName ?key varName ...? body
Execute the Tcl script in body with the value for each key (as
found by reading the dictionary value in dictionaryVariable)
mapped to the variable varName. There may be multiple
key/varName pairs. If a key does not have a mapping, that
corresponds to an unset varName. When body terminates, any
changes made to the varNames is reflected back to the dictionary
within dictionaryVariable (unless dictionaryVariable itself
becomes unreadable, when all updates are silently discarded),
even if the result of body is an error or some other kind of
exceptional exit. The result of dict update is (unless some kind
of error occurs) the result of the evaluation of body.
Each varName is mapped in the scope enclosing the dict update;
it is recommended that this command only be used in a local
scope (procedure, lambda term for apply, or method). Because of
this, the variables set by dict update will continue to exist
after the command finishes (unless explicitly unset). Note that
the mapping of values to variables does not use traces; changes
to the dictionaryVariable's contents only happen when body
terminates.
dict values dictionaryValue ?globPattern?
Return a list of all values in the given dictionary value. If a
pattern is supplied, only those values that match it (according
to the rules of string match) will be returned. The returned
values will be in the order of that the keys associated with
those values were inserted into the dictionary.
dict with dictionaryVariable ?key ...? body
Execute the Tcl script in body with the value for each key in
dictionaryVariable mapped (in a manner similarly to dict update)
to a variable with the same name. Where one or more keys are
available, these indicate a chain of nested dictionaries, with
the innermost dictionary being the one opened out for the
execution of body. As with dict update, making
dictionaryVariable unreadable will make the updates to the
dictionary be discarded, and this also happens if the contents
of dictionaryVariable are adjusted so that the chain of
dictionaries no longer exists. The result of dict with is
(unless some kind of error occurs) the result of the evaluation
of body.
The variables are mapped in the scope enclosing the dict with;
it is recommended that this command only be used in a local
scope (procedure, lambda term for apply, or method). Because of
this, the variables set by dict with will continue to exist
after the command finishes (unless explicitly unset). Note that
the mapping of values to variables does not use traces; changes
to the dictionaryVariable's contents only happen when body
terminates.
If the dictionaryVariable contains a value that is not a
dictionary at the point when the body terminates (which can
easily happen if the name is the same as any of the keys in
dictionary) then an error occurs at that point. This command is
thus not recommended for use when the keys in the dictionary are
expected to clash with the dictionaryVariable name itself. Where
the contained key does map to a dictionary, the net effect is to
combine that inner dictionary into the outer dictionary; see the
EXAMPLES below for an illustration of this.
DICTIONARY VALUES
Dictionaries are values that contain an efficient, order-preserving
mapping from arbitrary keys to arbitrary values. Each key in the
dictionary maps to a single value. They have a textual format that is
exactly that of any list with an even number of elements, with each
mapping in the dictionary being represented as two items in the list.
When a command takes a dictionary and produces a new dictionary based
on it (either returning it or writing it back into the variable that
the starting dictionary was read from) the new dictionary will have the
same order of keys, modulo any deleted keys and with new keys added on
to the end. When a string is interpreted as a dictionary and it would
otherwise have duplicate keys, only the last value for a particular key
is used; the others are ignored, meaning that, "apple banana" and
"apple carrot apple banana" are equivalent dictionaries (with different
string representations).
Operations that derive a new dictionary from an old one (e.g., updates
like dict set and dict unset) preserve the order of keys in the
dictionary. The exceptions to this are for any new keys they add, which
are appended to the sequence, and any keys that are removed, which are
excised from the order.
EXAMPLES
Basic dictionary usage:
# Make a dictionary to map extensions to descriptions
set filetypes [dict create .txt "Text File" .tcl "Tcl File"]
# Add/update the dictionary
dict set filetypes .tcl "Tcl Script"
dict set filetypes .tm "Tcl Module"
dict set filetypes .gif "GIF Image"
dict set filetypes .png "PNG Image"
# Simple read from the dictionary
set ext ".tcl"
set desc [dict get $filetypes $ext]
puts "$ext is for a $desc"
# Somewhat more complex, with existence test
foreach filename [glob *] {
set ext [file extension $filename]
if {[dict exists $filetypes $ext]} {
puts "$filename is a [dict get $filetypes $ext]"
}
}
Constructing and using nested dictionaries:
# Data for one employee
dict set employeeInfo 12345-A forenames "Joe"
dict set employeeInfo 12345-A surname "Schmoe"
dict set employeeInfo 12345-A street "147 Short Street"
dict set employeeInfo 12345-A city "Springfield"
dict set employeeInfo 12345-A phone "555-1234"
# Data for another employee
dict set employeeInfo 98372-J forenames "Anne"
dict set employeeInfo 98372-J surname "Other"
dict set employeeInfo 98372-J street "32995 Oakdale Way"
dict set employeeInfo 98372-J city "Springfield"
dict set employeeInfo 98372-J phone "555-8765"
# The above data probably ought to come from a database...
# Print out some employee info
set i 0
puts "There are [dict size $employeeInfo] employees"
dict for {id info} $employeeInfo {
puts "Employee #[incr i]: $id"
dict with info {
puts " Name: $forenames $surname"
puts " Address: $street, $city"
puts " Telephone: $phone"
}
}
# Another way to iterate and pick out names...
foreach id [dict keys $employeeInfo] {
puts "Hello, [dict get $employeeInfo $id forenames]!"
}
A localizable version of string toupper:
# Set up the basic C locale
set capital [dict create C [dict create]]
foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
dict set capital C $c [string toupper $c]
}
# English locales can luckily share the "C" locale
dict set capital en [dict get $capital C]
dict set capital en_US [dict get $capital C]
dict set capital en_GB [dict get $capital C]
# ... and so on for other supported languages ...
# Now get the mapping for the current locale and use it.
set upperCaseMap [dict get $capital $env(LANG)]
set upperCase [string map $upperCaseMap $string]
Showing the detail of dict with:
proc sumDictionary {varName} {
upvar 1 $varName vbl
foreach key [dict keys $vbl] {
# Manufacture an entry in the subdictionary
dict set vbl $key total 0
# Add the values and remove the old
dict with vbl $key {
set total [expr {$x + $y + $z}]
unset x y z
}
}
puts "last total was $total, for key $key"
}
set myDict {
a {x 1 y 2 z 3}
b {x 6 y 5 z 4}
}
sumDictionary myDict
# prints: last total was 15, for key b
puts "dictionary is now \"$myDict\""
# prints: dictionary is now "a {total 6} b {total 15}"
When dict with is used with a key that clashes with the name of the
dictionary variable:
set foo {foo {a b} bar 2 baz 3}
dict with foo {}
puts $foo
# prints: a b foo {a b} bar 2 baz 3
SEE ALSO
append(n), array(n), foreach(n), incr(n), list(n), lappend(n), lmap(n),
set(n)
KEYWORDS
dictionary, create, update, lookup, iterate, filter, map
Tcl 8.5 dict(n)