Defines a handler as if
by
DEFUN and optionally registers it with a
URI so that it will be found
by DISPATCH-EASY-HANDLERS.
description is either a
symbol name or a list matching the
destructuring
lambda list
(name &key uri acceptor-names default-parameter-type default-request-type).
lambda-list is a list the elements of which
are either a symbol var or a list matching
the destructuring lambda list
(var &key real-name parameter-type init-form request-type).
The resulting handler will be a Lisp function with the
name name and keyword parameters named by
the var symbols.
Each var will be bound to the value of the
GET or POST parameter called real-name (a
string) before the body of the function is executed.
If real-name is not provided, it will be
computed
by downcasing
the symbol name of var.
If uri (which is evaluated) is provided,
then it must be a string or
a function
designator for a unary function. In this case, the
handler will be returned
by DISPATCH-EASY-HANDLERS,
if uri is a string and
the script name of the current
request is uri, or
if uri designates a function and applying
this function to
the current REQUEST
object returns a true value.
acceptor-names (which is evaluated) can be a
list of symbols which means that the handler will only be
returned by DISPATCH-EASY-HANDLERS in
acceptors which have one of these names
(see ACCEPTOR-NAME). acceptor-names can also be the
symbol T which means that the handler will be
returned by DISPATCH-EASY-HANDLERS
in every acceptor.
Whether the GET or POST parameter (or both) will be taken into
consideration, depends on request-type
which can
be :GET, :POST, :BOTH,
or NIL. In the last case, the value of
default-request-type (the default of which
is :BOTH) will be used.
The value of var will usually be a string
(unless it resulted from a file upload
in which case it won't be converted at all), but
if parameter-type (which is evaluated) is
provided, the string will be converted to another Lisp type by
the following rules:
If the corresponding GET or POST parameter wasn't provided by
the client, var's value will
be NIL. If parameter-type
is 'STRING,
var's value remains as is.
If parameter-type is 'INTEGER
and the parameter string consists solely of decimal
digits, var's value will be the
corresponding integer, otherwise NIL.
If parameter-type is
'KEYWORD, var's value will be
the keyword obtained
by interning
the upcased
parameter string into
the keyword
package. If parameter-type
is 'CHARACTER and the parameter string is of
length one, var's value will be the single
character of this string, otherwise NIL.
If parameter-type
is 'BOOLEAN, var's value will
always be T (unless it is NIL by the
first rule above, of course).
If parameter-type is any other atom, it is
supposed to be
a function
designator for a unary function which will be called to
convert the string to something else.
Those were the rules for simple parameter types, but
parameter-type can also be a list starting
with one of the symbols
LIST, ARRAY,
or HASH-TABLE. The second value of the list must
always be a simple parameter type as in the last paragraph -
we'll call it the inner type below.
In the case of 'LIST, all GET/POST parameters
called real-name will be collected,
converted to the inner type as by the rules above, and
assembled into a list which will be the value of
var.
In the case of 'ARRAY, all GET/POST parameters
which have a name like the result of
(format nil "~A[~A]" real-name n)
where n is a non-negative integer, will be
assembled into an array where the nth element
will be set accordingly, after conversion to the inner type.
The array, which will become the value
of var, will be big enough to hold all
matching parameters, but not bigger. Array elements not set as
described above will be NIL. Note
that VAR will always be bound to an array, which
may be empty, so it will never be NIL, even if no
appropriate GET/POST parameters are found.
The full form of a 'HASH-TABLE parameter type is
(hash-table inner-type key-type test-function)
but key-type
and test-function can be left out in which
case they default to 'STRING
and 'EQUAL, respectively. For this parameter type,
all GET/POST parameters which have a name like the result of
(format nil "~A{~A}" real-name key)
(where key is a string that doesn't contain
curly brackets) will become the values (after conversion
to inner-type) of a hash table with test
function test-function
where key (after conversion
to key-type) will be the corresponding key.
Note that var will always be bound to a hash
table, which may be empty, so it will never be NIL,
even if no appropriate GET/POST parameters are found.
To make matters even more complicated, the three compound
parameter types also have an abbreviated form - just one of
the symbols LIST, ARRAY,
or HASH-TABLE. In this case, the inner type will
default to 'STRING.
If parameter-type is not provided
or NIL, default-parameter-type
(the default of which is 'STRING) will be used
instead.
If the result of the computations above would be
that var would be bound
to NIL, then init-form (if
provided) will be evaluated instead,
and var will be bound to the result of this
evaluation.
Handlers built with this macro are constructed in such a way
that the resulting Lisp function is useful even outside of
Hunchentoot. Specifically, all the parameter computations
above will only happen if *REQUEST* is
bound, i.e. if we're within a Hunchentoot request.
Otherwise, var will always be bound to the
result of evaluating init-form unless a
corresponding keyword argument is provided.
The example code that comes with
Hunchentoot contains an example which demonstrates some of the
features of DEFINE-EASY-HANDLER.
HUNCHENTOOT - The Common Lisp web server formerly known as TBNL