Changeset 12872 in project for wiki/eggref/4/intarweb


Ignore:
Timestamp:
12/24/08 15:23:27 (12 years ago)
Author:
sjamaan
Message:

Add some more documentation, so all(?) exported names are documented

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/intarweb

    r12866 r12872  
    7575is not of the type handled by that procedure.
    7676
     77The 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>
     81
    7782Requests are written using unparse procedures, which can be
    7883customized by overriding this parameter:
     
    8489request object. If the request object is not unparsed by this
    8590handler, it returns {{#f}}.
     91
     92The 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>
    8696
    8797=== Responses
     
    126136is not of the type handled by that procedure.
    127137
     138The predefined response parsers are the following:
     139
     140* <procedure>(http-0.9-response-unparser REQUEST) => REQUEST</procedure>
     141* <procedure>(http-1.x-response-unparser REQUEST) => REQUEST</procedure>
     142
    128143Responses are written using unparse procedures, which can be
    129144customized by overriding this parameter:
     
    136151handler, it returns {{#f}}.
    137152
     153The predefined response unparsers are the following:
     154
     155* <procedure>(http-0.9-response-unparser REQUEST) => REQUEST</procedure>
     156* <procedure>(http-1.x-response-unparser REQUEST) => REQUEST</procedure>
     157
    138158=== Headers
    139159
     
    143163<procedure>(headers ALIST [HEADERS]) => HEADERS</procedure>
    144164
    145 This creates headers based on an input list. This list has the
    146 header-name as a symbol key, and a list of values as value:
     165This creates a header object based on an input list.
     166
     167<procedure>(headers->list HEADERS) => ALIST</procedure>
     168
     169This converts the header object back to a list.
     170
     171The above mentioned lists have header names (symbols) as keys, and
     172lists of values as values:
    147173
    148174<example>
     
    163189the second is an alist of attribute name/value pairs.
    164190
     191To obtain the value of any particular header, you can use
     192
     193<procedure>(header-values NAME HEADERS) => LIST</procedures>
     194
     195The name of the header is a symbol, and it will return all the values
     196of the header (for example, the Accept header will have several values
     197that indicate the set of acceptable mime-types).
     198
     199If you know in advance that a header has only one value, you can use:
     200
     201<procedure>(header-value NAME HEADERS [DEFAULT]) => value</procedure>
     202
     203This will return the first value in the list, or the provided default
     204if there is no value for that header.
     205
     206These are just shortcuts, the underlying procedures to query the raw
     207contents of a header are these:
     208
     209* <procedure>(header-contents NAME HEADERS) => VECTOR</procedure>
     210* <procedure>(get-value VECTOR) => value</procedure>
     211* <procedure>(get-params VECTOR) => ALIST</procedure>
     212* <procedure>(get-param PARAM VECTOR [DEFAULT]) => value</procedure>
     213
     214Header contents are 2-element vectors; the first value containing the
     215value for the header and the second value containing an alist with
     216"parameters" for that header value. Parameters are attribute/value
     217pairs that define further specialization of a header's value. For
     218example, the {{accept}} header consists of a list of mime-types, which
     219optionally can have a quality parameter that defines the preference
     220for that mime-type.  All parameter names are downcased symbols, just
     221like header names.
     222
     223There are special-purpose procedures for obtaining information about
     224specific header parameters when the spec defines certain behaviour for
     225them, as well:
     226
     227* <procedure>(get-quality PARAM VECTOR [DEFAULT]) =>
     228value</procedure>
     229
     230This obtains the value of the {{q}} parameter for the given header
     231value, if any, or {{1}} if there is none defined.
     232
     233==== Header types
     234
    165235The headers all have their own different types.  Here follows a list
    166236of headers with their value types:
     
    421491entire header lines are put unparsed into a list, one entry per line.
    422492
    423 ==== Header-parsers
    424 
    425 The parsers used to read and write header values can be customized
    426 with the following parameters:
     493
     494==== Header parsers and unparsers
     495
     496The parsers and unparsers used to read and write header values can be
     497customized with the following parameters:
    427498
    428499* <parameter>(header-parsers [ALIST])</parameter>
    429500* <parameter>(header-unparsers [ALIST])</parameter>
    430501
    431 These parsers are indexed with as key the header name (a symbol) and
    432 the value being a procedure which accepts three values: the name of
    433 the header (symbol), the contents of the header (a string, without the
    434 leading header name and colon) and the preceding headers. It should
    435 merge the new header with the preceding headers and return the
     502These (un)parsers are indexed with as key the header name (a symbol)
     503and the value being a procedure which accepts three values: the name
     504of the header (symbol), the contents of the header (a string, without
     505the leading header name and colon) and the preceding headers. It
     506should merge the new header with the preceding headers and return the
    436507resulting headers.
    437508
     
    462533The value is a list of symbols that define header-names which are
    463534allowed to occur only once in a request/response.
     535
     536* <procedure>(http-name->symbol-name STRING) => SYMBOL</procedure>
     537* <procedure>(symbol->http-name SYMBOL) => STRING</procedure>
     538
     539These procedures convert strings containing the name of a header or
     540attribute (parameter name) to symbols representing the same. The
     541symbols are completely downcased.  When converting this symbol back to
     542a string, the initial letters of all the words in the header name or
     543attribute are capitalized.
    464544
    465545=== Changelog
Note: See TracChangeset for help on using the changeset viewer.