Changeset 11653 in project


Ignore:
Timestamp:
08/16/08 22:52:09 (13 years ago)
Author:
certainty
Message:

fixed unit-tests. added more documentation

Location:
release/3/dict/trunk
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • release/3/dict/trunk/dict.doc.scm

    r11546 r11653  
    100100)))
    101101
     102
     103(define define-example `( (pre #<<EOF
     104
     105(use dict)
     106
     107(define srv (dict:connect "dict.org"))
     108
     109(display (dict:define srv "gcide" "scheme"))
     110(newline)
     111
     112(display (dict:define! srv "scheme"))
     113(newline)
     114
     115(display (dict:define* srv "scheme"))
     116(newline)
     117
     118(dict:close srv)
     119
     120EOF
     121)))
     122
     123
     124(define standard-dict-server-errors '((li (strong (em "dict:status:syntax-error-command")) " The command is illformed ")
     125                                      (li (strong (em "dict:status:syntax-error-parameter")) " A supplied parameter is invalid for the given command")
     126                                      (li (strong (em "dict:status:command-not-implemented")) " The given command is not implemented by the server")
     127                                      (li (strong (em "dict:status:parameter-not-implemented")) " The given command doesn't support the supplied parameter")))
     128
     129
     130(define (param name description)
     131  `(p (strong (em ,name)) " ... " ,description))
     132
     133(define (params . prms)
     134  `(p (strong "Parameters:")
     135     (ul
     136      ,@(map (lambda (p) `(li ,(param (car p) (cadr p)))) prms))))
     137
     138(define (returns . what)
     139  (cond
     140   ((null? what)
     141    `(p (strong "Returns: nothing")))
     142   ((= (length what) 1)
     143    `(p (strong "Returns:")
     144        (ul
     145         (li (strong ,(caar what)) "  -  " (em ,(cadar what))))))
     146   (else
     147    `(p (strong "Returns (values):")
     148        (ul
     149         ,@(map (lambda (w) `(li (strong ,(car w)) " " (em ,(cadr w)))) what))))))
     150   
     151(define (error-codes .  pairs)
     152  `(p (b "dict:server-error codes")
     153      (ul
     154       ,@standard-dict-server-errors
     155       ,@(map (lambda (val) `(li (strong (em ,(car val))) " " ,(cadr val))) pairs))))
    102156
    103157(define doc
     
    121175     (p "This extension provides procedures to build dict-protocol-clients as described in rfc2229.
    122176         It is intended to be used as a library for applications that need to query dict-servers.")
     177
     178     (subsection "Accessing Status-Codes and Condtions"
     179      (group
     180       (p "Allmost every procedure may signal a condition, which can be used to display
     181           Messages to the user. Every condition that is a translation of dict error-codes can be accessed in a convenient manner")
     182       (procedure "(dict:error? obj)"
     183         (p (em "Test if a condition is a dict:error-condtion"))
     184         ,(returns '("boolean" "#t if obj is a dict:error-condition and #f otherwise"))
     185         ,(params '("obj" "the condition-object")))
     186
     187       (procedure "(dict:error-msg obj)"
     188         (p (em "Extract the message from the condition-object"))
     189         ,(returns '("string" "The message-string."))
     190         ,(params '("obj" "the condition-object")))
     191
     192       (procedure "(dict:server-error? obj)"
     193         (p (em "Test if a conditions is a server-error"))
     194         ,(returns '("boolean" "#t if obj is a dict:server-error"))
     195         ,(params '("obj" "the condition-object")))
     196
     197       (procedure "(dict:server-error-code obj)"
     198         (p (en "Access the numeric error-code as described in the RFC"))
     199         ,(returns '("fixnum" "The error-code. See section constants for a list of available symbolic names"))
     200         ,(params '("obj" "the condition-object")))
     201
     202       (procedure "(dict:server-error-msg obj)"
     203         (p (en "Access the textual information of the error"))
     204         ,(returns '("string" "The text that may be associated with the error"))
     205         ,(params '("obj" "the condition-object")))))
     206                   
     207         
    123208     
    124      (subsection "Connecting to the dict-server"
     209     (subsection "General Operations"
    125210       (group           
    126211        (procedure "(dict:connect server #!key port timeout client)"
    127           (p "Connects to a server and returns a connection-object.")
     212          (p (em "Connect to a dict-server"))
     213          ,(returns '("<dict:connection>" "A connection object"))
     214          ,(params '("server" "the canonical name of the server. e.g. dict.org ")
     215                   '("port" "the port the server listens on. This defaults to dict:default-port")
     216                   '("timeout" "is the timeout in milliseconds. This defaults to #f which means NO timeout")
     217                   '("client" "is a string describing the client. This defaults to 'dict.egg for chicken scheme'"))
     218          ,(error-codes '("dict:status:access-denied" "connections are denied for some reason")
     219                        '("dict:status:server-temporarily-unavailable" "the server is currently not available. Probably because of maintenance or too high load")
     220                        '("dict:status:shutdown-at-op-request" "The server is shutdown, due to human intervention by an operator")))
     221        (procedure "(dict:close connection)"
     222          (p (em "Disconnects from the server gracefully"))
     223          ,(returns '("boolean" "If the connection was shut down successfully it returns #t and #f otherwise"))
     224          ,(params '("connection" "the connection-object"))
     225          ,(error-codes))
     226        (examples ,connect-example)))
     227
     228     (subsection "Match a word in a given database"             
     229       (group
     230        (procedure "(dict:match server database strategy word)"
     231          (p (em "Try to mact the word in the specified database using the specified strategy"))
     232          ,(returns '("List" "A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to"))
     233          ,(params '("connection" "the connection object")
     234                  '("database"  "a database-name as retrieved by e.g. dict:databases")
     235                  '("strategy" "a strategy-name as retrieved by e.g. dict:strategies")
     236                  '("word" "the word to match"))
     237          ,(error-codes '("dict:status:invalid-database" "Specified Database is not known by the Server")
     238                        '("dict:status:invalid-strategy" "Specified Strategy is not known by the Server")))
     239       
     240        (procedure "(dict:match* server strategy word)"
     241          (p (em "Try to match the word using the specified strategy in all available databases"))
     242           ,(returns '("List" "A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to"))
     243            ,(params '("connection" "The connection-object")
     244                    '("strategy" "a strategy-name as retrieved by e.g. dict:strategies")
     245                    '("word" "The word to match"))
     246           ,(error-codes '("dict:satus:invalid-strategy" "Specified Strategy is not know by the server")))
     247       
     248        (procedure "(dict:match! server strategy word)"
     249          (p (em "Try to match the word using the specified strategy in all available databases. Stop after the first match"))
     250          ,(returns '("List" "A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to"))
     251          ,(params '("connection" "the connection-object")
     252                   '("strategy" "a strategy-name as retrieved by e.g. dict:strategies")
     253                   '("word" "the word to match"))
     254          ,(error-codes '("dict:satus:invalid-strategy" "Specified Strategy is not know by the server")))
     255       
     256        (procedure "(dict:match/default server database word)"
     257          (p (em "Try to match the word using the server's default-strategy in the given database")
     258          ,(returns '("List" "A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to"))
     259          ,(params '("connection" "the connection object")
     260                   '("database"  "a database-name as retrieved by e.g. dict:databases")
     261                   '("word" "The word to match"))
     262          ,(error-codes '("dict:status:invalid-database" "Specified Database is not known by the Server"))))
     263             
     264       
     265        (procedure "(dict:match*/default server word"
     266          (p (em "Try to match the word using the server's default-strategy in all databases")
     267           ,(returns '("List" "A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to"))
     268           ,(params '("connection" "the connection object")
     269                    '("word" "The word to match"))
     270          ,(error-codes)))
    128271         
    129           (p "server ... is the canonical name of the server. e.g. dict.org ")
    130 
    131           (p "port ... is the port the server listens on. This defaults to dict:default-port")
    132          
    133           (p "timeout ... is the timeout in milliseconds. This defaults to #f which means NO timeout")
    134          
    135           (p "client ... is a string describing the client. This defaults to 'dict.egg for chicken scheme'")
    136 
    137           (p (b "conditions:")
    138              (ul
    139               (li (b (em "dict:error"))  " Signaled if a timeout accures or unparsable data is returned from the server")
    140               (li (b (em "dict:server-error"))   " Signaled when certain status-response where sent from the server")))
    141           (examples ,connect-example))))
    142 
    143      (subsection "Match a word in a given database"
     272        (procedure "(dict:match!/default server word"
     273          (p (em "Try to match the word using the server's default-strategy in all databases. Stop after the first match")
     274          ,(returns '("List" "A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to"))   
     275          ,(params '("connection" "the connection object")
     276                   '("word" "The word to match"))
     277          ,(error-codes))))
     278       (examples ,match-example))
     279     
     280     (subsection "Find definitions for a word"
    144281       (group
    145         (procedure "(dict:match server database strategy word)")
    146         (procedure "(dict:match* server strategy word)")
    147         (procedure "(dict:match! server strategy word)")
    148         (procedure "(dict:match/default server database word)")
    149         (procedure "(dict:match*/default server word")
    150         (procedure "(dict:match!/default server word"))
    151        (examples ,match-example))))))         
     282        (procedure "(dict:define server database word)"
     283          (p (em "Try to retrieve a defition of word in the given database"))
     284          ,(returns '("List" "A list of defintions. Each sublist has length 3. The car holds the databasename where the defintion comes from. The cadr holds the a description of the database. The caddr holds the textual information"))
     285          ,(params '("connection" "the connection-object")
     286                   '("database" "the database as retrieved by e.g. dict:databases")
     287                   '("word" "The word to define"))
     288          ,(error-codes  '("dict:status:invalid-database" "Specified Database is not known by the Server")))
     289                   
     290        (procedure "(dict:define! server word)"
     291          (p (em "Try to retrieve a defintion of word out of all databases. Stop after one defintion was found."))
     292          ,(returns '("List" "A list of defintions. Each sublist has length 3. The car holds the databasename where the defintion comes from. The cadr holds the a description of the database. The caddr holds the textual information"))
     293          ,(params '("connection" "the connection-object")
     294                   '("word" "The word to define"))
     295          ,(error-codes))
     296             
     297        (procedure "(dict:define* server word)"
     298          (p (em "Try to retrieve a defintion of word out of all databases."))
     299          ,(returns '("List" "A list of defintions. Each sublist has length 3. The car holds the databasename where the defintion comes from. The cadr holds the a description of the database. The caddr holds the textual information"))
     300          ,(params '("connection" "the connection-object")
     301                   '("word" "The word to define"))
     302          ,(error-codes)))
     303       (examples ,define-example))
     304     
     305     (subsection "General dict commands"
     306      (group
     307        (procedure "(dict:databases connection)")
     308        (procedure "(dict:strategies connection)")
     309        (procedure "(dict:help connection)")
     310        (procedure "(dict:status connection)")
     311        (procedure "(dict:server-information connection)")
     312        (procedure "(dict:information connection database)")
     313        (procedure "(dict:authenticate connection username password")))
     314     (subsection "Misc. Helpers"
     315      (group
     316        (procedure "(dict:call-with-command proc connection cmd . args)")
     317        (procedure "(dict:decompose-status-response resp)")
     318        (procedure "(dict:announce-client connection client-string)")))
     319     (examples ,examples)))))
    152320                 
    153321(eggdoc->html doc)
  • release/3/dict/trunk/dict.html

    r11546 r11653  
    180180         It is intended to be used as a library for applications that need to query dict-servers.</p>
    181181<div class="subsection">
    182 <h4>Connecting to the dict-server</h4>
     182<h4>Accessing Status-Codes and Condtions</h4>
     183<dl>
     184<p>Allmost every procedure may signal a condition, which can be used to display
     185           Messages to the user. Every condition that is a translation of dict error-codes can be accessed in a convenient manner</p>
     186<dt class="definition"><strong>procedure:</strong> (dict:error? obj)</dt>
     187<dd>
     188<p><em>Test if a condition is a dict:error-condtion</em></p>
     189<p><strong>Returns:</strong>
     190<ul>
     191<li><strong>boolean</strong>  -  <em>#t if obj is a dict:error-condition and #f otherwise</em></li></ul></p>
     192<p><strong>Parameters:</strong>
     193<ul>
     194<li>
     195<p><strong><em>obj</em></strong> ... the condition-object</p></li></ul></p></dd>
     196<dt class="definition"><strong>procedure:</strong> (dict:error-msg obj)</dt>
     197<dd>
     198<p><em>Extract the message from the condition-object</em></p>
     199<p><strong>Returns:</strong>
     200<ul>
     201<li><strong>string</strong>  -  <em>The message-string.</em></li></ul></p>
     202<p><strong>Parameters:</strong>
     203<ul>
     204<li>
     205<p><strong><em>obj</em></strong> ... the condition-object</p></li></ul></p></dd>
     206<dt class="definition"><strong>procedure:</strong> (dict:server-error? obj)</dt>
     207<dd>
     208<p><em>Test if a conditions is a server-error</em></p>
     209<p><strong>Returns:</strong>
     210<ul>
     211<li><strong>boolean</strong>  -  <em>#t if obj is a dict:server-error</em></li></ul></p>
     212<p><strong>Parameters:</strong>
     213<ul>
     214<li>
     215<p><strong><em>obj</em></strong> ... the condition-object</p></li></ul></p></dd>
     216<dt class="definition"><strong>procedure:</strong> (dict:server-error-code obj)</dt>
     217<dd>
     218<p>
     219<en>Access the numeric error-code as described in the RFC</en></p>
     220<p><strong>Returns:</strong>
     221<ul>
     222<li><strong>fixnum</strong>  -  <em>The error-code. See section constants for a list of available symbolic names</em></li></ul></p>
     223<p><strong>Parameters:</strong>
     224<ul>
     225<li>
     226<p><strong><em>obj</em></strong> ... the condition-object</p></li></ul></p></dd>
     227<dt class="definition"><strong>procedure:</strong> (dict:server-error-msg obj)</dt>
     228<dd>
     229<p>
     230<en>Access the textual information of the error</en></p>
     231<p><strong>Returns:</strong>
     232<ul>
     233<li><strong>string</strong>  -  <em>The text that may be associated with the error</em></li></ul></p>
     234<p><strong>Parameters:</strong>
     235<ul>
     236<li>
     237<p><strong><em>obj</em></strong> ... the condition-object</p></li></ul></p></dd></dl></div>
     238<div class="subsection">
     239<h4>General Operations</h4>
    183240<dl>
    184241<dt class="definition"><strong>procedure:</strong> (dict:connect server #!key port timeout client)</dt>
    185242<dd>
    186 <p>Connects to a server and returns a connection-object.</p>
    187 <p>server ... is the canonical name of the server. e.g. dict.org </p>
    188 <p>port ... is the port the server listens on. This defaults to dict:default-port</p>
    189 <p>timeout ... is the timeout in milliseconds. This defaults to #f which means NO timeout</p>
    190 <p>client ... is a string describing the client. This defaults to 'dict.egg for chicken scheme'</p>
    191 <p><b>conditions:</b>
    192 <ul>
    193 <li><b><em>dict:error</em></b> Signaled if a timeout accures or unparsable data is returned from the server</li>
    194 <li><b><em>dict:server-error</em></b> Signaled when certain status-response where sent from the server</li></ul></p>
     243<p><em>Connect to a dict-server</em></p>
     244<p><strong>Returns:</strong>
     245<ul>
     246<li><strong>&lt;dict:connection&gt;</strong>  -  <em>A connection object</em></li></ul></p>
     247<p><strong>Parameters:</strong>
     248<ul>
     249<li>
     250<p><strong><em>server</em></strong> ... the canonical name of the server. e.g. dict.org </p></li>
     251<li>
     252<p><strong><em>port</em></strong> ... the port the server listens on. This defaults to dict:default-port</p></li>
     253<li>
     254<p><strong><em>timeout</em></strong> ... is the timeout in milliseconds. This defaults to #f which means NO timeout</p></li>
     255<li>
     256<p><strong><em>client</em></strong> ... is a string describing the client. This defaults to 'dict.egg for chicken scheme'</p></li></ul></p>
     257<p><b>dict:server-error codes</b>
     258<ul>
     259<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     260<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     261<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     262<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li>
     263<li><strong><em>dict:status:access-denied</em></strong> connections are denied for some reason</li>
     264<li><strong><em>dict:status:server-temporarily-unavailable</em></strong> the server is currently not available. Probably because of maintenance or too high load</li>
     265<li><strong><em>dict:status:shutdown-at-op-request</em></strong> The server is shutdown, due to human intervention by an operator</li></ul></p></dd>
     266<dt class="definition"><strong>procedure:</strong> (dict:close connection)</dt>
     267<dd>
     268<p><em>Disconnects from the server gracefully</em></p>
     269<p><strong>Returns:</strong>
     270<ul>
     271<li><strong>boolean</strong>  -  <em>If the connection was shut down successfully it returns #t and #f otherwise</em></li></ul></p>
     272<p><strong>Parameters:</strong>
     273<ul>
     274<li>
     275<p><strong><em>connection</em></strong> ... the connection-object</p></li></ul></p>
     276<p><b>dict:server-error codes</b>
     277<ul>
     278<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     279<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     280<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     281<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li></ul></p></dd>
    195282<div class="section">
    196283<h3>Examples</h3>
     
    223310                       (display-exn exn)
    224311                       #f)
    225                      (dict:connect &quot;dict.org&quot;)))              </pre></div></div></dd></dl></div>
     312                     (dict:connect &quot;dict.org&quot;)))              </pre></div></div></dl></div>
    226313<div class="subsection">
    227314<h4>Match a word in a given database</h4>
    228315<dl>
    229316<dt class="definition"><strong>procedure:</strong> (dict:match server database strategy word)</dt>
    230 <dd></dd>
     317<dd>
     318<p><em>Try to mact the word in the specified database using the specified strategy</em></p>
     319<p><strong>Returns:</strong>
     320<ul>
     321<li><strong>List</strong>  -  <em>A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to</em></li></ul></p>
     322<p><strong>Parameters:</strong>
     323<ul>
     324<li>
     325<p><strong><em>connection</em></strong> ... the connection object</p></li>
     326<li>
     327<p><strong><em>database</em></strong> ... a database-name as retrieved by e.g. dict:databases</p></li>
     328<li>
     329<p><strong><em>strategy</em></strong> ... a strategy-name as retrieved by e.g. dict:strategies</p></li>
     330<li>
     331<p><strong><em>word</em></strong> ... the word to match</p></li></ul></p>
     332<p><b>dict:server-error codes</b>
     333<ul>
     334<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     335<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     336<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     337<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li>
     338<li><strong><em>dict:status:invalid-database</em></strong> Specified Database is not known by the Server</li>
     339<li><strong><em>dict:status:invalid-strategy</em></strong> Specified Strategy is not known by the Server</li></ul></p></dd>
    231340<dt class="definition"><strong>procedure:</strong> (dict:match* server strategy word)</dt>
    232 <dd></dd>
     341<dd>
     342<p><em>Try to match the word using the specified strategy in all available databases</em></p>
     343<p><strong>Returns:</strong>
     344<ul>
     345<li><strong>List</strong>  -  <em>A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to</em></li></ul></p>
     346<p><strong>Parameters:</strong>
     347<ul>
     348<li>
     349<p><strong><em>connection</em></strong> ... The connection-object</p></li>
     350<li>
     351<p><strong><em>strategy</em></strong> ... a strategy-name as retrieved by e.g. dict:strategies</p></li>
     352<li>
     353<p><strong><em>word</em></strong> ... The word to match</p></li></ul></p>
     354<p><b>dict:server-error codes</b>
     355<ul>
     356<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     357<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     358<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     359<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li>
     360<li><strong><em>dict:satus:invalid-strategy</em></strong> Specified Strategy is not know by the server</li></ul></p></dd>
    233361<dt class="definition"><strong>procedure:</strong> (dict:match! server strategy word)</dt>
    234 <dd></dd>
     362<dd>
     363<p><em>Try to match the word using the specified strategy in all available databases. Stop after the first match</em></p>
     364<p><strong>Returns:</strong>
     365<ul>
     366<li><strong>List</strong>  -  <em>A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to</em></li></ul></p>
     367<p><strong>Parameters:</strong>
     368<ul>
     369<li>
     370<p><strong><em>connection</em></strong> ... the connection-object</p></li>
     371<li>
     372<p><strong><em>strategy</em></strong> ... a strategy-name as retrieved by e.g. dict:strategies</p></li>
     373<li>
     374<p><strong><em>word</em></strong> ... the word to match</p></li></ul></p>
     375<p><b>dict:server-error codes</b>
     376<ul>
     377<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     378<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     379<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     380<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li>
     381<li><strong><em>dict:satus:invalid-strategy</em></strong> Specified Strategy is not know by the server</li></ul></p></dd>
    235382<dt class="definition"><strong>procedure:</strong> (dict:match/default server database word)</dt>
    236 <dd></dd>
     383<dd>
     384<p><em>Try to match the word using the server's default-strategy in the given database</em>
     385<p><strong>Returns:</strong>
     386<ul>
     387<li><strong>List</strong>  -  <em>A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to</em></li></ul></p>
     388<p><strong>Parameters:</strong>
     389<ul>
     390<li>
     391<p><strong><em>connection</em></strong> ... the connection object</p></li>
     392<li>
     393<p><strong><em>database</em></strong> ... a database-name as retrieved by e.g. dict:databases</p></li>
     394<li>
     395<p><strong><em>word</em></strong> ... The word to match</p></li></ul></p>
     396<p><b>dict:server-error codes</b>
     397<ul>
     398<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     399<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     400<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     401<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li>
     402<li><strong><em>dict:status:invalid-database</em></strong> Specified Database is not known by the Server</li></ul></p></p></dd>
    237403<dt class="definition"><strong>procedure:</strong> (dict:match*/default server word</dt>
    238 <dd></dd>
     404<dd>
     405<p><em>Try to match the word using the server's default-strategy in all databases</em>
     406<p><strong>Returns:</strong>
     407<ul>
     408<li><strong>List</strong>  -  <em>A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to</em></li></ul></p>
     409<p><strong>Parameters:</strong>
     410<ul>
     411<li>
     412<p><strong><em>connection</em></strong> ... the connection object</p></li>
     413<li>
     414<p><strong><em>word</em></strong> ... The word to match</p></li></ul></p>
     415<p><b>dict:server-error codes</b>
     416<ul>
     417<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     418<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     419<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     420<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li></ul></p></p></dd>
    239421<dt class="definition"><strong>procedure:</strong> (dict:match!/default server word</dt>
    240 <dd></dd></dl>
     422<dd>
     423<p><em>Try to match the word using the server's default-strategy in all databases. Stop after the first match</em>
     424<p><strong>Returns:</strong>
     425<ul>
     426<li><strong>List</strong>  -  <em>A list of pairs. The car of each pair holds the word that matched wheras the cdr holds the database the matching word belongs to</em></li></ul></p>
     427<p><strong>Parameters:</strong>
     428<ul>
     429<li>
     430<p><strong><em>connection</em></strong> ... the connection object</p></li>
     431<li>
     432<p><strong><em>word</em></strong> ... The word to match</p></li></ul></p>
     433<p><b>dict:server-error codes</b>
     434<ul>
     435<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     436<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     437<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     438<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li></ul></p></p></dd></dl>
    241439<div class="section">
    242440<h3>Examples</h3>
     
    272470
    273471(dict:close srv)
    274 </pre></div></div></div></div></div>
     472</pre></div></div></div>
     473<div class="subsection">
     474<h4>Find definitions for a word</h4>
     475<dl>
     476<dt class="definition"><strong>procedure:</strong> (dict:define server database word)</dt>
     477<dd>
     478<p><em>Try to retrieve a defition of word in the given database</em></p>
     479<p><strong>Returns:</strong>
     480<ul>
     481<li><strong>List</strong>  -  <em>A list of defintions. Each sublist has length 3. The car holds the databasename where the defintion comes from. The cadr holds the a description of the database. The caddr holds the textual information</em></li></ul></p>
     482<p><strong>Parameters:</strong>
     483<ul>
     484<li>
     485<p><strong><em>connection</em></strong> ... the connection-object</p></li>
     486<li>
     487<p><strong><em>database</em></strong> ... the database as retrieved by e.g. dict:databases</p></li>
     488<li>
     489<p><strong><em>word</em></strong> ... The word to define</p></li></ul></p>
     490<p><b>dict:server-error codes</b>
     491<ul>
     492<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     493<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     494<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     495<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li>
     496<li><strong><em>dict:status:invalid-database</em></strong> Specified Database is not known by the Server</li></ul></p></dd>
     497<dt class="definition"><strong>procedure:</strong> (dict:define! server word)</dt>
     498<dd>
     499<p><em>Try to retrieve a defintion of word out of all databases. Stop after one defintion was found.</em></p>
     500<p><strong>Returns:</strong>
     501<ul>
     502<li><strong>List</strong>  -  <em>A list of defintions. Each sublist has length 3. The car holds the databasename where the defintion comes from. The cadr holds the a description of the database. The caddr holds the textual information</em></li></ul></p>
     503<p><strong>Parameters:</strong>
     504<ul>
     505<li>
     506<p><strong><em>connection</em></strong> ... the connection-object</p></li>
     507<li>
     508<p><strong><em>word</em></strong> ... The word to define</p></li></ul></p>
     509<p><b>dict:server-error codes</b>
     510<ul>
     511<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     512<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     513<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     514<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li></ul></p></dd>
     515<dt class="definition"><strong>procedure:</strong> (dict:define* server word)</dt>
     516<dd>
     517<p><em>Try to retrieve a defintion of word out of all databases.</em></p>
     518<p><strong>Returns:</strong>
     519<ul>
     520<li><strong>List</strong>  -  <em>A list of defintions. Each sublist has length 3. The car holds the databasename where the defintion comes from. The cadr holds the a description of the database. The caddr holds the textual information</em></li></ul></p>
     521<p><strong>Parameters:</strong>
     522<ul>
     523<li>
     524<p><strong><em>connection</em></strong> ... the connection-object</p></li>
     525<li>
     526<p><strong><em>word</em></strong> ... The word to define</p></li></ul></p>
     527<p><b>dict:server-error codes</b>
     528<ul>
     529<li><strong><em>dict:status:syntax-error-command</em></strong> The command is illformed </li>
     530<li><strong><em>dict:status:syntax-error-parameter</em></strong> A supplied parameter is invalid for the given command</li>
     531<li><strong><em>dict:status:command-not-implemented</em></strong> The given command is not implemented by the server</li>
     532<li><strong><em>dict:status:parameter-not-implemented</em></strong> The given command doesn't support the supplied parameter</li></ul></p></dd></dl>
     533<div class="section">
     534<h3>Examples</h3>
     535<div id="examples">
     536<pre>
     537(use dict)
     538
     539(define srv (dict:connect &quot;dict.org&quot;))
     540
     541(display (dict:define srv &quot;gcide&quot; &quot;scheme&quot;))
     542(newline)
     543
     544(display (dict:define! srv &quot;scheme&quot;))
     545(newline)
     546
     547(display (dict:define* srv &quot;scheme&quot;))
     548(newline)
     549
     550(dict:close srv)
     551</pre></div></div></div>
     552<div class="subsection">
     553<h4>General dict commands</h4>
     554<dl>
     555<dt class="definition"><strong>procedure:</strong> (dict:databases connection)</dt>
     556<dd></dd>
     557<dt class="definition"><strong>procedure:</strong> (dict:strategies connection)</dt>
     558<dd></dd>
     559<dt class="definition"><strong>procedure:</strong> (dict:help connection)</dt>
     560<dd></dd>
     561<dt class="definition"><strong>procedure:</strong> (dict:status connection)</dt>
     562<dd></dd>
     563<dt class="definition"><strong>procedure:</strong> (dict:server-information connection)</dt>
     564<dd></dd>
     565<dt class="definition"><strong>procedure:</strong> (dict:information connection database)</dt>
     566<dd></dd>
     567<dt class="definition"><strong>procedure:</strong> (dict:authenticate connection username password</dt>
     568<dd></dd></dl></div>
     569<div class="subsection">
     570<h4>Misc. Helpers</h4>
     571<dl>
     572<dt class="definition"><strong>procedure:</strong> (dict:call-with-command proc connection cmd . args)</dt>
     573<dd></dd>
     574<dt class="definition"><strong>procedure:</strong> (dict:decompose-status-response resp)</dt>
     575<dd></dd>
     576<dt class="definition"><strong>procedure:</strong> (dict:announce-client connection client-string)</dt>
     577<dd></dd></dl></div>
     578<div class="section">
     579<h3>Examples</h3>
     580<div id="examples">
     581<pre>(use dict)
     582
     583;; connect to the dict.org server
     584(define srv (dict:connect &quot;dict.org&quot;))
     585
     586;;print list of defintions
     587(define (display-defs defs)
     588  (for-each (lambda (def)
     589              (printf &quot;~A ~A ~%~A~%~%&quot; (car def) (cadr def) (caddr def)))
     590            defs))
     591
     592;;try to find the first match for word scheme
     593;;and retrieve all definitions for all matches
     594(let ((match (dict:match!/default srv &quot;scheme&quot;)))
     595  (unless (null? match)
     596    (for-each (lambda (word)
     597                (let ((definitions (dict:define srv (car match) word)))
     598                  (display-defs definitions)))
     599              (cdr match))))
     600
     601(display (dict:status srv))
     602(newline)
     603(display (dict:server-information srv))
     604(newline)
     605
     606(dict:close srv)
     607</pre></div></div></div></div>
    275608<div id="footer">
    276609<hr /><a href="index.html">&lt; Egg index</a>
  • release/3/dict/trunk/dict.scm

    r11652 r11653  
    4141(eval-when (compile)
    4242           (declare
    43             (unused dict:status:access-denied-show-info dict:status:access-denied-unknown-mech)
    4443            (export
     44             dict:status:access-denied-show-info dict:status:access-denied-unknown-mech
    4545             dict:status:n-databases-present dict:status:n-strategies-present dict:status:database-information-follows
    4646             dict:status:help-text-follows dict:status:server-information-follows dict:status:challenge-follows
     
    257257 
    258258  (let ((port (dict:connection-output con)))
    259     (display cmd port)
    260     (for-each (lambda (arg) (display " " port) (display arg port)) args)
    261     (display dict:crlf port)))
     259    (condition-case
     260     (begin
     261       (display cmd port)
     262       (for-each (lambda (arg) (display " " port) (display arg port)) args)
     263       (display dict:crlf port))
     264    (var () (dict:error "Connection instable or not present")))))
    262265
    263266(define (dict:call-with-command proc con cmd . args)
     
    449452      ((= code dict:status:no-database-present) '())
    450453      (else
    451        (dict:error "Malformed status response for command: SHOW DATABASE"))))
     454       (dict:error "Malformed status response for command: SHOW DATABASE" code msg))))
    452455   con
    453456   dict:cmd:show-db))
     
    461464      ((= code dict:status:no-strategies-present) '())
    462465      (else
    463        (dict:error "Malformed status response for command: SHOW STRAT"))))
     466       (dict:error "Malformed status response for command: SHOW STRAT" code msg))))
    464467   con
    465468   dict:cmd:show-strat))
     
    472475       (dict:collect-text con))
    473476      (else
    474        (dict:error "Malformed status response for command: SHOW SERVER"))))
     477       (dict:error "Malformed status response for command: SHOW SERVER" code msg))))
    475478   con
    476479   dict:cmd:show-server))
     
    484487      ((= code dict:status:invalid-database) (dict:server-error code "invalid database selected"))
    485488      (else
    486        (dict:error "Malformed status response for command: SHOW INFO"))))
     489       (dict:error "Malformed status response for command: SHOW INFO" code msg))))
    487490   con
    488491   dict:cmd:show-info
     
    496499       (dict:collect-text con))
    497500      (else
    498        (dict:error "Malformed status response for command: HELP"))))
     501       (dict:error "Malformed status response for command: HELP" code msg))))
    499502   con
    500503   dict:cmd:help))
     
    506509      ((= code dict:status:statistic) msg)
    507510      (else
    508        (dict:error "Malformed status response for command: STATUS"))))
     511       (dict:error "Malformed status response for command: STATUS" code msg))))
    509512   con
    510513   dict:cmd:status))
     
    517520      ((= code dict:status:authentication-successful) #t)
    518521      ((= code dict:status:access-denied) #f)
    519       (else
    520        (dict:error "Malformed status response for commmand: AUTH"))))
     522      ((= code dict:status:access-denied-show-info)
     523       (dict:server-error code "Authentication denied"))
     524      ((= code dict:status:access-denied-unknown-mech)
     525       (dict:server-error code "Authentication error. Unknown mechanism"))
     526      (else
     527       (dict:error "Malformed status response for commmand: AUTH" code msg))))
    521528   con
    522529   dict:cmd:auth
  • release/3/dict/trunk/tests/run-test.scm

    r11546 r11653  
    77;; Created: Di Aug  5 19:36:16 2008 (CEST)
    88;; Version:
    9 ;; Last-Updated: Di Aug  5 21:36:53 2008 (CEST)
     9;; Last-Updated: Sa Aug 16 19:48:12 2008 (CEST)
    1010;;           By: closure
    11 ;;     Update #: 60
     11;;     Update #: 84
    1212;; URL:
    1313;; Keywords:
     
    6565  (values (current-server-input) (current-server-output)))
    6666
    67 (define banner "220 fake-dict <auth.mime> <example@id.org>\r\n250 ok\r\n")
     67(define banner "220 fake-dict <auth.mime> <example@id.org>\r\n250 OK\r\n")
    6868
    6969(define (with-fake-io input proc)
     
    133133(define expect-on-close "CLIENT dict.egg for chicken scheme\r\nQUIT\r\n")
    134134
    135 ;;TODO look why the expectation doesnt work
    136135(test "close"
    137136      #t
    138       (with-fake-io "221 closing"
     137      (with-fake-io "221 closing\r\n"
    139138                    (lambda ()
    140139                      (let ((con (dict:connect "example.org")))
    141                         (and (dict:close con) (string-ci=? (get-output-string (current-server-output)) expect-on-close))))))
     140                        (and (dict:close con)
     141                             (string-ci=? (string-trim-right (get-output-string (current-server-output)) #\space) expect-on-close))))))
    142142     
    143143     
Note: See TracChangeset for help on using the changeset viewer.