You are looking at historical revision 16167 of this page. It may differ significantly from its current revision.

dict

Description

Pure scheme implementation of a rfc2229 protocol client. This is a rewrite of the dict.egg available for chicken 3.x which was a wrapper around libdict.

Author

David Krentzlin

Requirements

Requires the defstruct extension

Documentation

This extension provides a set of procedures, that can be used to communicate with dict-servers.At the moment of this writing it supports almost all commands of the dict-protocol.authentication and mime-headers are currently not supported, but will be once the needed extensions are available.

Connect/Disconnect

[procedure] (connect server #!key (port (*default-port*)) (client "dict.eg for chicken scheme") (timeout #f)) => CONNECTION

Connects to the dict-server with the specified port or the default-port as specified in rfc22229 (2628). Once the connection is established, the server's banner is parsed and information are extracted. Finally the procedure issues a client-command with the specified client-string as parameter. The value for timout is directly used to set the timeout for tcp-connect. The procedure returns a connection-object on success or signals an error otherwise.

[procedure] (disconnect CONNECTION) => BOOL

Closes the connection represented by CONNECTION and sets its status to disconnected. Returns #t if the connection was closes successfully or false otherwise.

Connection-object

The connection-object has the following accessors.

[procedure] (connection-msg-id CONNECTION) => STRING

The message-id as given by the server

[procedure] (connection-server-capabilities CONNECTION) => LIST

The list of the server's capabilities. For example auth, mime etc.

Logging

Sometimes you might want to see what happens when you use the extension. For those cases there is support for logging input and output.

[parameter] *current-log-port*

Set this to a port and the extension will log all input send and all output retrieved from the server to this port. If you want to disable logging, set it to #f. It defaults to #f, so logging is disabled.

Status-responses

In case of an error the command-procedures return the status-response send by the server. In order to identify a status or present an error-message to the user, there are procedures that deal with status-response-objects

[procedure] (status-response? RESP) => BOOL

Check if a response is a status-response.

[procedure] (response-status-error? STATUS-RESPONSE) => BOOL

Checks if the given status-response represents an error.

[procedure] (response-status-code STATUS-RESPONSE) => FIXNUM

Retrieve the status-code (a positive fixnum) of the STATUS-RESPONSE.

[procedure] (response-status-message STATUS-RESPONSE) => STRING

Retrieve the textual information send by the server for this STATUS-RESPONSE

[procedure] (response-status-code->string FIXNUM) => STRING

Map status-codes to textual-representation as specified in rfc2229

Status-Response-Predicates

For each status-response-type there is a predicate that checks whether a given status-response represents that specific type. See the list of status-predicates at the end of this documentation.

Commands

Generally all commands return two values. The first value is a boolean indicating success or failure of the operation. The second value depends on the operation performed. In the case of a failure all commands return the status-response send by the server as the second value.

[procedure] (!match CONNECTION word #!key (strategy 'default) (db 'first)) => (VALUES BOOL ALIST|STATUS-RESPONSE)

Performs a match-operation on the dict-server for the given word. The strategy to use can be specified by the key-word-argument strategy. It defaults to the symbol 'default which means: "Use the default-strategy". The default-strategy is server-dependent. Legal values for the strategy are:

The db key-word-argument specifies the database to search. Legal values for db are:

This procedure returns an alist mapping databases to matches.

[procedure] (!define CONNECTION word #!key (db 'first)) => (VALUES BOOL LIST|STATUS-RESPONSE)

Performs a define-operation on the dict-server for the given word. The db key-word-argument specifies the database to use: Legal values for db are:

This procedure returns a list of lists where each sublist consists of the following elements: (WORD DB DB-DESCRPTION DEFINITION)

[procedure] (!databases CONNECTION) => (VALUES BOOL LIST|STATUS-RESPONSE)

Get a list of available databases.

[procedure] (!strategies CONNECTION) => (VALUES BOOL LIST|STATUS-RESPONSE)

Get a list of available search-strategies

[procedure] (!server-information CONNECTION) => (VALUES BOOL STRING|STATUS-RESPONSE)

Retrieve information about the server.

[procedure] (!database-information CONNECTION db) => (VALUES STRING LIST|STATUS-RESPONSE)

Retrieve information about the database specified by db.

[procedure] (!help CONNECTION) => (VALUES BOOL STRING|STATUS-RESPONSE)

Retrieve the help-text.

[procedure] (!status CONNECTION) => (VALUES BOOL STRING|STATUS-RESPONSE)

Retrieve general status-information e.g. timing-values.

[procedure] (!quit CONNECTION) => (VALUES BOOL STATUS-RESPONSE)

Ask the server to close the connection. Please don't use this directly, but (disconnect) instead.

[procedure] (!announce-client CONNECTION client) => (VALUES BOOL STATUS-RESPONSE)

Notify the server about the client that is talking to it. This happens automatically during (connect)

Examples

Examples:

(use dict)

(*current-log-port* (current-output-port))

(define con (connect "dict.org"))

(receive (success matches) (!match con "scheme" db: 'all)
  (if success
      (printf "Found matches: ~A~%" matches)))

(receive (success def) (!define con "Scheme-to-C" db: "foldoc")
  (if (and success (not (null? def)))
      (printf "Defintion for Scheme-to-C: ~A~%" (definition-text (car def)))))

(receive (success strats) (!strategies con)
  (if success
      (printf "Strategies: ~A~%" strats)))

(disconnect con)

List of status-predicates