Common Lisp Package: TBNL

README:

FUNCTION

Public

AUTHORIZATION (&OPTIONAL (REQUEST *REQUEST*))

Returns as two values the user and password (if any) as captured in the 'AUTHORIZATION' header of the REQUEST object REQUEST.

AUX-REQUEST-VALUE (SYMBOL &OPTIONAL (REQUEST *REQUEST*))

Returns the value associated with SYMBOL from the request object REQUEST (the default is the current request) if it exists.

CONTENT-LENGTH (&OPTIONAL (REPLY *REPLY*))

The outgoing 'Content-Length' http header of REPLY.

CONTENT-TYPE (&OPTIONAL (REPLY *REPLY*))

The outgoing 'Content-Type' http header of REPLY.

COOKIES-IN (&OPTIONAL (REQUEST *REQUEST*))

Returns an alist of all cookies associated with the REQUEST object REQUEST.

COOKIES-OUT (&OPTIONAL (REPLY *REPLY*))

Returns an alist of the outgoing cookies associated with the REPLY object REPLY.

CREATE-FOLDER-DISPATCHER-AND-HANDLER (URI-PREFIX BASE-PATH &OPTIONAL DEFAULT-CONTENT-TYPE)

Creates and returns a dispatch function which will dispatch to a handler function which emits the file relative to BASE-PATH that is denoted by the URI of the request relative to URI-PREFIX. URI-PREFIX must be a string ending with a slash, BASE-PATH must be a pathname designator for an existing directory. The content types of the files are determined via their suffix, falling back to DEFAULT-CONTENT-TYPE if the suffix is unknown.

CREATE-PREFIX-DISPATCHER (PREFIX PAGE-FUNCTION)

Creates a dispatch function which will dispatch to the function denoted by PAGE-FUNCTION if the file name of the current request starts with the string PREFIX.

CREATE-REGEX-DISPATCHER (REGEX PAGE-FUNCTION)

Creates a dispatch function which will dispatch to the function denoted by PAGE-FUNCTION if the file name of the current request matches the CL-PPCRE regular expression REGEX.

CREATE-STATIC-FILE-DISPATCHER-AND-HANDLER (URI PATH &OPTIONAL CONTENT-TYPE)

Creates and returns a dispatch function which will dispatch to a handler function which emits the file denoted by the pathname designator PATH with content type CONTENT-TYPE if the SCRIPT-NAME of the request matches the string URI. If CONTENT-TYPE is NIL tries to determine the content type via the file's suffix.

DEFAULT-DISPATCHER (REQUEST)

Default dispatch function which handles every request with the function stored in *DEFAULT-HANDLER*.

DELETE-AUX-REQUEST-VALUE (SYMBOL &OPTIONAL (REQUEST *REQUEST*))

Removes the value associated with SYMBOL from the request object REQUEST.

DELETE-SESSION-VALUE (SYMBOL &OPTIONAL (SESSION *SESSION*))

Removes the value associated with SYMBOL from the current session object if there is one.

DISPATCH-EASY-HANDLERS (REQUEST)

This is a dispatcher which returns the appropriate handler defined with DEFINE-EASY-HANDLER, if there is one.

ESCAPE-FOR-HTML (STRING)

Escapes the characters #\<, #\>, #\', #\", and #\& for HTML output.

GET-BACKTRACE (ERROR)

This is the function that is used internally by TBNL to show or log backtraces. It accepts a condition object ERROR and returns a string with the corresponding backtrace.

GET-PARAMETER (NAME &OPTIONAL (REQUEST *REQUEST*))

Returns the GET parameter with name NAME as captured in the REQUEST object REQUEST. Search is case-sensitive.

GET-PARAMETERS (&OPTIONAL (REQUEST *REQUEST*))

Returns an alist of the GET parameters associated with the REQUEST object REQUEST.

HANDLE-IF-MODIFIED-SINCE (TIME &OPTIONAL (REQUEST *REQUEST*))

Handles the If-Modified-Since header of the REQUEST. Date string is compared to the one generated from the supplied TIME.

HANDLE-STATIC-FILE (PATH &OPTIONAL CONTENT-TYPE)

A function which acts like a TBNL handler for the file denoted by PATH. Send a content type header corresponding to CONTENT-TYPE or (if that is NIL) tries to determine the content type via the file's suffix.

HEADER-IN (NAME &OPTIONAL (REQUEST *REQUEST*))

