chickadee » dict

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

dict

Introduction

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.

Repository

dict is hosted at: https://bitbucket.org/certainty/dict

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)

Authors

David Krentzlin

License

 Copyright (c) 2009 David Krentzlin <david@lisp-unleashed.de>

  Permission is hereby granted, free of charge, to any person
  obtaining a copy of this software and associated documentation
  files (the "Software"), to deal in the Software without
  restriction, including without limitation the rights to use,
  copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the
  Software is furnished to do so, subject to the following
  conditions:

  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  OTHER DEALINGS IN THE SOFTWARE.

Requirements

Requires the defstruct,md5 and utf8 extensions.

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. Mime-headers are currently not supported.

Connect/Disconnect

(connect server #!key (port (*default-port*)) (client "dict.egg for chicken scheme") (timeout #f)) => CONNECTIONprocedure

Connects to the dict-server with the specified port or the default-port as specified in rfc2229 (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 timeout is directly used to set the timeout for tcp-connect. The procedure returns a connection-object on success or signals an error otherwise.

disconnect CONNECTIONprocedure

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

Connection-object

The connection-object has the following accessors.

connection-msg-id CONNECTIONprocedure

The message-id as given by the server

connection-server-capabilities CONNECTIONprocedure

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.

*current-log-port*parameter

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

status-response? RESPprocedure

Check if a response is a status-response.

response-status-error? STATUS-RESPONSEprocedure

Checks if the given status-response represents an error.

response-status-code STATUS-RESPONSEprocedure

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

response-status-message STATUS-RESPONSEprocedure

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

response-status-code->string FIXNUMprocedure

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.

!match CONNECTION word #!key (strategy 'default) (db 'first)procedure

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:

  • a string => the name of a strategy (see !strategies)
  • the symbol 'default => this means use the default strategy

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

  • a string => the name of a database (see !databases)
  • the symbol 'first => this means search all databases and stop after the first match
  • the symbol 'all => this means search all databases and return all matches

This procedure returns an alist mapping databases to matches.

!define CONNECTION word #!key (db 'first)procedure

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:

  • a string => the name of a database (see !databases)
  • the symbol 'first => this means search all databases and stop after the first match
  • the symbol 'all => this means search all databases and return all matches

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

!databases CONNECTIONprocedure

Get a list of available databases.

!strategies CONNECTIONprocedure

Get a list of available search-strategies

!server-information CONNECTIONprocedure

Retrieve information about the server.

!database-information CONNECTION dbprocedure

Retrieve information about the database specified by db.

!help CONNECTIONprocedure

Retrieve the help-text.

!status CONNECTIONprocedure

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

!quit CONNECTIONprocedure

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

!announce-client CONNECTION clientprocedure

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





!authenticate CONNECTION username passwordprocedure


Attempts to authenticate the given user at the dict-server. This is sometimes needed to access dictionaries that are otherwise not readable.
List of status-predicates


Versionhistory




Contents »