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

This is version 1.0.5 of the dict extension library for Chicken Scheme.

Description

dict protocoll-client API

Documentation

This extension provides a wrapper around libdict. A dict-protocoll-client API.

Make sure you have libdict installed and the header and libfiles are in place. This extension provides two logical layers. The first is the low-level-api wrapping libdict. The second is a higher-level api that provides the most common procedures. See the egg-sources for the low-level-api; all procedures in the low-level-part are prefixed by dict:low.

NOTE: all procedures except (dict:close) yield an error if invalid or closed connections are supplied!

Connecting to a dict-server - high-level -

'''procedure:''' (dict:connect server [port timeout client user password debug])

Connects to a server and returns a connection-object.

server ... is the canonical name of the server. e.g. dict.org

port ... is the port the server listens on. This defaults to DICT:DEFPORT

timeout ... is the timeout in seconds. This defaults to 10

client ... is a string describing the client. This defaults to the empty string

user ... if the server requires authentication this is set as the username

password ... if the server requires authentication this is set as the password

debug ... this is used to toggle debugging. This defaults to #f

This procedure returns a connection-object if it was successful and #f otherwise

Disconnecting from a dict-server - high-level -

'''procedure:''' (dict:close connection)

Disconnects the from the server represented by `connection` and releases all internal resources

connection ... is the connection-handle obtained by a call to (dict:connect)

It is not an error if an allready closed connection is closed again. The procedure returns #t if the connection has been open and was successfully closed, #f otherwise.

Authenticating to a dict-server - high-level -

'''procedure:''' (dict:authenticate connection user password)

Performs authentication on the server specified by `connection` with `user` and `password`

The procedure returns #t if the login was successful and #f otherwise.

Using connection to a dict-server - high-level -

'''procedure:''' (dict:call-with-server procedure server . connect-options)

Connects to the server as specified by `server` and invokes the one-argument procedure `procedure` where the opened connection is passed as the parameter.

If the connection can be established the procedure closes the connection once `procedure` has finished and returns what `procedure`returned, otherwise `procedure` is not invoked and #f is returned

List available dictionaries on a dict-server - high-level -

'''procedure:''' (dict:dictionary-list connection)

Retrieves a list of dictionaries that are present on the server represented by `connection`

This procedure returns a list of pairs. The car of each pair holds the dictionary-name as to be used for (dict:dictionary-set!) and the cdr holds a description string.

List available search-strategies on a dict-server - high-level -

'''procedure:''' (dict:strategy-list connection)

Retrieves a list of available search-strategies on the server represented by `connection`.

This procedure returns a list of pairs. The car of each pair hold the strategy-name as to be used by (dict:strategy-set!) and the cdr holds a description string.

Selecting a dictionary to use on a dict-server - high-level -

'''procedure:''' (dict:dictionary-set! connection dictionary-name)

Selects a the dictionary identfied by `dictionary-name`. This causes all following operations to operate on this dictionary.

This procedure returns #t if the dictionary was successfully selected and #f otherwise.

Selecting a search-strategy to use on a dict-server - high-level -

'''procedure:''' (dict:strategy-set! connection strategy-name)

Selects a the search-strategy identfied by `strategy-name`. This causes all following operations to operate with this strategy.

This procedure returns #t if the strategy was successfully selected and #f otherwise.

Search for a word on a dict-server - high-level -

'''procedure:''' (dict:match connection word)

Performs the search on the dict-server. If no dictionary has been chosen via (dict:dictionary-set!) then all available dictionaries are searched, otherwise only the selected dictionary is searched.

This procedure returns a list of pairs. Each pair represents a match. The car of the pair is the word that matched (usefull for eg. soundex-search) and the cdr of the pair is the dictionary it was fount in.

Search for a word on a dict-server - raw:high-level -

'''procedure:''' (dict:match-raw connection word)

Performs the search on the dict-server. If no dictionary has been chosen via (dict:dictionary-set!) then all available dictionaries are searched, otherwise only the selected dictionary is searched.

This procedure returns a list of answer-objects. Those objects can then be queried via low-level-procedures like (dict:low:manswer-dict).

Search for a definition on a dict-server - high-level -

'''procedure:''' (dict:define connection word)

Performs the search on the dict-server. If no dictionary has been chosen via (dict:dictionary-set!) then all available dictionaries are searched, otherwise only the selected dictionary is searched.

This procedure returns a list of tripels. Each tripel represents a match. The car of the tripel is the word that matched (usefull for eg. soundex-search) and the cadr of the tripel is the dictionary it was fount in and the caddr of the tripel is the defintion for the word in question

Search for a definition on a dict-server - raw:high-level -

'''procedure:''' (dict:define-raw connection word)

Performs the search on the dict-server. If no dictionary has been chosen via (dict:dictionary-set!) then all available dictionaries are searched, otherwise only the selected dictionary is searched.

This procedure returns a list of answer-objects. Those objects can then be queried via low-level-procedures like (dict:low:defanswer-dict).

Query server-information - high-level -

'''procedure:''' (dict:server-information connection)

Returns a string holding the description of the server.

Query errors - high-level -

'''procedure:''' (dict:query-errors connection)

Get information about the most recent error.

The procedure returns a pair where the car holds a fixnum representing the error-number as in errno.h and the cdr holds a string describing the error.

Examples

(use dict)

;; connect to the dict.org server
(define srv (dict:connect "dict.org"))

;; select a database
;; for a list of available database use (dict:dictionary-list)
(dict:dictionary-set! srv "gcide")

;; set a search-strategy
;; for a list of available strategies use (dict:strategy-list)
(dict:strategy-set! srv "word")

;; search for a matching entry
;; returns a list of pairs wher the cdr holds the match and
;; the cdr hold the dictionary it was fount in (this is gcide of course for this example)
(define result (dict:match srv "hello"))

;; search for a definition
(define def-result (dict:define srv "scheme"))

;; finally close the connection
;; if this is not done explicitely the connection
;; will be closed when the internal pointer gets gc'ed
(dict:close srv)

;;================= USING dict:call-with-server ================================

(dict:call-with-server (lambda (con)
                          (display (dict:define con "scheme")))
                       "dict.org")

About this egg

Author

David Krentzlin

Version history

1.0.5
More unit-tests added. Minor change so double-closing on connections is ok.
1.0.4
fixed typo in dict:low:command
1.0.3
added checks to all low-level-procedures to accept only valid connections
1.0.2
renamed database-list,select-strategy,select-database to be more consistent. Minor bugfixes.
1.0.1
Removed cons* use (part of SRFI-1), added fixnum declare.
1.0
Initial release

Requirements

[[ftp://ftp.dict.org/pub/dict/libdict-0.9.tar.gz|libdict <ftp://ftp.dict.org/pub/dict/libdict-0.9.tar.gz>]]