web.lsp

Module index

Module: Web

Author: Jeff Ober
Version: 0.3.1 beta
Original location: http://static.artfulcode.net/newlisp/web.lsp
Source: web.lsp
Package definition: web.qwerty

A collection of functions for writing web-based software.

Features:

• ASP/PHP-style templates
• Cookies
• Entities translation
• GET/POST parameters
• HTTP header control
• Sessions
• URL building and parsing
• URL encoding and decoding
• query building and parsing

Known issues

• When used in conjunction with the official CGI module, CGI must be loaded first. In the case of identical GET and POST parameters, the value is stored in GET, but the value will be POST. This is due to the fact that CGI stores both GET and POST in the same association list and overwrites GET values with POST.

Note: for JSON encoding and decoding, see the Json module.

To do

• add MIME decoding for multipart posts

Version history

0.3.1 • fixed ineffective usage of set/setf

0.3 • made parse-query more tolerant and fixed parsing bug • cookie now accepts an additional parameter that only permits access during HTTPS sessions

0.2 • build-url now accepts query strings in addition to assoc lists • session-id now accepts an optional parameter to set the session id • fixed some typos with clean-sessions • fixed extra parameter in define-session-handlers

0.1 • initial release



- § -

Web:escape-js

syntax: (Web:escape-js str)
parameter: str - a string to escape

Escapes a string for output in javascript. Does not encode entities; just prevents control characters from causing syntax errors in javascript.

- § -

Web:escape

syntax: (Web:escape str)
parameter: str - a string to escape

return: the escaped string

Escapes characters that are part of the (X)HTML and XML syntax to prevent characters from confusing browsers' parsing of markup. Escapes single and double quotes, ampersands, and left and right angle brackets (", ', &, <, and >).

- § -

Web:unescape

syntax: (Web:unescape str)
parameter: str - an entity-escaped string

return: the unescaped string

Unescapes the basic (X)HTML and XML character entities in a string.

- § -

Web:encode-entities

syntax: (Web:encode-entities str)
parameter: str - a string to escape

return: the escaped string

Escapes characters with a much larger set of character entities than escape using a table derived from Wikipedia.

- § -

Web:decode-entities

syntax: (Web:decode-entities str)
parameter: str - an entity-encoded string

return: the decoded string

Translates character entities to their character equivalents as well as numeric entities.

- § -

Web:url-encode

syntax: (Web:url-encode str)
parameter: str - a string token to encode for use in a URL

return: the URL-encoded string

Encodes a string for use in a URL.

- § -

Web:url-decode

syntax: (Web:url-decode str)
parameter: str - a URL-encoded string

return: the decoded string

Decodes hexidecimals and spaces (represented as '+') in a URL-encoded string.

- § -

Web:parse-query

syntax: (Web:parse-query query-string)
parameter: query-string - a URL-encoded query string

return: an association list of decoded key-value pairs

Parses a URL-encoded query string and returns a list of key-values pairs.

- § -

Web:build-query

syntax: (Web:build-query a-list)
parameter: a-list - an association list

return: a URL-encoded query string

Builds a URL-encoded query string using a-list. Does not include the leading question mark (so queries may be easily built of association list fragments.)

- § -

Web:parse-url

syntax: (Web:parse-url str-url)
parameter: str-url - a URL

return: an association list with the decomposed URL's parts

Parses a URL and returns an association list of its decomposed parts. The list's keys (as strings) are: scheme, user, pass, host, port, path, query, and fragment. Also handles IPV6 addresses. Modeled on the PHP function of the same name.

Parsing based on code from this comment.

- § -

Web:build-url

syntax: (Web:build-url str-url [list-query-params ...])
parameter: str-url - a string URL
parameter: list-query-params - one or more association lists of query parameters and their values


syntax: (Web:build-url list-url [list-query-params ...])
parameter: list-url - an association list of URL components using the structure of parse-url's return value
parameter: list-query-params - one or more association lists of query parameters and their values

return: a URL string composed of the initial URL data plus subsequently superseding query parameters

In the first syntax, builds a URL from an existing URL string. In the second syntax, builds a URL from an association list in the same format as the return value of parse-url, with both keys and values being strings. In both syntaxes, any number of additional association lists of key/value pairs may be passed, which are serialized as query parameters, with each list overriding the previous. If there are query parameters in the initial URL, they are used as the initial list with the lowest priority.

- § -

Web:header

syntax: (Web:header str-key str-value)
parameter: str-key - the header name (e.g., "Content-type")
parameter: str-value - the header value (e.g., "text/html")

Sets an HTTP output header. Headers are printed using Web:send-headers.

- § -

Web:redir

syntax: (Web:redir str-url)
parameter: str-url - a URL string

Redirects the client to str-url.

- § -

Web:send-headers

syntax: (Web:send-headers)