Returns the incoming header with name NAME as captured in the REQUEST object REQUEST. Search is case-insensitive.

HEADER-OUT (NAME &OPTIONAL (REPLY *REPLY*))

Returns the current value of the outgoing http header named NAME. Search is case-insensitive.

HEADERS-IN (&OPTIONAL (REQUEST *REQUEST*))

Returns an alist of the incoming headers associated with the REQUEST object REQUEST.

HEADERS-OUT (&OPTIONAL (REPLY *REPLY*))

Returns an alist of the outgoing headers associated with the REPLY object REPLY.

HOST (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'Host' incoming http header value captured in the REQUEST object REQUEST.

HTTP-TOKEN-P (TOKEN)

Tests whether TOKEN is a string which is a valid 'token' according to HTTP/1.1 (RFC 2068).

LOG-FILE

Returns the log file which is currently used.

SETFLOG-FILE (PATHSPEC)

Sets the log file which is to be used.

LOG-MESSAGE* (FMT &REST ARGS)

Same as LOG-MESSAGE* but with the default log level (as defined by *DEFAULT-LOG-LEVEL*).

MOD-LISP-ID (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'Server ID' sent by mod_lisp as captured in the REQUEST object REQUEST. This value is set in Apache's server configuration file and is of course only available if mod_lisp is the front-end.

NO-CACHE

Adds appropriate headers to completely prevent caching on most browsers.

PARAMETER (NAME &OPTIONAL (REQUEST *REQUEST*))

Returns the GET or the POST parameter with name NAME as captured in the REQUEST object REQUEST. If both a GET and a POST parameter with the same name exist the GET parameter is returned. Search is case-sensitive.

POST-PARAMETER (NAME &OPTIONAL (REQUEST *REQUEST*))

Returns the POST parameter with name NAME as captured in the REQUEST object REQUEST. Search is case-sensitive.

POST-PARAMETERS (&OPTIONAL (REQUEST *REQUEST*))

Returns an alist of the POST parameters associated with the REQUEST object REQUEST.

QUERY-STRING (&OPTIONAL (REQUEST *REQUEST*))

Returns the query string of the REQUEST object REQUEST. That's the part behind the question mark (i.e. the GET parameters).

RAW-POST-DATA (&OPTIONAL (REQUEST *REQUEST*))

Returns the raw string sent as the body of a POST request.

READ-FROM-STRING* (STRING)

Safe version of READ-FROM-STRING: Symbols are interned in the :TBNL-DUMMY package, *READ-EVAL* is turned off.

REAL-REMOTE-ADDR (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'X-Forwarded-For' incoming http header value captured in the REQUEST object REQUEST if it exists. Otherwise returns the value of REMOTE-ADDR.

RECOMPUTE-REQUEST-PARAMETERS (&KEY (REQUEST *REQUEST*) (EXTERNAL-FORMAT *TBNL-DEFAULT-EXTERNAL-FORMAT*))

Recomputes the GET and POST parameters for the REQUEST object REQUEST. This only makes sense if you're using a different external format.

REDIRECT (SCRIPT-NAME &KEY (HOST (HOST *REQUEST*) HOST-PROVIDED-P) (PROTOCOL (IF (SSL-SESSION-ID *REQUEST*) HTTPS HTTP)) (ADD-SESSION-ID (NOT (OR HOST-PROVIDED-P (COOKIE-IN *SESSION-COOKIE-NAME*)))) PERMANENTLY)

Redirects the browser to the resource SCRIPT-NAME on host HOST. PROTOCOL must be one of the keywords :HTTP or :HTTPS. Adds a session ID if ADD-SESSION-ID is true. If PERMANENTLY is true, a 301 request is sent to the browser, otherwise a 302.

REFERER (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'Referer' (sic!) incoming http header value captured in the REQUEST object REQUEST.

REMOTE-ADDR (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'REMOTE_ADDR' header (if sent by the front-end, otherwise the IP address of the remote host if available) as captured in the REQUEST object REQUEST. See also REAL-REMOTE-ADDR.

REMOTE-PORT (&KEY (REQUEST *REQUEST*) (AS-NUMBER T))

Returns the 'REMOTE_PORT' header (if sent by the front-end, otherwise the IP port of the remote host) as captured in the REQUEST object REQUEST. If AS-NUMBER is true, which is the default, the value is returned as a number, otherwise as a string.

REQUEST-METHOD (&KEY (REQUEST *REQUEST*) (AS-KEYWORD T))

Returns the 'REQUEST_METHOD' header (if sent by the front-end) as captured in the REQUEST object REQUEST. If AS-KEYWORD is true, which is the default, the value will be returned as a keyword like :GET or :POST.

REQUEST-URI (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'REQUEST_URI' header (if sent by the front-end) as captured in the REQUEST object REQUEST.

RESET-SESSIONS

Removes ALL stored sessions and creates a new session secret.

RETURN-CODE (&OPTIONAL (REPLY *REPLY*))

The http return code of REPLY. The return codes TBNL can handle are defined in specials.lisp.

RFC-1123-DATE (&OPTIONAL (TIME (GET-UNIVERSAL-TIME)))

Generate time string according to RFC 1123. Default is current time.

SCRIPT-NAME (&OPTIONAL (REQUEST *REQUEST*))

Returns the file name of the REQUEST object REQUEST. That's the requested URI without the query string (i.e the GET parameters).

SEND-HEADERS

Sends the initial status line and all headers as determined by the REPLY object *REPLY*. Returns a stream to which the body of the reply can be written. Once this function has been called further changes to *REPLY* don't have any effect. Also, automatic handling of errors (i.e. sending the corresponding status code to the browser, etc.) is turned off for this request. If your handlers return the full body as a string or as an array of octets you should NOT call this function.

SERVER-ADDR (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'SERVER_ADDR' header (if sent by the front-end, otherwise the IP address of the TBNL host if available) as captured in the REQUEST object REQUEST.

SERVER-PORT (&KEY (REQUEST *REQUEST*) (AS-NUMBER T))

Returns the IP port where the request came in (if sent by the front-end). If AS-NUMBER-P is true, which is the default, the value is returned as a number.

SERVER-PROTOCOL (&KEY (REQUEST *REQUEST*) (AS-KEYWORD T))

Returns the 'SERVER_PROTOCOL' environent value (if sent by the front-end) as captured in the REQUEST object REQUEST. If AS-KEYWORD is true, which is the default, the value will be returned as a keyword like :HTTP/1.0 or :HTTP/1.1.

SESSION-VALUE (SYMBOL &OPTIONAL (SESSION *SESSION*))

Returns the value associated with SYMBOL from the session object SESSION (the default is the current session) if it exists.

SSL-SESSION-ID (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'SSL_SESSION_ID' header (if sent by the front-end) as captured in the REQUEST object REQUEST.

START-SESSION

Returns the current SESSION object. If there is no current session, creates one and updates the corresponding data structures. In this case the function will also send a session cookie to the browser.

START-TBNL

Starts listening on port *TBNL-PORT* if needed. Initializes *SESSION-SECRET* if needed. Returns the newly created or already existing listener object.

STOP-TBNL

Stops the object bound to *LISTENER* if it exists.

URL-DECODE (STRING &OPTIONAL (EXTERNAL-FORMAT *TBNL-DEFAULT-EXTERNAL-FORMAT*))

Decode a url-encoded STRING which is assumed to be encoded using the external format EXTERNAL-FORMAT.

URL-ENCODE (STRING &OPTIONAL (EXTERNAL-FORMAT *TBNL-DEFAULT-EXTERNAL-FORMAT*))

URL-encodes a string using the external format EXTERNAL-FORMAT.

USER-AGENT (&OPTIONAL (REQUEST *REQUEST*))

Returns the 'User-Agent' incoming http header value captured in the REQUEST object REQUEST.

Undocumented

REQUIRE-AUTHORIZATION (&OPTIONAL (REALM TBNL))

Private

ADDRESS-STRING

Returns a string with information about TBNL and the front-end suitable for inclusion in HTML output.

COMPUTE-ARRAY-PARAMETER (PARAMETER-NAME TYPE PARAMETERS)

Retrieves all parameters from PARAMETERS which are named like "PARAMETER-NAME[N]" (where N is a non-negative integer), converts them to TYPE, and returns an array where the Nth element is the corresponding value.

COMPUTE-HASH-TABLE-PARAMETER (PARAMETER-NAME TYPE PARAMETERS KEY-TYPE TEST-FUNCTION)

Retrieves all parameters from PARAMETERS which are named like "PARAMETER-NAME{FOO}" (where FOO is any sequence of characters not containing curly brackets), converts them to TYPE, and returns a hash table with test function TEST-FUNCTION where the corresponding value is associated with the key FOO (converted to KEY-TYPE).

COMPUTE-LIST-PARAMETER (PARAMETER-NAME TYPE PARAMETERS)

Retrieves all parameters from PARAMETERS which are named PARAMETER-NAME, converts them to TYPE, and returns a list of them.

COMPUTE-PARAMETER (PARAMETER-NAME PARAMETER-TYPE REQUEST-TYPE)

Computes and returns the parameter(s) called PARAMETER-NAME and converts it/them according to the value of PARAMETER-TYPE. REQUEST-TYPE is one of :GET, :POST, or :BOTH.

COMPUTE-REAL-NAME (SYMBOL)

Computes the `real' paramater name (a string) from the Lisp symbol SYMBOL. Used in cases where no parameter name is provided.

COMPUTE-SIMPLE-PARAMETER (PARAMETER-NAME TYPE PARAMETER-READER)

Retrieves the parameter named PARAMETER-NAME using the reader PARAMETER-READER and converts it to TYPE.

CONVERT-PARAMETER (ARGUMENT TYPE)

Converts the string ARGUMENT to TYPE where TYPE is one of the symbols STRING, CHARACTERS, INTEGER, KEYWORD, or BOOLEAN - or otherwise a function designator for a function of one argument. ARGUMENT can also be NIL in which case this function also returns NIL unconditionally.

COUNT-SESSION-USAGE

Counts session usage globally and triggers session gc if necessary.

CREATE-RANDOM-STRING (&OPTIONAL (N 10) (BASE 16))

Returns a random number (as a string) with base BASE and N digits.

DEFAULT-HANDLER

The handler that is supposed to serve the request if no other handler is called.

ENCODE-SESSION-STRING (ID USER-AGENT REMOTE-ADDR START)

Create a uniquely encoded session string based on the values ID, USER-AGENT, REMOTE-ADDR, and START

FORM-URL-ENCODED-LIST-TO-ALIST (FORM-URL-ENCODED-LIST &OPTIONAL (EXTERNAL-FORMAT *TBNL-DEFAULT-EXTERNAL-FORMAT*))

Converts a list FORM-URL-ENCODED-LIST of name/value pairs into an alist. Both names and values are url-decoded while doing this.

GET-NEXT-SESSION-ID

Returns the next sequential session id.

GET-POST-DATA (&OPTIONAL (REQUEST *REQUEST*))

Reads the posted data from the stream and stores the raw contents in the corresponding slot of the REQUEST object.

GET-REQUEST-DATA

Reads incoming headers and posted content (if any) from the front-end or directly from the HTTP stream via *TBNL-STREAM*. Returns the results as an alist.

GET-STORED-SESSION (ID)

Returns the SESSION object corresponding to the number ID if the session has not expired. Will remove the session if it has expired but will not create a new one.

ISO-TIME (&OPTIONAL (TIME (GET-UNIVERSAL-TIME)))

Returns the universal time TIME as a string in full ISO format.

LISTEN-FOR-REQUEST (*TBNL-STREAM* COMMAND-PROCESSOR &REST ARGS)

Listens on *TBNL-STREAM* for an incoming request. Packages the command using GET-REQUEST-DATA and passes it to the COMMAND-PROCESSOR function (which is PROCESS-REQUEST). ARGS are ignored. Designed to be called by a KMRCL:LISTENER object.

MAKE-DEFUN-PARAMETER (DESCRIPTION DEFAULT-PARAMETER-TYPE DEFAULT-REQUEST-TYPE)

Creates a keyword parameter to be used by DEFINE-EASY-HANDLER. DESCRIPTION is one of the elements of DEFINE-EASY-HANDLER's LAMBDA-LIST and DEFAULT-PARAMETER-TYPE and DEFAULT-REQUEST-TYPE are the global default values.

MAYBE-INVOKE-DEBUGGER (CONDITION)

Invokes the debugger if *CATCH-ERRORS-P* is true.

MAYBE-REWRITE-URLS-FOR-SESSION (HTML &KEY (COOKIE-NAME *SESSION-COOKIE-NAME*) (VALUE (SESSION-COOKIE-VALUE)))

Rewrites the HTML page HTML such that the name/value pair COOKIE-NAME/COOKIE-VALUE is inserted if the client hasn't sent a cookie of the same name but only if *REWRITE-FOR-SESSION-URLS* is true. See the docs for URL-REWRITE:REWRITE-URLS.

MD5-HEX (STRING)

Calculates the md5 sum of the string STRING and returns it as a hex string.

MIME-TYPE (PATHSPEC)

Given a pathname designator PATHSPEC returns the MIME type (as a string) corresponding to the suffix of the file denoted by PATHSPEC (or NIL).

OCTETS-TO-STRING (OCTETS &OPTIONAL (EXTERNAL-FORMAT *TBNL-DEFAULT-EXTERNAL-FORMAT*))

Converts an array of type (UNSIGNED-BYTE 8) to a Lisp string using the external format EXTERNAL-FORMAT.

PARSE-RFC2388-FORM-DATA (STREAM CONTENT-TYPE-HEADER)

Create an alist of POST parameters from the stream STREAM which is supposed to be of content type 'multipart/form-data'.

PROCESS-REQUEST (COMMAND)

Processes COMMAND as created by GET-REQUEST-DATA using the corresponding user funtion from *DISPATCH-TABLE*. Sets up REPLY, REQUEST, and SESSION objects. Called by LISTEN-FOR-REQUEST.

QUOTE-STRING (STRING)

Quote string according to RFC 2616's definition of quoted-string

READ-HTTP-HEADERS

Reads and parses HTTP headers coming from *TBNL-STREAM* and converts them into an alist.

READ-HTTP-REQUEST (FIRST-LINE)

Reads incoming HTTP request from Araneida or directly from a browser via *TBNL-STREAM*. Assumes the first line is already consumed and in FIRST-LINE. Returns an alist of the headers.

REMOVE-SESSION (SESSION)

Completely removes the SESSION object SESSION from *SESSION-DATA*.

RESET-SESSION-SECRET

Sets *SESSION-SECRET* to a new random value. All old sessions will cease to be valid.

SCANNER-FOR-GET-PARAM (PARAM-NAME)

Returns a CL-PPCRE scanner which matches a GET parameter in a URL. Scanners are memoized in SCANNER-HASH once they are created.

SESSION-GC

Removes sessions from *session-data* which are too old - see SESSION-TOO-OLD-P.

SESSION-TOO-OLD-P (SESSION)

Returns true if the SESSION object SESSION has not been active in the last (SESSION-MAX-TIME SESSION) seconds.

SESSION-VERIFY (REQUEST)

Tries to get a session identifier from the cookies (or alternatively from the GET parameters) sent by the client. This identifier is then checked for validity against the REQUEST object REQUEST. On success the corresponding session object (if not too old) is returned (and updated). Otherwise NIL is returned.

START-OUTPUT (&OPTIONAL CONTENT)

Sends all headers and maybe the content body to *TBNL-STREAM*. Handles the supported return codes accordingly. Called by PROCESS-REQUEST. Returns the stream to write to.

STARTS-WITH-ONE-OF-P (SEQ SUBSEQ-LIST &KEY (TEST 'EQL))

Tests whether the sequence SEQ starts with one of the sequences in SUBSEQ-LIST.

STARTS-WITH-P (SEQ SUBSEQ &KEY (TEST 'EQL))

Tests whether the sequence SEQ starts with the sequence SUBSEQ.

STATUS-LINE (RETURN-CODE)

Returns a meaningful status line for the http return code RETURN-CODE (which should be an integer).

STRING-ASSOC (STRING A-LIST)

Returns an entry keyed by the string STRING from A-LIST. The search is case-insensitive.

STRING-ASSOC* (STRING A-LIST)

Returns an entry keyed by the string STRING from A-LIST. The search is case-sensitive.

STRING-TO-OCTETS (STRING &OPTIONAL (EXTERNAL-FORMAT *TBNL-DEFAULT-EXTERNAL-FORMAT*))

Converts a Lisp string to an array of type (UNSIGNED-BYTE 8) using the external format EXTERNAL-FORMAT.

STRINGIFY-SESSION (SESSION)

Creates a string representing the SESSION object SESSION. See ENCODE-SESSION-STRING.

TBNL-INFO-STRING

Provides parts of the version info depending on *USE-MODLISP-HEADERS* and the presence of :ARANEIDA in *FEATURES*. Can only be called when a request is handled.

WRITE-HEADER-LINE (KEY VALUE)

Accepts a KEY and a VALUE and writes them, one line at a time, to the mod_lisp or HTTP/Araneida socket stream.

WRITE-HEADER-LINE/HTTP (KEY VALUE)

Accepts a KEY and a VALUE and writes them, one line at a time, to the http/Araneida socket stream

WRITE-HEADER-LINE/MODLISP (KEY VALUE)

Accepts a KEY and a VALUE and writes them, one line at a time, to the mod_lisp socket stream

Undocumented

HYPERDOC-LOOKUP (SYMBOL TYPE)

MAKE-TMP-FILE-NAME (&OPTIONAL (PREFIX tbnl))

SOCKET-LOCAL-HOST

SOCKET-LOCAL-PORT

SOCKET-REMOTE-HOST

SOCKET-REMOTE-PORT

MACRO

Public

DEFINE-EASY-HANDLER (DESCRIPTION LAMBDA-LIST &BODY BODY)

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 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 NAME. 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. 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 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 TBNL. Specifically, all the parameter computations above will only happen if *REQUEST* is bound, i.e. if we're within a TBNL request. Otherwise, VAR will always be bound to the result of evaluating INIT-FORM unless a corresponding keyword argument is provided.

DO-SESSIONS ((VAR &OPTIONAL RESULT-FORM) &BODY BODY)

Executes BODY with VAR bound to each existing SESSION object consecutively. Returns the values returned by RESULT-FORM unless RETURN is executed. The scope of the binding of VAR does not include RESULT-FORM.

Private

DEBUG-VALUE (VAR EXPR)

Evaluates and returns EXPR but also sets VAR to its value if in debug mode.

DEFCONSTANT* (NAME VALUE &OPTIONAL DOC)

Make sure VALUE is evaluated only once (to appease SBCL).

DEFVAR-UNBOUND (NAME &OPTIONAL (DOC-STRING ))

Convenience macro to declare unbound special variables with a documentation string.

HANDLER-CASE* (EXPRESSION &REST CLAUSES)

Like HANDLER-CASE, but observes *CATCH-ERRORS-P*.

IGNORE-ERRORS* (&BODY BODY)

Like IGNORE-ERRORS, but observes *CATCH-ERRORS-P*.

WITH-DEBUGGER (&BODY BODY)

Executes BODY and invokes the debugger if an error is signaled and *CATCH-ERRORS-P* is NIL.

WITH-REBINDING (BINDINGS &BODY BODY)

Syntax: WITH-REBINDING ( { var | (var prefix) }* ) form* Evaluates a series of forms in the lexical environment that is formed by adding the binding of each VAR to a fresh, uninterned symbol, and the binding of that fresh, uninterned symbol to VAR's original value, i.e., its value in the current lexical environment. The uninterned symbol is created as if by a call to GENSYM with the string denoted by PREFIX - or, if PREFIX is not supplied, the string denoted by VAR - as argument. The forms are evaluated in order, and the values of all but the last are discarded (that is, the body is an implicit PROGN).

WITH-UNIQUE-NAMES ((&REST BINDINGS) &BODY BODY)

Syntax: WITH-UNIQUE-NAMES ( { var | (var x) }* ) declaration* form* Executes a series of forms with each VAR bound to a fresh, uninterned symbol. The uninterned symbol is as if returned by a call to GENSYM with the string denoted by X - or, if X is not supplied, the string denoted by VAR - as argument. The variable bindings created are lexical unless special declarations are specified. The scopes of the name bindings and declarations do not include the Xs. The forms are evaluated in order, and the values of all but the last are discarded (that is, the body is an implicit PROGN).

Undocumented

WITH-LOCK-HELD ((LOCK) &BODY BODY)

GENERIC-FUNCTION

Public

Undocumented

DISPATCH-REQUEST (DISPATCH-TABLE)

LOG-MESSAGE (LOG-LEVEL FMT &REST ARGS)

Private

Undocumented

SLOT-ACCESSOR

Public

SESSION-COUNTER (OBJECT)

The number of times this session has been used.

SESSION-MAX-TIME (OBJECT)

The time (in seconds) after which this session expires if it's not used.

SETFSESSION-MAX-TIME (NEW-VALUE OBJECT)

The time (in seconds) after which this session expires if it's not used.

SESSION-REMOTE-ADDR (OBJECT)

The remote IP address of the client when this sessions was started as returned by REAL-REMOTE-ADDR.

SESSION-STRING (OBJECT)

The session strings encodes enough data to safely retrieve this session. It is sent to the browser as a cookie value or as a GET parameter.

SESSION-USER-AGENT (OBJECT)

The incoming 'User-Agent' header that was sent when this session was created.

Private

AUX-DATA (OBJECT)

Used to keep a user-modifiable alist with arbitrary data during the request.

SETFAUX-DATA (NEW-VALUE OBJECT)

Used to keep a user-modifiable alist with arbitrary data during the request.

LOG-MESSAGES (OBJECT)

A list (in reverse chronological order) of the messages which are to be written to the Apache error log. This slot's value should only be modified by the functions defined in log.lisp.

SESSION (OBJECT)

The session object associated with this request.

SETFSESSION (NEW-VALUE OBJECT)

The session object associated with this request.

SESSION-DATA (OBJECT)

Data associated with this session - see SESSION-VALUE.

SESSION-ID (OBJECT)

The unique ID (an INTEGER) of the session.

SESSION-LAST-CLICK (OBJECT)

The last time this session was used.

SESSION-START (OBJECT)

The time this session was started.

VARIABLE

Public

*CATCH-ERRORS-P*

Whether TBNL should catch and log errors (or rather invoke the debugger).

*CONTENT-TYPES-FOR-URL-REWRITE*

The content types for which url-rewriting is OK. See *REWRITE-FOR-SESSION-URLS*.

*DEBUG-MODE*

Whether we're in debug mode.

*DEFAULT-CONTENT-TYPE*

The default content-type header which is returned to the client.

*DEFAULT-HANDLER*

The name of the function which is always returned by DEFAULT-DISPATCHER.

*DEFAULT-LOG-LEVEL*

The default log level for LOG-MESSAGE*

*DISPATCH-TABLE*

A list of dispatch functions - see function PROCESS-REQUEST.

*FILE-UPLOAD-HOOK*

If this is not NIL, it should be a unary function which will be called with a pathname for each file which is uploaded to TBNL. The pathname denotes the temporary file to which the uploaded file is written. The hook is called directly before the file is created.

*HTTP-ERROR-HANDLER*

Contains NIL (the default) or a function of one argument which is called if the content handler has set a return code other than +HTTP-OK+ or +HTTP-NOT-MODIFIED+.

*LISP-ERRORS-LOG-LEVEL*

Log level for Lisp errors.

*LISP-WARNINGS-LOG-LEVEL*

Log level for Lisp warnings.

*LOG-LISP-BACKTRACES-P*

Whether Lisp backtraces should be logged when an error occurs. Will only have effect of *LOG-LISP-ERRORS-P* or *LOG-LISP-BACKTRACES* are also true.

*LOG-LISP-ERRORS-P*

Whether Lisp errors should be logged.

*LOG-LISP-WARNINGS-P*

Whether Lisp warnings should be logged.

*LOG-PREFIX*

The prefix which is printed in front of Apache log messages. This should be a string or T (for "TBNL", the default) or NIL (meaning no prefix).

*REWRITE-FOR-SESSION-URLS*

Whether HTML pages should possibly be rewritten for cookie-less session-management.

*SESSION-MAX-TIME*

The default time (in seconds) after which a session times out.

*SESSION-REMOVAL-HOOK*

A function of one argument (a session object) which is called whenever a session is garbage-collected.

*SHOW-ACCESS-LOG-MESSAGES*

Whether routine messages about each request should be logged. This will only be done if *USE-APACHE-LOG* is NIL.

*SHOW-LISP-BACKTRACES-P*

Whether Lisp backtraces should be shown in HTML output when an error occurs. Will only have effect of *SHOW-LISP-ERRORS-P* is also true.

*SHOW-LISP-ERRORS-P*

Whether Lisp errors should be shown in HTML output.

*TBNL-PORT*

The port TBNL is listening on.

*TMP-DIRECTORY*

Directory for temporary files created by MAKE-TMP-FILE-NAME.

*USE-APACHE-LOG*

Whether log messages should be sent as headers (assuming that mod_lisp hands them over to Apache).

*USE-REMOTE-ADDR-FOR-SESSIONS*

Whether the client's remote IP (as returned by REAL-REMOTE-ADDR) should be encoded into the session string. If this value is true a session will cease to be accessible if the client's remote IP changes. This might for example be an issue if the client uses a proxy server which doesn't send correct 'X_FORWARDED_FOR' headers.

*USE-USER-AGENT-FOR-SESSIONS*

Whether the 'User-Agent' header should be encoded into the session string. If this value is true a session will cease to be accessible if the client sends a different 'User-Agent' header.

Undocumented

*TBNL-DEFAULT-EXTERNAL-FORMAT*

Private

*CLOSE-TBNL-STREAM*

Set this to T if you want to close the TBNL socket each time a request has been handled.

*HEADERS-SENT*

Used internally to check whether the reply headers have already been sent for this request.

*LOG-FILE*

The log file to use if *USE-APACHE-LOG* is false.

*LOG-FILE-LOCK*

A lock to prevent two threads from writing to the log file at same time.

*LOG-FILE-STREAM*

The stream corresponding to the log file.

*MIME-TYPE-HASH*

A hash table which maps file suffixes to MIME types.

*MIME-TYPE-LIST*

An alist where the cars are MIME types and the cdrs are list of file suffixes for the corresponding type.

*SESSION-DATA*

All sessions of all users currently using TBNL. An alist where the car is the session's ID and the cdr is the SESSION object itself.

*SESSION-DATA-LOCK*

A lock to prevent two threads from modifying *SESSION-DATA* at the same time.

*SESSION-GC-FREQUENCY*

A session GC (see function SESSION-GC) will happen every *SESSION-GC-FREQUENCY* requests (counting only requests which use a session).

*TBNL-SOCKET-USAGE-COUNTER*

The number of requests serviced with the current socket.

*TBNL-VERSION*

A string denoting the current version of TBNL. Used for diagnostic output.

*THE-RANDOM-STATE*

A fresh random state.

*TMP-FILES*

A list of temporary files created while a request was handled.

*USE-MODLISP-HEADERS*

If this variable is true then outgoing headers are written in a format mod_lisp can understand, otherwise they're written like plain HTTP headers.

Undocumented

*EASY-HANDLER-ALIST*

*HYPERDOC-BASE-URI*

CLASS

Private

REPLY

Objects of this class hold all the information about an outgoing reply. They are created automatically by TBNL and can be accessed and modified by the corresponding handler.

REQUEST

Objects of this class hold all the information about an incoming request. They are created automatically by TBNL and can be accessed by the corresponding handler.

SESSION (OBJECT)

SESSION objects are automatically maintained by TBNL. They should not be created explicitely with MAKE-INSTANCE but implicitely with START-SESSION. Note that SESSION objects can only be created when the special variable *REQUEST* is bound to a REQUEST object.

CONSTANT

Public

Undocumented

+HTTP-ACCEPTED+

+HTTP-AUTHORIZATION-REQUIRED+

+HTTP-BAD-GATEWAY+

+HTTP-BAD-REQUEST+

+HTTP-CONFLICT+

+HTTP-CONTINUE+

+HTTP-CREATED+

+HTTP-EXPECTATION-FAILED+

+HTTP-FORBIDDEN+

+HTTP-GATEWAY-TIME-OUT+

+HTTP-GONE+

+HTTP-INTERNAL-SERVER-ERROR+

+HTTP-LENGTH-REQUIRED+

+HTTP-METHOD-NOT-ALLOWED+

+HTTP-MOVED-PERMANENTLY+

+HTTP-MOVED-TEMPORARILY+

+HTTP-MULTIPLE-CHOICES+

+HTTP-NO-CONTENT+

+HTTP-NON-AUTHORITATIVE-INFORMATION+

+HTTP-NOT-ACCEPTABLE+

+HTTP-NOT-FOUND+

+HTTP-NOT-IMPLEMENTED+

+HTTP-NOT-MODIFIED+

+HTTP-OK+

+HTTP-PARTIAL-CONTENT+

+HTTP-PAYMENT-REQUIRED+

+HTTP-PRECONDITION-FAILED+

+HTTP-PROXY-AUTHENTICATION-REQUIRED+

+HTTP-REQUEST-ENTITY-TOO-LARGE+

+HTTP-REQUEST-TIME-OUT+

+HTTP-REQUEST-URI-TOO-LARGE+

+HTTP-REQUESTED-RANGE-NOT-SATISFIABLE+

+HTTP-RESET-CONTENT+

+HTTP-SEE-OTHER+

+HTTP-SERVICE-UNAVAILABLE+

+HTTP-SWITCHING-PROTOCOLS+

+HTTP-TEMPORARY-REDIRECT+

+HTTP-UNSUPPORTED-MEDIA-TYPE+

+HTTP-USE-PROXY+

+HTTP-VERSION-NOT-SUPPORTED+

+LATIN-1+

+UTF-8+

Private

+BUFFER-LENGTH+

Length of buffers used for internal purposes.

+DAY-NAMES+

The three-character names of the seven days of the week - needed for cookie date format.

+MONTH-NAMES+

The three-character names of the twelve months - needed for cookie date format.

Undocumented