lispdoc - results for define-easy-handler

(hunchentoot:define-easy-handler description lambda-list &body body)
Function: Defines a handler with the body BODY 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 BODY 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 function of one argument. In this case, the handler will be returned by DISPATCH-EASY-HANDLERS, if URI is a string and the script name of a 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 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' 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, 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.