Writes the HTTP headers to stdout. This function should be called regardless of whether any headers have been manually set to ensure that the minimum HTTP headers are properly sent. Note: no check is made to verify that output has not already begun.

- § -

Web:cookie

syntax: (Web:cookie str-key)
parameter: str-key - the cookie's name


syntax: (Web:cookie str-key str-value [int-expires [str-path [str-domain [bool-http-only [bool-secure-only]]]])
parameter: str-key - the cookie's name
parameter: str-key - the cookie's value
parameter: int-expires - (optional) the expiration date of the cookie as a unix timestamp; default is a session cookie
parameter: str-path - (optional) the cookie's path; default is the current path
parameter: str-domain - (optional) the cookie's domain; default is the current host
parameter: bool-http-only - (optional) whether the cookie may be read by client-side scripts
parameter: bool-secure-only - (optional) whether the cookie may be accessed/set outside of HTTPS

In the first syntax, cookie returns the value of the cookie named str-key or nil. If str-key is not provided, an association list of all cookie values is returned.

In the second syntax, cookie sets a new cookie or overwrites an existing cookie in the client's browser. Note that bool-http-only defaults to true, but is not standard and therefore is not necessarily implemented in all browsers. bool-secure-only defaults to nil. Cookies use the header function and must be sent before calling send-headers.

- § -

Web:get

syntax: (Web:get str-key)

Returns the value of str-key in the query string or nil if not present. If str-key is not provided, returns an association list of all GET values.

- § -

Web:post

syntax: (Web:post str-key)

Returns the value of str-key in the client-submitted POST data or nil if not present. If str-key is not provided, returns an association list of all POST values.

- § -

Web:define-session-handlers

syntax: (Web:define-session-handlers fn-open fn-close fn-delete fn-clear fn-clean)
parameter: fn-open - function to begin a new session
parameter: fn-close - function to close a session, saving changes
parameter: fn-delete - function to delete a session
parameter: fn-clean - function to prune old sessions

Defines handler functions to be called when various session control functions are used, making custom session storage a fairly simple matter.

The required handler functions are:

• fn-open: called by open-session; resumes or starts a new session storage instance, initializing the context tree
• fn-close: called by close-session; writes changes to a session to storage
• fn-delete: called by delete-session; deletes the entire session from storage
• fn-clean: called by clean-sessions; prunes old stored sessions

Some useful functions and variables for handler functions:

• session-id: function that returns the current session id and sets the session cookie when necessary
• session-context: function that returns the session context dictionary
• SESSION_MAX_AGE: a variable storing the number of seconds after which an orphan session should be deleted

- § -

Web:session-id

syntax: (Web:session-id [str-sid])
parameter: str-sid - (optional) the session ID to use

return: a unique session id for the client

Creates or retrieves the client's session id. If this is a new session id, a cookie is set in the client's browser to identify it on future loads.

If str-sid is provided, it will be used as the new session ID.

- § -

Web:session-context

syntax: (Web:session-context)

return: a symbol pointing to the current session's context dictionary

Run-time session data is stored in a context tree. session-context returns the current session tree or creates a new one when necessary. This function is primarily intended for session handlers' use; it is typically more useful to call session on its own to retrieve an association list of key/value pairs in an application.

- § -

Web:open-session

syntax: (Web:open-session)

Initializes the client's session.

- § -

close-session

syntax: (close-session)

Writes any changes to the session to file. This is automatically called when the distribution function exit is called.

- § -

delete-session

syntax: (delete-session)

Deletes the session. Sessions are then turned off and open-session must be called again to use sessions further.

- § -

clear-session

syntax: (clear-session)

Clears all session variables.

- § -

clean-sessions

syntax: (clean-sessions)

Cleans old session files. This function is not currently called automatically; note that there is the possibility of a race condition with this function and other session handling functions.

- § -

session

syntax: (session [str-key [str-value]])
parameter: str-key - the session key
parameter: str-value - the new value
When called with both str-key and str-value, sets the session variable. When called with only str-key, returns the value of str-key. Otherwise, returns an association list of session variables. Returns nil if the session is not opened.

- § -

Web:eval-template

syntax: (Web:eval-template str-template ctx-context)
parameter: str-template - a string containing the template syntax
parameter: ctx-context - the context in which to evaluate the template

Translates a template using ASP-like tags, creating small islands of newLISP code in an HTML (or other) document. This is similar to the distribution CGI module's put-page function, except that the short-cut <%= foo %> is used to simply output the value of foo and tags may span multiple lines.

Note that the opening and closing tags may be changed by setting the values of Web:OPEN_TAG and Web:CLOSE_TAG if desired. The shortcut print tag will be Web:OPEN_TAG + '='.

example:

 (Web:eval-template "<p><%= (* 3 3) %></p>")
 => "<p>9</p>"
 (Web:eval-template "<p><% (println (* 3 3)) %></p>")
 => "<p>9</p>"

- ∂ -

Artful Code

generated with newLISP  and newLISPdoc