Changeset 14357 in project


Ignore:
Timestamp:
04/22/09 22:17:43 (11 years ago)
Author:
certainty
Message:

Changes applied for certainty (82.82.227.229) through svnwiki:

add procedure documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/dict

    r14356 r14357  
    44
    55=== Description
    6 Pure scheme implementation of a rfc2229 protocol client.
    7 This is a rewrite of the dict.egg available for chicken 3.x which was a wrapper around libdict.
     6Pure scheme implementation of a rfc2229 protocol client. This is a rewrite of the dict.egg
     7available for chicken 3.x which was a wrapper around libdict.
    88
    99=== Author
     
    2020=== Documentation
    2121
    22 This extension provides a set of procedures, that can be used to communicate with dict-servers.
    23 At the moment of this writing it supports almost all commands of the dict-protocol.
    24 authentication and mime-headers are currently not supported, but will be once the needed
    25 extensions are available.
     22This extension provides a set of procedures, that can be used to communicate with
     23dict-servers.At the moment of this writing it supports almost all commands of the
     24dict-protocol.authentication and mime-headers are currently not supported, but will
     25be once the needed extensions are available.
     26
    2627
    2728=== Connect/Disconnect
    2829
    29 * <procedure>(connect server #!key (port (*default-port*)) (client "dict.eg for chicken scheme") (timeout #f)) => CONNECTION</procedure>
    30 
    31 Connects to the dict-server with the specified port or the default-port as specified in rfc22229 (2628). Once the connection
    32 is established, the server's banner is parsed and information are extracted. Finally the procedure issues a client-command
    33 with the specified client-string as parameter.
    34 The value for timout is directly used to set the timeout for tcp-connect.
    35 The procedure returns a connection-object on success and signals an error otherwise.
    36 
    37 * <procedure>(disconnect CONNECTION) => BOOL</procedure>
     30<procedure>(connect server #!key (port (*default-port*)) (client "dict.eg for chicken scheme") (timeout #f)) => CONNECTION</procedure>
     31
     32Connects to the dict-server with the specified port or the default-port as specified
     33in rfc22229 (2628). Once the connection is established, the server's banner is parsed
     34and information are extracted. Finally the procedure issues a client-command with the
     35specified client-string as parameter. The value for timout is directly used to set the
     36timeout for tcp-connect. The procedure returns a connection-object on success or
     37signals an error otherwise.
     38
     39<procedure>(disconnect CONNECTION) => BOOL</procedure>
    3840
    3941Closes the connection represented by CONNECTION and sets its status status do disconnected.
    4042Returns #t if the connection was closes successfully and false otherwise.
    4143
     44=== Connection-object
     45
     46The connection-object has the following accessors.
     47
     48<procedure>(connection-msg-id CONNECTION) => STRING </procedure>
     49
     50The message-id as given by the server
     51
     52<procedure>(connection-server-capabilities CONNECTION) => LIST </procedure>
     53
     54The list of the server's capabilities. For example auth, mime etc.
     55
     56
     57=== Logging
     58
     59Sometimes you might want to see what happens when you use the extension.
     60For those cases there is support for logging input and output.
     61
     62<parameter> *current-log-port* </parameter>
     63
     64Set this to a port and the extension will log all input send and all output
     65retrieved from the server to this port. If you want to disable logging,
     66set it to #f. It defaults to #f, so logging is disabled.
     67
    4268=== Status-responses
    4369
    44 In case of an error the command-procedures return the status-response send by the server.
    45 In order to identify a status or present an error-message to the user, there are procedures
    46 that deal with status-response-objects
    47 
    48 * <procedure>(status-response? RESP) => BOOL </procedure>
     70In case of an error the command-procedures return the status-response send
     71by the server. In order to identify a status or present an error-message to
     72the user, there are procedures that deal with status-response-objects
     73
     74<procedure>(status-response? RESP) => BOOL </procedure>
    4975
    5076Check if a response is a status-response.
    5177
    52 * <procedure>(response-status-error? STATUS-RESPONSE) => BOOL </procedure>
     78<procedure>(response-status-error? STATUS-RESPONSE) => BOOL </procedure>
    5379
    5480Checks if the given status-response represents an error.
    5581
    56 * <procedure>(response-status-code STATUS-RESPONSE) => FIXNUM</procedure>
     82<procedure>(response-status-code STATUS-RESPONSE) => FIXNUM</procedure>
    5783
    5884Retrieve the status-code (a positive fixnum) of the STATUS-RESPONSE.
    5985
    60 * <procedure>(response-status-message STATUS-RESPONSE) => STRING</procedure>
     86<procedure>(response-status-message STATUS-RESPONSE) => STRING</procedure>
    6187
    6288Retrieve the textual information send by the server for this STATUS-RESPONSE
    6389
    64 * <procedure>(response-status-code->string FIXNUM) => STRING</procedure>
     90<procedure>(response-status-code->string FIXNUM) => STRING</procedure>
    6591
    6692Map status-codes to textual-representation as specified in rfc2229
     
    6995
    7096For each status-response-type there is a predicate that checks whether a given
    71 status-response represents that specific type. See the list of status-predicates at the end of this documentation.
     97status-response represents that specific type. See the list of status-predicates
     98at the end of this documentation.
    7299
    73100
    74101=== Commands
    75102
    76 
    77 === Example
     103Generally all commands return two values. The first value is a boolean indicating
     104success or failure of the operation. The second value depends on the operation
     105performed. In the case of a failure all commands return the status-response send by
     106the server as the second value.
     107
     108
     109<procedure>(!match CONNECTION word #!key (strategy 'default) (db 'first)) => (VALUES BOOL ALIST|STATUS-RESPONSE) </procedure>
     110
     111Performs a match-operation on the dict-server for the given word.
     112The strategy to use can be specified by the key-word-argument strategy. It defaults to the symbol 'default
     113which means: "Use the default-strategy". The default-strategy is server-dependent.
     114Legal values for the strategy are:
     115* a string => the name of a strategy (see !strategies)
     116* the symbol 'default => this means use the default strategy
     117
     118The db key-word-argument specifies the database to search.
     119Legal values for db are:
     120* a string => the name of a database (see !databases)
     121* the symbol 'first => this means search all databases and stop after the first match
     122* the symbol 'all => this means search all databases and return all matches
     123
     124This procedure returns an alist mapping databases to matches.
     125
     126
     127<procedure>(!define CONNECTION word #!key (db 'first)) => (VALUES BOOL LIST|STATUS-RESPONSE)</procedure>
     128
     129Performs a define-operation on the dict-server for the given word.
     130The db key-word-argument specifies the database to use:
     131Legal values for db are:
     132* a string => the name of a database (see !databases)
     133* the symbol 'first => this means search all databases and stop after the first match
     134* the symbol 'all => this means search all databases and return all matches
     135
     136This procedure returns a list of lists where each sublist consists of the following elements:
     137(WORD DB DB-DESCRPTION DEFINITION)
     138
     139<procedure>(!databases CONNECTION) => (VALUES BOOL LIST|STATUS-RESPONSE)</procedure>
     140
     141Get a list of available databases.
     142
     143<procedure>(!strategies CONNECTION) => (VALUES BOOL LIST|STATUS-RESPONSE)</procedure>
     144
     145Get a list of available search-strategies
     146
     147<procedure>(!server-information CONNECTION) => (VALUES BOOL STRING|STATUS-RESPONSE)</procedure>
     148
     149Retrieve information about the server.
     150
     151<procedure>(!database-information CONNECTION db) => (VALUES STRING LIST|STATUS-RESPONSE)</procedure>
     152
     153Retrieve information about the database specified by db.
     154
     155<procedure>(!help CONNECTION) => (VALUES BOOL STRING|STATUS-RESPONSE)</procedure>
     156
     157Retrieve the help-text.
     158
     159<procedure>(!status CONNECTION) => (VALUES BOOL STRING|STATUS-RESPONSE)</procedure>
     160
     161Retrieve general status-information e.g. timing-values.
     162
     163<procedure>(!quit CONNECTION) => (VALUES BOOL STATUS-RESPONSE)</procedure>
     164
     165Ask the server to close the connection. Please don't use this directly,
     166but (disconnect) instead.
     167
     168<procedure>(!announce-client CONNECTION client) => (VALUES BOOL STATUS-RESPONSE)</procedure>
     169
     170Notify the server about the client that is talking to it. This happens automatically during
     171(connect)
     172
     173
     174=== Examples
    78175
    79176=== List of status-predicates
Note: See TracChangeset for help on using the changeset viewer.