Common Lisp Package: HH-WEB

README:

About HH-Web#

HH-Web is the beginnings of a web application framework written in Lisp designed to streamline development of modern web applications.

See the LICENSE file for the license covering all code within the HH-Web directory and any subdirectories.
Basically, it's the MIT license, so you are free to do what you want, provided you reproduce the original copyright.

Platforms##

The primary platform for HH-Web development is SBCL x64 on Mac OS X Lion (latest SBCL rev tested is 1.0.57); other Common Lisp implementations that appear to work correctly are CCL 1.8 x86, LispWorks 6.01, and ABCL 1.0.1. HH-Web has also been tested with SBCL 1.0.57 x64 on Ubuntu 11.04.

Platforms with known issues include CCL x64 (problem with threads) and CMUCL (which does not like named-readtables).

Features##

In its present form (as of June 2012), there are 4 principal features in HH-Web:

  • Composable widgets: HH-Web let's the developer write a web page using conventional Lisp s-expression syntax, complete with properly generated CSS & Javascript. More importantly, commonly used fragments of HTML/CSS/Javascript can be bundled as a tag (just like HTML tags such as p, div, h1, etc.), and the corresponding HTML/CSS/Javascript for the expected fragment will be generated instead. Using custom tags means that most of the development of a new site involves identifying the common elements that make up the site's pages, creating custom tags (with parameters or "attributes", when necessary) as needed, and then authoring the pages as templates using both HTML tags and the site-specific custom tags.

  • Regex-based URL dispatching: Inspired by Django's (and Rails') use of regex dispatching, HH-Web implements a similar technique, but in Lisp. Most importantly, if the regex contains "variables" (e.g., named registers, in regex parlance), then symbols will be interned for those variables and exposed as parameters to the URL's handler. Thus, components of an URL's path will automatically be extracted and made available as arguments to the handling code.

  • Dynamic code reloading: HH-Web automatically monitors specific files for new URL dispatching rules, page template changes, and all taglibraries. Changes in the underlying code is by default automatically reflected the next time the page is refreshed in the browser. The intent is to provide the equivalent usability of other web authoring environments such as PHP or ASP: change the code for a page, and reflect that immediately in the browser.

  • Integrated caching: HH-Web's support for caching is evolving, but in its current form it permits marking caching guidelines for specific URLs. Specifically, caching causes HH-Web to preseve any generated content (from templates and tags, typically) in an in-memory cache for later use. If a request for a page in its map appear again, then HH-Web will serve the content from the cache, rather than invoking code to regenerate the content fresh.

Getting Started##

As an aide to starting new projects that use HH-Web to structure web application development, you can load the HH-Web system into the REPL using Quicklisp (included as of 7/3/2012--thanks Zach!):

(ql:quickload :hh-web) 

then execute the following expression:

