Changeset 17949 in project


Ignore:
Timestamp:
04/27/10 22:55:10 (9 years ago)
Author:
Jim Ursetto
Message:

wiki/intarweb: Surgery for chicken-doc

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/intarweb

    r16674 r17949  
    2727=== Requests
    2828
    29 A request object (a [[defstruct]]-type record) can be created using
    30 the following procedure:
    31 
    3229<procedure>(make-request #!key uri port (method 'GET) (major 1) (minor 1) (headers (make-headers '())))</procedure>
    3330
    34 An existing request can be picked apart using the following procedures:
    35 
    36 * <procedure>(request-uri REQUEST) => URI</procedure>
    37 * <procedure>(request-port REQUEST) => PORT</procedure>
    38 * <procedure>(request-method REQUEST) => SYMBOL</procedure>
    39 * <procedure>(request-major REQUEST) => NUMBER</procedure>
    40 * <procedure>(request-minor REQUEST) => NUMBER</procedure>
    41 * <procedure>(request-headers REQUEST) => HEADERS</procedure>
    42 
    43 The uri defines the entity to retrieve on the server, which should be
    44 a [[uri-common]]-type URI object. The port is the scheme I/O port
    45 where the request is written to or read from.  The method is a symbol
    46 that defines the HTTP method to use (case sensitive). major and minor
     31Create a request object (a [[defstruct]]-type record). The client will
     32generally write requests, while the server will read them.
     33
     34The URI defines the entity to retrieve on the server, which should be
     35a [[uri-common]]-type URI object. The PORT is the scheme I/O port
     36where the request is written to or read from.  The METHOD is a symbol
     37that defines the HTTP method to use (case sensitive). MAJOR and MINOR
    4738identify the major and minor version of HTTP to use. Currently, 0.9,
    48391.0 and 1.1 are supported (but be careful with 0.9, it has some weird
    49 consequences and is not widely supported). Headers must be a headers
    50 object, which is described below.
    51 
    52 The client will generally write requests, while the server will read them.
    53 To write a request, use the following procedure:
     40consequences and is not widely supported). HEADERS must be a headers
     41object.
     42
     43<procedure>(request-uri REQUEST) => URI</procedure><br>
     44<procedure>(request-port REQUEST) => PORT</procedure><br>
     45<procedure>(request-method REQUEST) => SYMBOL</procedure><br>
     46<procedure>(request-major REQUEST) => NUMBER</procedure><br>
     47<procedure>(request-minor REQUEST) => NUMBER</procedure><br>
     48<procedure>(request-headers REQUEST) => HEADERS</procedure><br>
     49
     50An existing request can be picked apart with these accessors.
    5451
    5552<procedure>(write-request REQUEST) => REQUEST</procedure>
    5653
    57 This will write a request line with headers to the server.  In case it
     54Write a request line with headers to the server.  In case it
    5855is a request type that has any body data, this should be written to
    5956the the request's port. Beware that this port can be modified by
     
    6663body can be read from the request-port after calling this procedure.
    6764
     65<parameter>(request-parsers [LIST])</parameter>
     66
    6867Requests are parsed using parse procedures, which can be customized
    69 by overriding this parameter:
    70 
    71 <parameter>(request-parsers [LIST])</parameter>
    72 
    73 The list is one of procedures which accept a request line string,
    74 which produce a request object from that, or {{#f}} if the request
    75 is not of the type handled by that procedure.
    76 
    77 The predefined request parsers are the following:
    78 
    79 * <procedure>(http-0.9-request-parser STRING) => REQUEST</procedure>
    80 * <procedure>(http-1.x-request-parser STRING) => REQUEST</procedure>
     68by overriding this parameter.
     69
     70LIST is a list of procedures which accept a request line
     71string and produce a request object, or {{#f}} if the
     72request is not of the type handled by that procedure.
     73
     74The predefined request parsers are:
     75
     76* {{http-0.9-request-parser}}
     77* {{http-1.x-request-parser}}
     78
     79<procedure>(http-0.9-request-parser STRING) => REQUEST</procedure><br>
     80<procedure>(http-1.x-request-parser STRING) => REQUEST</procedure><br>
     81
     82Predefined request parsers for use with {{request-parsers}}.
     83
     84<parameter>(request-unparsers [LIST])</parameter>
    8185
    8286Requests are written using unparse procedures, which can be
    83 customized by overriding this parameter:
    84 
    85 <parameter>(request-unparsers [LIST])</parameter>
    86 
    87 The list is one of procedures which accept a request object and write
     87customized by overriding this parameter.
     88
     89LIST is list of procedures which accept a request object and write
    8890to the request's output port and return the new, possibly updated
    8991request object. If the request object is not unparsed by this
    9092handler, it returns {{#f}}.
    9193
    92 The predefined request unparsers are the following:
    93 
    94 * <procedure>(http-0.9-request-unparser REQUEST) => REQUEST</procedure>
    95 * <procedure>(http-1.x-request-unparser REQUEST) => REQUEST</procedure>
    96 
     94The predefined request unparsers are:
     95
     96* {{http-0.9-request-unparser}}
     97* {{http-1.x-request-unparser}}
     98
     99<procedure>(http-0.9-request-unparser REQUEST) => REQUEST</procedure><br>
     100<procedure>(http-1.x-request-unparser REQUEST) => REQUEST</procedure><br>
     101
     102Predefined request unparsers for use with {{request-unparsers}}.
    97103They return the request, and as a side effect they write the
    98104request to the request object's port.
     
    100106=== Responses
    101107
    102 A response is also a [[defstruct]]-type record, much like a request:
    103 
    104108<procedure>(make-response #!key port (code 200) (reason "OK") (major 1) (minor 1) (headers (make-headers '())))</procedure>
    105109
    106 An existing response can be picked apart using the following procedures:
    107 * <procedure>(response-port RESPONSE) => PORT</procedure>
    108 * <procedure>(response-code RESPONSE) => NUMBER</procedure>
    109 * <procedure>(response-reason RESPONSE) => STRING</procedure>
    110 * <procedure>(response-class RESPONSE-OR-CODE) => NUMBER</procedure>
    111 * <procedure>(response-major RESPONSE) => NUMBER</procedure>
    112 * <procedure>(response-minor RESPONSE) => NUMBER</procedure>
    113 * <procedure>(response-headers RESPONSE) => HEADERS</procedure>
    114 
    115 The port, major, minor and headers are the same as for requests. code
    116 and reason are an integer status code and the short message that
     110Create a response, a [[defstruct]]-type record.  A server will usually
     111write a response with {{write-response}}; a client will read it
     112with {{read-response}}.
     113
     114<procedure>(response-port RESPONSE) => PORT</procedure><br>
     115<procedure>(response-code RESPONSE) => NUMBER</procedure><br>
     116<procedure>(response-reason RESPONSE) => STRING</procedure><br>
     117<procedure>(response-class RESPONSE-OR-CODE) => NUMBER</procedure><br>
     118<procedure>(response-major RESPONSE) => NUMBER</procedure><br>
     119<procedure>(response-minor RESPONSE) => NUMBER</procedure><br>
     120<procedure>(response-headers RESPONSE) => HEADERS</procedure><br>
     121
     122An existing response can be picked apart using these accessors.
     123
     124The PORT, MAJOR, MINOR and HEADERS are the same as for requests. CODE
     125and REASON are an integer status code and the short message that
    117126belongs to it, as defined in the spec (examples include: 200 OK, 301
    118 Moved Permanently, etc).  class is the major class of the response
     127Moved Permanently, etc).  CLASS is the major class of the response
    119128code (100, 200, 300, 400 or 500).  {{response-class}} can be called
    120129either on a response object or directly on a response code number.
    121130
    122 A server will usually write a response, a client will read it.
    123 To write a response, use the following procedure:
    124 
    125131<procedure>(write-response RESPONSE) => RESPONSE</procedure>
     132
     133Write the response object RESPONSE to the {{response-port}}.
    126134
    127135If there is a response body, this must be written to the response-port
     
    133141be read from the response-port after calling this procedure.
    134142
     143<parameter>(response-parsers [LIST])</parameter>
     144
    135145Responses are parsed using parse procedures, which can be customized
    136 by overriding this parameter:
    137 
    138 <parameter>(response-parsers [LIST])</parameter>
    139 
    140 The list is one of procedures which accept a response line string,
    141 which produce a response object from that, or {{#f}} if the response
    142 is not of the type handled by that procedure.
    143 
    144 The predefined response parsers are the following:
    145 
    146 * <procedure>(http-0.9-response-unparser REQUEST) => REQUEST</procedure>
    147 * <procedure>(http-1.x-response-unparser REQUEST) => REQUEST</procedure>
     146by overriding this parameter.
     147
     148LIST is a list one of procedures which accept a response line string
     149and produce a response object, or {{#f}} if the response is not of the
     150type handled by that procedure.
     151
     152The predefined response parsers are:
     153
     154* {{http-0.9-response-parser}}
     155* {{http-1.x-response-parser}}
     156
     157<procedure>(http-0.9-response-parser REQUEST) => REQUEST</procedure><br>
     158<procedure>(http-1.x-response-parser REQUEST) => REQUEST</procedure><br>
     159
     160Predefined response parsers for use with {{response-parser}}.
     161
     162<parameter>(response-unparsers [LIST])</parameter>
    148163
    149164Responses are written using unparse procedures, which can be
    150 customized by overriding this parameter:
    151 
    152 <parameter>(response-unparsers [LIST])</parameter>
    153 
    154 The list is one of procedures which accept a response object and write
     165customized by overriding this parameter.
     166
     167LIST is a list of procedures which accept a response object and write
    155168to the response's output port and return the new, possibly updated
    156169response object. If the response object is not unparsed by this
     
    159172The predefined response unparsers are the following:
    160173
    161 * <procedure>(http-0.9-response-unparser REQUEST) => REQUEST</procedure>
    162 * <procedure>(http-1.x-response-unparser REQUEST) => REQUEST</procedure>
     174* {{http-0.9-response-unparser}}
     175* {{http-1.x-response-unparser}}
     176
     177<procedure>(http-0.9-response-unparser REQUEST) => REQUEST</procedure><br>
     178<procedure>(http-1.x-response-unparser REQUEST) => REQUEST</procedure><br>
     179
     180Predefined response unparsers for use with {{response-unparser}}.
    163181
    164182=== Headers
     183
     184<procedure>(headers ALIST [HEADERS]) => HEADERS</procedure>
     185
     186This creates a header object based on an input list.
    165187
    166188Requests and responses contain HTTP headers wrapped in a special
    167189header-object to ensure they are properly normalized.
    168190
    169 <procedure>(headers ALIST [HEADERS]) => HEADERS</procedure>
    170 
    171 This creates a header object based on an input list.
    172 
    173 <procedure>(headers->list HEADERS) => ALIST</procedure>
    174 
    175 This converts the header object back to a list.
    176 
    177 The above mentioned lists have header names (symbols) as keys, and
     191The input list has header names (symbols) as keys, and
    178192lists of values as values:
    179193
     
    190204{{old-headers}}. The host header is either a string with the hostname
    191205or a pair of hostname/port. The accept header is a list of allowed
    192 mime-type symbols. As can be seen here, optional parameters or
    193 "attributes" can be added to a header value by wrapping the value in a
    194 vector of length 2. The first entry in the vector is the header value,
    195 the second is an alist of attribute name/value pairs.
    196 
    197 To obtain the value of any particular header, you can use
     206mime-type symbols.
     207
     208As can be seen here, optional parameters or "attributes" can be added
     209to a header value by wrapping the value in a vector of length 2. The
     210first entry in the vector is the header value, the second is an alist
     211of attribute name/value pairs.
     212
     213<procedure>(headers->list HEADERS) => ALIST</procedure>
     214
     215This converts a header object back to a list.  See {{headers}}
     216for details.
    198217
    199218<procedure>(header-values NAME HEADERS) => LIST</procedure>
    200219
    201 The name of the header is a symbol, and it will return all the values
     220Obtain the value of header NAME in the HEADERS object.
     221
     222The NAME of the header is a symbol; this procedure will return all the values
    202223of the header (for example, the Accept header will have several values
    203224that indicate the set of acceptable mime-types).
    204225
    205 If you know in advance that a header has only one value, you can use:
    206 
    207226<procedure>(header-value NAME HEADERS [DEFAULT]) => value</procedure>
    208227
    209 This will return the first value in the list, or the provided default
    210 if there is no value for that header.
    211 
    212 * <procedure>(header-params NAME HEADERS) => ALIST</procedure>
     228If you know in advance that a header has only one value, you can use
     229{{header-value}} instead of {{header-values}}.  This will return the
     230first value in the list, or the provided default if there is no value
     231for that header.
     232
     233<procedure>(header-params NAME HEADERS) => ALIST</procedure>
    213234
    214235This will return all the params for a given header, assuming there is
    215236only one header.  An empty list is returned if the header does not exist.
    216237
    217 * <procedure>(header-param PARAM NAME HEADERS [DEFAULT]) => value</procedure>
    218 
    219 This will return a specific parameter for the header, or the
    220 {{DEFAULT}} is the parameter isn't present or the header does not
    221 exist.  This also assumes there's only one header.
    222 
    223 The procedures mentioned above are just shortcuts, the underlying
    224 procedures to query the raw contents of a header are these:
    225 
    226 * <procedure>(header-contents NAME HEADERS) => VECTOR</procedure>
    227 * <procedure>(get-value VECTOR) => value</procedure>
    228 * <procedure>(get-params VECTOR) => ALIST</procedure>
    229 * <procedure>(get-param PARAM VECTOR [DEFAULT]) => value</procedure>
     238<procedure>(header-param PARAM NAME HEADERS [DEFAULT]) => value</procedure>
     239
     240This will return a specific parameter for the header, or DEFAULT
     241if the parameter isn't present or the header does not exist.  This
     242also assumes there's only one header.
     243
     244<procedure>(header-contents NAME HEADERS) => VECTOR</procedure><br>
     245<procedure>(get-value VECTOR) => value</procedure><br>
     246<procedure>(get-params VECTOR) => ALIST</procedure><br>
     247<procedure>(get-param PARAM VECTOR [DEFAULT]) => value</procedure><br>
     248
     249Procedures such as {{header-values}} are just shortcuts; these are
     250the underlying procedures to query the raw contents of a header.
    230251
    231252Header contents are 2-element vectors; the first value containing the
     
    503524==== Header parsers and unparsers
    504525
     526<parameter>(header-parsers [ALIST])</parameter><br>
     527<parameter>(header-unparsers [ALIST])</parameter><br>
     528
    505529The parsers and unparsers used to read and write header values can be
    506 customized with the following parameters:
    507 
    508 * <parameter>(header-parsers [ALIST])</parameter>
    509 * <parameter>(header-unparsers [ALIST])</parameter>
     530customized with these parameters.
    510531
    511532These (un)parsers are indexed with as key the header name (a symbol)
     
    527548parser's result.
    528549
    529 When there's an error parsing a given header, the following
    530 parameter's procedure will be invoked:
    531 
    532550<parameter>(header-parse-error-handler [HANDLER])</parameter>
     551
     552When there is an error parsing a given header, this
     553parameter's procedure will be invoked.
    533554
    534555{{HANDLER}} is a procedure accepting four values: the header name, the
     
    546567it's best to simply ignore these headers with "bad" content values.
    547568
    548 * <procedure>(replace-header-contents NAME CONTENTS HEADERS) => HEADERS</procedure>
    549 * <procedure>(replace-header-contents! NAME CONTENTS HEADERS) => HEADERS</procedure>
    550 * <procedure>(update-header-contents NAME CONTENTS HEADERS) => HEADERS</procedure>
    551 * <procedure>(update-header-contents! NAME CONTENTS HEADERS) => HEADERS</procedure>
     569<procedure>(replace-header-contents NAME CONTENTS HEADERS) => HEADERS</procedure><br>
     570<procedure>(replace-header-contents! NAME CONTENTS HEADERS) => HEADERS</procedure><br>
     571<procedure>(update-header-contents NAME CONTENTS HEADERS) => HEADERS</procedure><br>
     572<procedure>(update-header-contents! NAME CONTENTS HEADERS) => HEADERS</procedure><br>
    552573
    553574The {{replace}} procedures replace any existing contents of the named
     
    563584single-header.
    564585
     586<parameter>(single-headers [LIST])</parameter>
     587
    565588Whether a header is allowed once or multiple times in a request or
    566 response is determined by this parameter:
    567 
    568 <parameter>(single-headers [LIST])</parameter>
     589response is determined by this parameter.
    569590
    570591The value is a list of symbols that define header-names which are
    571592allowed to occur only once in a request/response.
    572593
    573 * <procedure>(http-name->symbol-name STRING) => SYMBOL</procedure>
    574 * <procedure>(symbol->http-name SYMBOL) => STRING</procedure>
     594<procedure>(http-name->symbol-name STRING) => SYMBOL</procedure><br>
     595<procedure>(symbol->http-name SYMBOL) => STRING</procedure><br>
    575596
    576597These procedures convert strings containing the name of a header or
     
    580601attribute are capitalized.
    581602
    582 * <procedure>(remove-header name headers) => headers</procedure>
    583 * <procedure>(remove-header! name headers) => headers</procedure>
     603<procedure>(remove-header name headers) => headers</procedure><br>
     604<procedure>(remove-header! name headers) => headers</procedure><br>
    584605
    585606These two procedures remove all headers with the given name.
Note: See TracChangeset for help on using the changeset viewer.