(hh-web:make-skeleton :for :acme :in #p"~/lisp/") 

Substitute your own project name for acme in the above expression. Note that the argument to the :for keyword must be a symbol or string, and the argument to the :in keyword must be a directory path (e.g., it must end in "/"), although that directory should not exist, make-skeleton will not overwrite any files or directories that already present--it will raise an error instead. In the above example, the package for your new application will appear as a subdirectory of the one you provided, thus it will appear in ~/lisp/acme/.

If you use Quicklisp and the "~/lisp/" directory is registered with ASDF as a source directory, then you can then run the following at your REPL to start your newly-created web application:

(ql:quickload :acme)  
(acme:start-httpd-server) 

Now just point your browser at http://localhost:8000, and you should see a boilerplate homepage.

You can stop your application at any time by running the following:

(acme:stop-httpd-server) 

Additionally, the generated skeleton of a project also creates a single script called quickrun.lisp that lets you load and run your site in one step. For example, with SBCL:

sbcl --load ~/lisp/acme/quickrun.lisp 

Here's the directory structure created for your project:

/acme  
  |  
  +-- acme.asd			# system declaration  
  +-- locales				# directory containing files to support i18n and l10n  
  +-- logs.lisp			# helpers for logging using log5  
  +-- package.lisp		# package declaration  
  +-- quickrun.lisp	# script for loading and running the site  
  +-- server.lisp		# runs your site with hunchentoot  
  +-- taglibraries		# directory for your tag libraries  
  +-- templates			# directory for your templates  
  +-- templates.lisp	# file for declaring which templates to use  
  +-- urls.lisp			# file containing the regex rules for dispatching requests 

To develop your site, edit the following files as needed, and refresh your browser to see changes take effect immediately:

  • urls.lisp for your request dispatch rules
  • templates.lisp for the declaring what templates you wish to use
  • any file in the taglibraries folder for designing your tag or widget libraries
  • any file in the templates folder for creating your own page templates

Learning More

For more information on how HH-Web works and how to make use of it for your application, see the documentation on the wiki.

FUNCTION

Public

+TAG-LIBRARY (LIBRARY-NAME)

Find the tag-library (if possible), and import it into the current package (e.g., found by looking at *package* in dynamic environment

CREATE-FILE-CACHE-DISPATCHER-AND-HANDLER-FOR-ROOT (ROOT &KEY (URI /) (POPULATE NIL) (STATIC NIL))

Return a dispatcher suitable for use with Hunchentoot, dispatching URLs

CREATE-PACKAGE-FOLDER-DISPATCHER-AND-HANDLER (URI PACKAGE-NAME)

Create a dispatcher for all files inside a www subfolder of a package's directory

LOAD-TEMPLATES (&OPTIONAL (*TEMPLATE-PROVIDER-REGISTRY* *TEMPLATE-PROVIDER-REGISTRY*))

Refresh the list of templates, if necessary

LOCAL-TAG-LIBRARY-PROVIDER-REGISTRY-SYMBOL

Returns a symbol in the current package for storing the tag library provider registry expected by the package

LOCAL-TEMPLATE-PROVIDER-REGISTRY-SYMBOL

Returns a symbol in the current package for storing the template provider registry expected by the package

LOCALE-SERVICE (&OPTIONAL (*REQUEST* *REQUEST*))

Service for editing locales usable by the application

LOG-HTTP-ACCESS (&KEY RETURN-CODE CONTENT CONTENT-LENGTH)

Sends a standardized access log message to the access log with information about the current request and response.

LOG-HTTP-MESSAGE (LOG-LEVEL FORMAT-STRING &REST FORMAT-ARGUMENTS)

Sends a formatted message to the file http message log. FORMAT and ARGS are as in FORMAT. LOG-LEVEL is a keyword denoting the log level or NIL in which case it is ignored.

MAKE-FS-CACHE (ROOT &KEY (POPULATE NIL) (STATIC NIL))

Create a cache with the indicated root, and if populate is non-nil, preload the cache with all files underneath the root

MAKE-PACKAGE-FS-CACHE (PACKAGE &KEY (POPULATE NIL) (STATIC NIL))

Create a filesystem cache for the www subdirectory of a package

MAKE-SKELETON (&KEY FOR IN)

Generate a skeleton for a package in the indicated location;

META-SERVICE-REQUEST-P (&OPTIONAL (*REQUEST* *REQUEST*))

If there is a _meta parameter present, then regard the request as a 'meta' request by returning t; otherwise return nil

USE-TAG-LIBRARY (LIBRARY-NAME)

Add the named tag library to the list of libraries used by the active tag library

Undocumented

CREATE-ASDF-SYSTEM-TAG-LIBRARY-PROVIDER (SYSTEM &KEY ((FOLDER *PACKAGE-TAG-LIBRARY-FOLDER*) *PACKAGE-TAG-LIBRARY-FOLDER*))

CREATE-ASDF-SYSTEM-TEMPLATE-PROVIDER (SYSTEM &KEY ((FOLDER FOLDER) *PACKAGE-TEMPLATE-FOLDER*))

CREATE-FILE-CACHE-DISPATCHER-AND-HANDLER (CACHE &OPTIONAL (URI /))

CREATE-FOLDER-TAG-LIBRARY-PROVIDER (FOLDER)

CREATE-FOLDER-TEMPLATE-PROVIDER (FOLDER)

CREATE-PACKAGE-FILE-CACHE-DISPATCHER-AND-HANDLER (PACKAGE &KEY (URI /) (POPULATE NIL) (STATIC NIL))

DISPATCH-URL-CACHE (*REQUEST*)

FLUSH-URL-CATEGORY (CATEGORY)

GET-AVAILABLE-LOCALES (&OPTIONAL (*LOCALES* *LOCALES*))

GET-LOCALIZABLE-STRING-NOTES (STRING)

GET-LOCALIZABLE-STRINGS (&OPTIONAL (*LOCALE* *LOCALE*))

GET-LOCALIZATION-CONTEXTS (LITERAL-STRING)

GET-PACKAGE-FONT (PACKAGE FONT)

GET-STRING-LOCALIZATION (STRING LOCALE-NAME)

GET-STRING-LOCALIZATION-NOTES (STRING LOCALE-NAME)

GETTEXT (LITERAL-STRING &OPTIONAL (*LOCALE* *LOCALE*))

HTTP-DELETE-P (&OPTIONAL (*REQUEST* *REQUEST*))

HTTP-GET-P (&OPTIONAL (*REQUEST* *REQUEST*))

HTTP-POST-P (&OPTIONAL (*REQUEST* *REQUEST*))

HTTP-PUT-P (&OPTIONAL (*REQUEST* *REQUEST*))

INIT-LOCALIZATION (LOCALE-PACKAGE DEVELOPMENT-LOCALE-NAME)

SET-LOCALE (LOCALE-NAME)

Private

ADD-LOCALIZATION-CONTEXT (LOCALIZABLE-STRING &OPTIONAL (*LOCALIZATION-CONTEXT* *LOCALIZATION-CONTEXT*))

Captures the context in which the string appears, if a relevant context is available

BYTES-TO-STRING (SOME-BYTES)

Borrowed from Arnesi (http://common-lisp.net/project/bese/arnesi.html)

CACHEABLE-REQUEST-P (*REQUEST*)

If a request has any query parameters, it's not cachable

DEFAULT-TAG-ATTRIBUTES

Return a list of default attributes common to all tags

DETOKENIZE (ELEMENTS TOKEN &OPTIONAL (PREFIX ))

Combine elements into a string, separating each element by token

FIND-TAG-DEFINITION (TAG-SYMBOL)

Given the symbol for a tag definition, locate that definition in any available tag library

FLUSH-TAG-LIBRARY (LIBRARY-NAME CACHED-LIBRARY)

Safely a cached library, typically for reloading

FLUSH-TEMPLATE (TEMPLATE-PATH CACHED-TEMPLATE)

Safely a cached template, typically for reloading

GENERATE-LONG-UUID-STRING (SIZE)

Utility function for generating long strings of random data, such as for nonces, salts, and session cookies

HANDLE-CACHED-FILE (CACHED-FILE)

Given a cached file, return the contents of the file in a hunchentoot reply

LOAD-TEMPLATE-DEFINITION (*TEMPLATE* TEMPLATE-PATH &OPTIONAL (*TEMPLATE-PROVIDER-REGISTRY* *TEMPLATE-PROVIDER-REGISTRY*))

Load the indicated template definition from the first provider that can

LOAD-URLS

Refresh the list of URL dispatchers, if necessary

PROCESS-DIRECTIVE (EXPR)

Useful for pre-processing specific expressions as directives inside a template; returns nil if the expression is *not* a directive--returns t if the expr should be regarded as a directive and discarded

PS-SERVICE-METHOD-PARAMETER-LIST (PARAMETER-LIST)

Helper for processing service parameter lists during script generation

SELECT (SOME-LIST A-TEST)

Return a list containing only those elements from some list for which a-test is true

STRING-STARTS-WITH (TARGET-STRING SEARCH-STRING)

Return T if target-string starts with search-string, nil otherwise

STRING-TO-BYTES (A-STRING &KEY (PAD-TO 1))

Borrowed from Arnesi (http://common-lisp.net/project/bese/arnesi.html)

TOKENIZE (TOKEN-STRING TOKEN &OPTIONAL (START-POS 0))

Break a token-string into a list, where each element is separated in the original token-string by token

URL-PATTERN-PARAMETERS (*REQUEST* PATTERN)

Returns 3 values: a list of parameter name, a list of parameter values, and either t or nil to indicate that a match was successful

Undocumented

ADD-LOCALIZABLE-STRING (LITERAL-STRING &OPTIONAL (*LOCALE* *LOCALE*))

ADD-STRING-LOCALIZATION (NAME LOCALIZATION NOTES &OPTIONAL (*LOCALE* *LOCALE*))

CONTENT-FOR-USER-AGENT (CACHED-ITEM)

CREATE-PACKAGE-LOCALE (LOCALE-PACKAGE LOCALE-NAME)

DELETE-PACKAGE-LOCALE (LOCALE-PACKAGE LOCALE-NAME)

DETECT-USER-AGENTS (&OPTIONAL (*REQUEST* *REQUEST*))

DOC-INDEX

FIND-ALL-TAG-ATTRIBUTES (TAG-ATTRIBUTES BASES)

FIND-CACHED-TAG-LIBRARY (LIBRARY-NAME)

FIND-CACHED-TEMPLATE (TEMPLATE-PATH)

FIND-NEXT-TAG-METHOD (DEFINITION METHOD-NAME &OPTIONAL (VISITED-DEFINITIONS NIL))

FIND-TAG-ATTRIBUTES (TAG-SYMBOL)

FIND-TAG-METHOD (DEFINITION METHOD-NAME &OPTIONAL (VISITED-DEFINITIONS NIL))

GENERATE-BASE32-UUID-STRING

GENERATE-PACKAGE-DOCUMENTATION

GENERATE-SKELETON-FILE (SKELETON PATH CONTENT)

GET-PACKAGE-LOCALE-DIRECTORY (PACKAGE LOCALE)

GET-PACKAGE-LOCALES-DIRECTORY (PACKAGE)

GET-PACKAGE-STRING-LOCALIZATION-FILE (PACKAGE LOCALE)

HANDLE-CACHED-ITEM (CACHED-ITEM)

HASH-CONTENTS (SOME-HASH)

IMPORT-TAG-LIBRARY (LIBRARY-NAME)

LOAD-AVAILABLE-PACKAGE-LOCALES (PACKAGE)

LOAD-STRING-LOCALIZATIONS (PACKAGE LOCALE)

MAKE-URL-PATTERN (PATTERN DISPATCH-TEST HANDLER CATEGORIES EXPIRY)

MAKE-URL-PATTERN-FUNCTION-FORM (PARAMETER-NAMES PARAMETER-VALUES EXTRAS BODY)

NEXT-LOG-FILE-NAME (LOG-FILE-NAME MAX)

NUMBERED-FILE-NAME (FILE-NAME NUMBER)

PS-SERVICE-METHOD-CLIENT-SCRIPT (METHOD-NAME SERVICE-ARGS PARAMETERS HTTP-METHOD)

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

SAVE-STRING-LOCALIZATIONS (PACKAGE LOCALE)

SEPARATE-INITIALIZER-AND-BODY (RAW-BODY)

SET-TAG-READER

TAG-INDENTATION-STRING

URL-PATTERN-PARAMETER-NAMES (NAMED-REGISTERS)

URL-PATTERN-PARAMETER-VALUES (PATH NAMED-REGISTERS STARTS ENDS &OPTIONAL (PARAMETER-INDEX 0))

UUID-STRING

MACRO

Public

_ (LITERAL-STRING)

Should record literal string for reference within the i18n subsystem, and by default return the appropriate string for the current locale

CREATE-WEB-SERVER ((&REST INITIALIZATION-ARGS) &KEY (FOLDERS NIL) (PACKAGES NIL) (DISPATCHERS NIL))

Create a web server, using the provided initialization arguments for constructing the acceptor. The acceptor class used internally inherits from hunchentoot's easy-acceptor, so initialization arguments valid for that class are also valid here as well. In addition to initialization arguments, the following keywords are understood: * folders : a list of pairs URL -> path mappings, where each points to a filesystem folder for static files * packages : a list of of pairs of URL -> package mappings, where packages should have a www/ subfolder containing static files * dispatchers: list of additional hunchentoot dispatchers to use, if the server cannot otherwise find a handler for a request after attempting to locate a handler based on provided URL routes

DEFENTITY (NAME TEXT &OPTIONAL DOCUMENTATION)

Defines an entity usable in HTML

DEFHTMLTAG (NAME &KEY ((TAG TAG) NIL) ((BASES BASES) NIL) ((ATTRIBUTES ATTRIBUTES) NIL) ((INIT INIT) NIL) ((HASBODY HASBODY) T) ((NOENDTAG NOENDTAG) NIL) ((CONTENT CONTENT) NIL) ((SCRIPT SCRIPT) NIL) ((READY READY) NIL) ((STYLE STYLE) NIL) ((STYLE-SHEETS STYLE-SHEETS) NIL) ((SCRIPT-LIBRARIES SCRIPT-LIBRARIES) NIL))

Define a new tag renderable as HTML.

DEFSERVICE (NAME (&KEY ((DOCUMENTATION DOCUMENTATION) NIL) ((ARGS SERVICE-ARGS) NIL)) &REST METHODS)

Defines a service with the specified name, optional documentation, optional args and keyword args (typically extracted from the URL associated with the service), and a set of methods. If present, args appear as the parameter lists of methods in client script and are used to construct the path of the request. The intent is to enable passing of args from the client through the URL and also to have named registers from the pattern registered for the service available as well

HOUT (FORMAT-STRING &REST ARGS)

Macro to simplify writing out html to correct stream

HTML (&REST BODY)

Interpret the body as html markup, return multiple values, the first of which is an HTML string. The full list of return values is: $(ul (li "The intended title of the page containing this HTML fragment") (li "Link elements that should appear in the head of the page containing this fragment") (li "Style sheets required by the HTML fragment") (li "Script libraries required by the HTML fragment") (li "Sections of Javascript code required by the HTML fragment") (li "Sections of Javascript code to be run on page initialization that are required by the HTML fragment") ) Any of these values may be null (including the fragment itself). Care should be taken when nesting calls to this macro, as inline expansion of $$ characters will occur in each invocation of it, and unexpected results may occur.

IMAGE ((&KEY WIDTH HEIGHT) &REST BODY)

Captures calls to vecto to generate an image

IN-TAG-LIBRARY (LIBRARY-NAME)

All following tag definitions will go into this named library

PAGE (&REST RAW-BODY)

Interpret the raw body as html markup, and return a complete HTML page. In combination with $(a {:href "_macro_html"} "html"), this macro weaves the output of calls to $(em "html") into a complete page, with styles, scripts, references to script libraries, a page title, etc., all arranged in the appropriate order.

RESET-URLS

Clear out list of dispatchers; useful to ensures that stale patterns do not survive reload

WITH-HTTP-PARAMETERS ((&REST PARAMETER-LIST) &REST BODY)

Execute body with the values of provided parameters in indicated variables. The parameter-list should be a list of variable/parameter combinations, where each combination in the list is of the form (variable parameter). The parameter name should be a string, the variable should be a symbol referenced in the body.

Undocumented

+TITLE (EXPR)

DEFCOOKIE (NAME KEY VAR EXPIRY-PERIOD &OPTIONAL (EXPORT NIL))

DEFLOCALE ((LOCALE) &REST RESOURCES)

DEFSERVICE-CLIENT (SERVICE-NAME)

DEFSERVICE-HANDLER (SERVICE-NAME &REST METHOD-HANDLERS)

DEFTEMPLATE (NAME PATH &KEY ((ARGS TEMPLATE-ARGS) NIL))

DEFTEMPLATES (&KEY ((TAG-LIBRARY-PACKAGES TAG-LIBRARY-PACKAGES) NIL) ((TEMPLATE-PACKAGES TEMPLATE-PACKAGES) NIL) ((TEMPLATES TEMPLATES) NIL) ((TEMPLATE-FOLDER DEFAULT-TEMPLATE-FOLDER) '*PACKAGE-TEMPLATE-FOLDER*) ((TAG-LIBRARY-FOLDER DEFAULT-TAG-LIBRARY-FOLDER) '*PACKAGE-TAG-LIBRARY-FOLDER*))

DEFURL (PATTERN &KEY ((IF DISPATCH-TEST) T) ((HANDLER HANDLER) NIL) ((CATEGORIES CATEGORIES) NIL) ((UNTIL CACHE-UNTIL) NIL) ((WHILE CACHE-WHILE) NIL))

DEFURLS (&REST URLDEFS)

ENABLED-USER-AGENTS (&REST USER-AGENTS)

EXPANSION (EXPR)

SERVICE-CLIENT (SERVICE-NAME)

TAGS (EXPR)

USE-BACKTRACE-LOGGING (&REST BODY)

WITH-COOKIES (&OPTIONAL (COOKIES NIL) &REST BODY)

WITH-TAG-READER (NIL &REST BODY)

Private

HTML-FOR-USER-AGENT (&REST BODY)

Given the markup for a page, build a cond statement that will return the rendering appropriate to the current user agent

MAP-SERVICE-METHOD-DEFS ((METHOD-DEFS) &REST WORK)

Used to pull apart a method definition, which has the following structure. After the initial :method keyword, the structure below is a valid lambda list. (:method method-name &key ((:documentation documentation) nil) ((:http-method http-method) :get) ((:if test) nil) ((:cookies cookies) nil) ((:parameters parameters) nil) )

MAP-SERVICE-METHOD-HANDLERS ((SERVICE-NAME METHOD-HANDLERS) &REST WORK)

Each method handler should have the following form: (:method method-name &rest method-handler-body)

PUTEND (SOME-OBJECT SOME-PLACE)

Append some-object to the end of the list in some-place. Modifies some-place.

WITH-SKELETON-FILE ((STREAM SKELETON PATH) &REST BODY)

Write a string representation of content to the location specified path relative to the skeleton's base director

Undocumented

FORMAT-STRING (FORMAT-CONTROL-STRING &REST ARGS)

INITIALIZE-TAG (TAG-VAR &REST ATTRIBUTE-KEY-VALUES)

PARAMETER-NAME-P (REGISTER)

PUTENDNEW (SOME-OBJECT SOME-PLACE &KEY ((TEST TEST) 'EQUAL))

UNION-ORDERED (SOME-LIST SOME-PLACE)

GENERIC-FUNCTION

Public

GET-CACHED-ITEM (CACHE REQUEST)

Obtain a cached item, regardless of whether the item is in the cache or must be loaded from the provider

RENDER-AS-HTML (SOME-EXPR)

Return some expression as an HTML string

Undocumented

RUN-WEB-SERVER (SERVER-ACCEPTOR &KEY WAIT (WAIT NIL))

Private

ADD-TAG-TO-LIBRARY (TAG-DEFINITION &OPTIONAL TAG-LIBRARY)

Called at the point of tag definition to add the tag to the library

CACHE-ITEM (CACHE REQUEST ITEM)

Force an item into the cache for the indicated key, removing any item previously cached for that key

CACHE-PROVIDER-KEY (CACHE-PROVIDER REQUEST)

Compute or determine the key to use for the particular cache and request

CACHED-ITEM-EXPIREDP (PROVIDER-OR-CACHE ITEM)

Return non-nil if item should be refreshed from provider, rather than reused from the cache

CACHED-ITEM-INVALIDP (PROVIDER-OR-CACHE ITEM REQUEST)

Return non-nil if item is not valid (for example, because of a failed authorization check

CACHED-ITEM-STALEP (CACHE ITEM)

If an item is not yet stale, then the cache does not check with the provider to determine if the item is expired (intended as a means of throttling checks by the provider, which may be expensive

EXPAND-EXPRESSION-WITH-LIBRARIES (EXPR &OPTIONAL *AVAILABLE-TAG-LIBRARIES*)

Expand the expression using the provided libraries

FIND-CACHED-ITEM (CACHE REQUEST)

Find an item in the cache with the indicated key, or null if there is no item cached for that key or if the cached item has expired

FS-CACHE-FILE-FULL-PATH (PATH PROVIDER)

Return the full path of the indicated file

FS-CACHE-FILE-MODIFIED-TIME (PATH PROVIDER)

Obtain the file's modified time

GENERATE-SERVICE-CLIENT-SCRIPT (SERVICE-NAME)

Return a string of client-side Javascript sufficient for calling all methods of the service

GENERATE-SKELETON (SKELETON)

Generate all the files necessary for a project using hh-web

GENERATE-SKELETON-COMPONENT (SKELETON COMPONENT)

Generate the files necessary for the indicated component and skeleton

HANDLE-SERVICE-META-REQUEST (SERVICE-NAME META &OPTIONAL *REQUEST*)

Handle the service meta request with the named service, using the meta argument (if non-nil) or the +meta-service-request-parameter+ to determine what to do. Common meta service requests include (but are not limited to) the following values of +meta-service-request-parameter+: client - returns sufficient Javascript for invoking the service as an ordinary function form javascript help - returns an HTML page with a documentation string for the service documentation - same as help doc - same as help docs - same as help form - returns an HTML page with both the documentation string for the service, but also a form suitable for entering parameters and then invoking the service, as well as displaying (and changing?) values of involved cookies before and after the invocation.

LOAD-AND-CACHE-ITEM (CACHE REQUEST)

Load an item with the indicated key into the cache

LOAD-CACHE-ITEM-FROM-PROVIDER (PROVIDER REQUEST)

Load an item from the provider, given the indicated request

LOAD-TAG-LIBRARY (LIBRARY-NAME &OPTIONAL *TAG-LIBRARY-PROVIDER-REGISTRY*)

Load the tag library from the first provider that can provide it

LOAD-TAG-LIBRARY-FROM-PROVIDER (LIBRARY-NAME PROVIDER)

If the provider can provide a tag library with the indicated name, return the tag library; otherwise, return nil

LOAD-TEMPLATE-FROM-PROVIDER (*TEMPLATE* TEMPLATE-PATH PROVIDER)

If the provider can provide a template with the indicated path, return the template; otherwise, return nil

LOCATION-PATHNAME (LOCATION)

Convert the argument to a pathname

LOG-INTERVAL-EXPIRED-P (SENDER)

Return true if it's time to rotate the sender's logs

PROVIDER-TAG-LIBRARY-EXPIREDP (LIBRARY PROVIDER)

Return t if the provider considers the tag library expired, otherwise nil

PROVIDER-TEMPLATE-EXPIREDP (*TEMPLATE* PROVIDER)

Return t if the provider considers the template expired, otherwise nil

READ-TAG-LIBRARY (INPUT-STREAM)

Read in a tag library from a stream

READ-TEMPLATE-DEFINITION (INPUT-STREAM TEMPLATE-PACKAGE TEMPLATE-ARGS TEMPLATE-KEYWORD-ARGS)

Read a template definition from a stream

RENDER-TAG-ATTRIBUTES (*CURRENT-TAG*)

Render a tag's attributes as string of name=value pairs

RENDER-TAG-BODY (*CURRENT-TAG*)

Render the body of a tag as html

RENDER-TAG-CONTENT (*CURRENT-TAG*)

Render just the content portion of the tag (no styles or scripts): usually, the start tag, the rendered body, and the end tag. In tags that have a custom html representation, this is usually the method overriden.

RENDER-TAG-END (*CURRENT-TAG*)

Render the end of a tag

RENDER-TAG-READY-SCRIPTS (*CURRENT-TAG*)

Return a string representing script to run when a page first loads. During rendering, scripts are accumulated by visiting each tag in the page (depth, then breadth), and adding each unique script (based on string comparison) to the end of a list. Consequently, outer tags have their ready script run before inner tags.

RENDER-TAG-SCRIPT-LIBRARIES (*CURRENT-TAG*)

Return a list of strings pointing to script libraries used by instances of this tag

RENDER-TAG-SCRIPTS (*CURRENT-TAG*)

Return the script that should be shared by all instances of some-tag's class within the same context (page, stylesheet, etc.)

RENDER-TAG-START (*CURRENT-TAG*)

Render the beginning of a tag, including its attributes (by calling render-attributes)

RENDER-TAG-STYLE-SHEETS (*CURRENT-TAG*)

Return a list of strings pointing to stylesheets used by instances of this tag

RENDER-TAG-STYLES (*CURRENT-TAG*)

Return a list of styles expected by instances of this tag

SERVICE-ARGS (SERVICE-NAME)

Return a list of symbols identifying the arguments a service expects. All methods of a service share the same arguments.

SERVICE-DOCUMENTATION-STRING (SERVICE-NAME)

Return the documentation string provided with the service definition

SERVICE-METHOD-ARGS (SERVICE-NAME METHOD-NAME)

Return the argument list (derived from URL path component,typically) for a service

SERVICE-METHOD-COOKIES (SERVICE-NAME METHOD-NAME)

Return the cookies touched by a service method

SERVICE-METHOD-DOCUMENTATION-STRING (SERVICE-NAME METHOD-NAME)

Return the documentation string provided with the method definition

SERVICE-METHOD-HTTP-METHOD (SERVICE-NAME METHOD-NAME)

Return the HTTP method expected for this service method

SERVICE-METHOD-PARAMETERS (SERVICE-NAME METHOD-NAME)

Return the parameter list for a service method

SERVICE-METHOD-TEST (SERVICE-NAME METHOD-NAME)

Return the test expected for this service method

SERVICE-METHODS (SERVICE-NAME)

Return as a list the symbolic names of methods supported by the service

SKELETON-COMPONENTS (SKELETON)

Return the list of components of the skeleton, as a list of keywords

TAG-ATTRIBUTE-VALUE (*CURRENT-TAG* ATTRIBUTE)

Return the value of attribute on tag

SETFTAG-ATTRIBUTE-VALUE (VALUE *CURRENT-TAG* ATTRIBUTE)

Set the value of attribute on the tag

TAG-EXPANSION (SOME-TAG-SYMBOL)

Return the macro for expanding a tag expression into a tag object

TAG-LIBRARY (NAME)

Return the library with the indicated name

TAG-LIBRARY-EXPIREDP (LIBRARY)

Return if the library (or any of its dependent libraries) has epxired

TAG-LIBRARY-NAME-FOR-TAG (*CURRENT-TAG*)

Return the name of the tag library in which the tag is defined

TAG-LIBRARY-TAG-EXPANSIONS (SOME-LIBRARY)

For some library, return the list of macro expansions for each tag in the library

TAG-SEPARATE-INITIALIZER-AND-BODY (SOME-TAG-SYMBOL RAW-BODY)

Return 2 values (nil if the value is not applicable): the first is the tag initializer, the 2nd is the tag's computed body. Default behavior takes the first list starting ith +@ and uses the cdr of that list as the arguments to a make-instance call for that tag class. All other items in the list will be returned in the 2nd value for the body of the tag

TEMPLATE-PROVIDER-BASE-DIRECTORY (PROVIDER)

Returns the base directory on a fileystem for templates served by the provider. Directory name should end in /.

TEMPLATE-TAGS-EXPIREDP (TMPL)

Return t if any of the known required tag libraries used in the template have expired; nil otherwise

Undocumented

DELETE-OLD-LOGS (SENDER)

DISABLE-CACHE-LOADING (CACHE)

ENABLE-CACHE-LOADING (CACHE)

LIBRARY-NAME (CONDITION)

LOAD-TEMPLATE (TEMPLATE-PATH &OPTIONAL TEMPLATE-ARGS TEMPLATE-KEYWORD-ARGS)

RENAME-EXISTING-LOGS (SENDER)

ROTATE-LOGS (SENDER &OPTIONAL FORCE)

SKELETON-LOCATION (SKELETON)

TAG-LIBRARY-FILE-MODIFIED-TIME (LIBRARY-NAME PROVIDER)

TAG-LIBRARY-FULL-PATH (LIBRARY-NAME PROVIDER)

TAG-LIBRARY-STALEP (LIBRARY)

TEMPLATE-EXPIREDP (TMPL)

TEMPLATE-FILE-MODIFIED-TIME (TEMPLATE-PATH PROVIDER)

TEMPLATE-FULL-PATH (TEMPLATE-PATH PROVIDER)

TEMPLATE-STALEP (TMPL)

SLOT-ACCESSOR

Public

Undocumented

BODY-OF (OBJECT)

SETFBODY-OF (NEW-VALUE OBJECT)

Private

CACHE-KEY (ITEM-OR-REQUEST)

The Return the key for the item (or request)

SETFCACHE-KEY (NEW-VALUE OBJECT)

Set the Return the key for the item (or request)

CATEGORIES (OBJECT)

List of symbols identifying categories to which the content belongs

SETFCATEGORIES (NEW-VALUE OBJECT)

List of symbols identifying categories to which the content belongs

CONTEXTS (OBJECT)

The contexts where the string appears; usually URLs (actually paths) to pages containing the string

SETFCONTEXTS (NEW-VALUE OBJECT)

The contexts where the string appears; usually URLs (actually paths) to pages containing the string

DESCRIPTION (OBJECT)

A description of the string's purpose and expected usage. Likely this slot is unused in localized strings, but is useful for strings in the development locale

SETFDESCRIPTION (NEW-VALUE OBJECT)

A description of the string's purpose and expected usage. Likely this slot is unused in localized strings, but is useful for strings in the development locale

LOCALE (OBJECT)

The locale in which this specific string has been localized

SETFLOCALE (NEW-VALUE OBJECT)

The locale in which this specific string has been localized

LOCALIZATION (OBJECT)

The localized representation of a string

SETFLOCALIZATION (NEW-VALUE OBJECT)

The localized representation of a string

LOG-INTERVAL (OBJECT)

Interval in seconds between log rotations

SETFLOG-INTERVAL (NEW-VALUE OBJECT)

Interval in seconds between log rotations

MODIFIED-TIME-OF (ITEM)

The Required method for items in a cache, to determine whether it has become stale or expired

SETFMODIFIED-TIME-OF (NEW-VALUE OBJECT)

Set the Required method for items in a cache, to determine whether it has become stale or expired

NAME (OBJECT)

The string as it appeared in the development locale

SETFNAME (NEW-VALUE OBJECT)

The string as it appeared in the development locale

NOTES (OBJECT)

Notes from / to localizers about a string

SETFNOTES (NEW-VALUE OBJECT)

Notes from / to localizers about a string

TAG-ATTRIBUTES (*CURRENT-TAG*)

The Return a list of attribute names for the tag

SETFTAG-ATTRIBUTES (NEW-VALUE OBJECT)

Set the Return a list of attribute names for the tag

TAG-HAS-BODY-P (SOME-TAG-SYMBOL)

The Return t (the default) if a tag expects to have a tag body; nil otherwise. If no body, that implies the tag treats the raw body as an initializer for the tag, and that a custom html method will then use the tag's slots to render appropriate html.

SETFTAG-HAS-BODY-P (NEW-VALUE OBJECT)

Set the Return t (the default) if a tag expects to have a tag body; nil otherwise. If no body, that implies the tag treats the raw body as an initializer for the tag, and that a custom html method will then use the tag's slots to render appropriate html.

TAG-HAS-END-TAG-P (*CURRENT-TAG*)

The Return t (the default) if a tag expects to have an end tag rendered (e.g., </a>); nil otherwise. If nil, then the tag's rendering only includes the start tag and content (if any). Examples of use is the <img> and <input> tags.

SETFTAG-HAS-END-TAG-P (NEW-VALUE OBJECT)

Set the Return t (the default) if a tag expects to have an end tag rendered (e.g., </a>); nil otherwise. If nil, then the tag's rendering only includes the start tag and content (if any). Examples of use is the <img> and <input> tags.

TAG-LIBRARIES-USED (OBJECT)

A list of symbols identifying other libraries upon which this one depends

SETFTAG-LIBRARIES-USED (NEW-VALUE OBJECT)

A list of symbols identifying other libraries upon which this one depends

TAG-LIBRARY-TAGS (OBJECT)

A list of symbols identifying tags defined by this library

SETFTAG-LIBRARY-TAGS (NEW-VALUE OBJECT)

A list of symbols identifying tags defined by this library

TAG-NAME (*CURRENT-TAG*)

The Return the name of the tag as a string used for rendering in html

SETFTAG-NAME (NEW-VALUE OBJECT)

Set the Return the name of the tag as a string used for rendering in html

TAG-SYMBOL (OBJECT)

The tag symbol is the unique identifier for a tag definition

SETFTAG-SYMBOL (NEW-VALUE OBJECT)

The tag symbol is the unique identifier for a tag definition

Undocumented

CACHE-LOADING-ENABLED (OBJECT)

SETFCACHE-LOADING-ENABLED (NEW-VALUE OBJECT)

CACHE-PROVIDER (OBJECT)

SETFCACHE-PROVIDER (NEW-VALUE OBJECT)

CONTENT (OBJECT)

SETFCONTENT (NEW-VALUE OBJECT)

CONTENT-TYPE (OBJECT)

SETFCONTENT-TYPE (NEW-VALUE OBJECT)

DEFINITION-OF (OBJECT)

SETFDEFINITION-OF (NEW-VALUE OBJECT)

DISPATCH-TABLE-OF (OBJECT)

SETFDISPATCH-TABLE-OF (NEW-VALUE OBJECT)

ENTRIES (OBJECT)

SETFENTRIES (NEW-VALUE OBJECT)

EXPIRY (OBJECT)

SETFEXPIRY (NEW-VALUE OBJECT)

FOLDER-OF (OBJECT)

SETFFOLDER-OF (NEW-VALUE OBJECT)

FOR-PACKAGE (OBJECT)

SETFFOR-PACKAGE (NEW-VALUE OBJECT)

FS-ROOT (OBJECT)

SETFFS-ROOT (NEW-VALUE OBJECT)

GENERATOR (OBJECT)

SETFGENERATOR (NEW-VALUE OBJECT)

HANDLER (OBJECT)

SETFHANDLER (NEW-VALUE OBJECT)

IN-LOCATION (OBJECT)

SETFIN-LOCATION (NEW-VALUE OBJECT)

LAST-WRITE (OBJECT)

SETFLAST-WRITE (NEW-VALUE OBJECT)

MAXLOGS (OBJECT)

SETFMAXLOGS (NEW-VALUE OBJECT)

PACKAGE-OF (OBJECT)

SETFPACKAGE-OF (NEW-VALUE OBJECT)

PATTERNS (OBJECT)

SETFPATTERNS (NEW-VALUE OBJECT)

STRINGS (OBJECT)

SETFSTRINGS (NEW-VALUE OBJECT)

SYSTEM-OF (OBJECT)

SETFSYSTEM-OF (NEW-VALUE OBJECT)

TAG-ATTRIBUTE-MAP (OBJECT)

SETFTAG-ATTRIBUTE-MAP (NEW-VALUE OBJECT)

TAG-BASES (OBJECT)

SETFTAG-BASES (NEW-VALUE OBJECT)

TAG-CONTENT (OBJECT)

SETFTAG-CONTENT (NEW-VALUE OBJECT)

TAG-DEFINITION (OBJECT)

SETFTAG-DEFINITION (NEW-VALUE OBJECT)

TAG-INIT (OBJECT)

SETFTAG-INIT (NEW-VALUE OBJECT)

TAG-LIBRARY-NAME (OBJECT)

TAG-LIBRARY-PACKAGE (OBJECT)

SETFTAG-LIBRARY-PACKAGE (NEW-VALUE OBJECT)

TAG-LIBRARY-PROVIDER (OBJECT)

SETFTAG-LIBRARY-PROVIDER (NEW-VALUE OBJECT)

TAG-LIBRARY-PROVIDER-REGISTRY-OF (OBJECT)

SETFTAG-LIBRARY-PROVIDER-REGISTRY-OF (NEW-VALUE OBJECT)

TAG-READY-SCRIPTS (OBJECT)

SETFTAG-READY-SCRIPTS (NEW-VALUE OBJECT)

TAG-SCRIPT-LIBRARIES (OBJECT)

SETFTAG-SCRIPT-LIBRARIES (NEW-VALUE OBJECT)

TAG-SCRIPTS (OBJECT)

SETFTAG-SCRIPTS (NEW-VALUE OBJECT)

TAG-STYLE-SHEETS (OBJECT)

SETFTAG-STYLE-SHEETS (NEW-VALUE OBJECT)

TAG-STYLES (OBJECT)

SETFTAG-STYLES (NEW-VALUE OBJECT)

TEMPLATE-ARGS (OBJECT)

SETFTEMPLATE-ARGS (NEW-VALUE OBJECT)

TEMPLATE-KEYWORD-ARGS (OBJECT)

SETFTEMPLATE-KEYWORD-ARGS (NEW-VALUE OBJECT)

TEMPLATE-PACKAGE (OBJECT)

SETFTEMPLATE-PACKAGE (NEW-VALUE OBJECT)

TEMPLATE-PATH (CONDITION)

TEMPLATE-PROVIDER (OBJECT)

SETFTEMPLATE-PROVIDER (NEW-VALUE OBJECT)

TEMPLATE-PROVIDER-REGISTRY-OF (OBJECT)

SETFTEMPLATE-PROVIDER-REGISTRY-OF (NEW-VALUE OBJECT)

TEMPLATE-PROVIDERS-OF (OBJECT)

SETFTEMPLATE-PROVIDERS-OF (NEW-VALUE OBJECT)

TEST (OBJECT)

SETFTEST (NEW-VALUE OBJECT)

URL-CACHE-OF (OBJECT)

SETFURL-CACHE-OF (NEW-VALUE OBJECT)

VARIABLE

Public

*CURRENT-TAG*

The current tag under construction (if any), within the scope of a tag's body

*LOCALE-PACKAGE*

Default package containing localization information (locales)

*MINIMUM-TEMPLATE-STALE-TIME*

Minimum time in seconds for which a template must remain stale (e.g. not expire, before reloading from its source

*PACKAGE-TAG-LIBRARY-FOLDER*

Default folder within a package that contains the package's tag libraries

*PACKAGE-TEMPLATE-FOLDER*

The name of the folder within a package's folder structure where template files are located

*TAG-LIBRARY*

Current tag library to which new tag defintions will belong

*TAG-LIBRARY-PROVIDER-REGISTRY*

A list of functions such that when each is called with 1 argument (a tag name), they return the tag source as a stream or string

*TEMPLATE*

While reading a template, this is the current template object for whom a definition is being read

*TEMPLATE-PROVIDER-REGISTRY*

List of template providers, each of which will be called to resolve a template name to locate an appropriate template

*THIS-TAG*

The active tag in the scope of a tag method (e.g., while rendering); while rendering a custom tag, *this-tag* will not change within the same method, but *current-tag* changes within the body of each tag in the content

Undocumented

*ENABLED-USER-AGENTS*

*USER-AGENT*

*USER-AGENT-STRINGS*

Private

*AVAILABLE-TAG-LIBRARIES*

All tag libraries

*DEFAULT-TAG-DEFINITION*

Provides default implementation for tag methods

*DEFAULT-TAG-LIBRARY-FOLDER*

The default folder for tag libraries

*DEFAULT-TEMPLATE-FOLDER*

The default folder for templates

*DEVELOPMENT-LOCALE-NAME*

Locale in which development occurs, and in which strings in code first appear before translation into other locales

*HTML-OUT*

Output stream for rendering html

*LOCALE*

Current locale

*LOCALES*

List of loaded or known locales

*LOCALIZATION-CONTEXT*

Typically set to the URL in which the string occurs, but not always (and not always set implying no relevant context

*MINIMUM-CACHED-ITEM-STALE-TIME*

Minimum time in seconds for which a cache entry is not stale (and thus can't expire), but after which the item is stale and possible expired

*MINIMUM-TAG-LIBRARY-STALE-TIME*

Minimum time in seconds for which a tag library must remain stale (e.g. not expire) before reloading from its source

*MINIMUM-URL-CACHE-STALE-TIME*

Minimum time in seconds between checks for changes to URLs; lower times mean check for updates to defurls more often, higher times mean check more rarely

*PAGE-READY-SCRIPTS*

A list of strings, each representing script to be run when the document is ready (after load)

*PAGE-SCRIPT-LIBRARIES*

A list of strings, each pointing to a script library that the page referneces

*PAGE-SCRIPTS*

A list of strings, each representing a script added to the page

*PAGE-STYLE-SHEETS*

A list of strings, each pointing to a styleseheet that the page references

*PAGE-STYLES*

A list of strings, each representing CSS added to the page

*PAGE-TITLE*

The title of the page as it should be presented to the user in the browser

*TAG-PRINTING-LEVEL*

Used for pretty printing HTML, with proper indentation for nested tags

*TEMPLATE-CACHE*

Cache of template names to template objects

+META-SERVICE-REQUEST-PARAMETER+

When this parameter appears for a service, the service will perform other 'meta' activities for the service. See handle-service-meta-request.

+METHOD-PARAMETER+

Special parameter used in POST requests to indicate the actual desired method (should be either 'DELETE' or 'PUT'). Used by some browser-side code as a substitute for situations where the browser will not allow Javascript to send a native DELETE or PUT request.

Undocumented

*LOCALIZABLE-STRINGS*

*PACKAGE-TAG-LIBRARY-PROVIDER-REGISTRY*

*PACKAGE-TEMPLATE-PROVIDER-REGISTRY*

*URL-CACHE*

+CLIENT-META-SERVICE-REQUEST+

CLASS

Public

ROTATING-LOG-SENDER

A variation of stream sender that rotates logs based on a configurable interval. Log rotation happens just before a message is logged.

Undocumented

CLASS

HTMLTAG

STRING-LOCALIZATION

TEMPLATE

Private

FILE-BASED-TEMPLATE-PROVIDER

Generalized type for providers serving templates from the filesystem

SKELETON

A skeleton represents the starting point for a project based on hh-web

TAG-DEFINITION (OBJECT)

Holds the details of a particular type of tag. All slots are lambdas (or funcallables) except for symbol, name, bases, and attributes

URL-CACHE-ITEM

Represents an cache entry containing the generated content for a specific URL

Undocumented

ASDF-SYSTEM-PROVIDER

CACHE

CACHE-PROVIDER (OBJECT)

FOLDER-TAG-LIBRARY-PROVIDER

FOLDER-TEMPLATE-PROVIDER

FS-CACHE-ITEM

FS-CACHE-PROVIDER

LOCALE (OBJECT)

LOCALIZABLE-STRING

TAG-LIBRARY (NAME)

TAG-LIBRARY-PROVIDER (OBJECT)

TEMPLATE-PROVIDER (OBJECT)

TEMPLATE-PROVIDER-REGISTRY

URL-CACHE-PROVIDER

WEB-SERVER-ACCEPTOR

CONDITION

Private

Undocumented

TAG-LIBRARY-NOT-FOUND-ERROR

TEMPLATE-NOT-FOUND-ERROR