#lang scribble/doc

@require[(file "base.ss")]

@title[#:tag "delirium"]{Delirium API}

The Delirium API invokes Delirium.  This API is provided by
the main file @file{delirium.ss} which you can require
as follows:

@schemeblock[
  (require (planet "delirium.ss" ("untyped" "delirium.plt" 1)))]

@defproc[(run-delirium [request request?] [test schemeunit-test?] [run-tests procedure? test/text-ui]) response?]

Runs Delirium with the given @schemeid[test] (which can be
a test suite or test case) in response to the given web
server @schemeid[request].

The optional @schemeid[run-tests] argument specifies a
function to actually run the tests.  It defaults to
@schemeid[test/text-ui] provided by SchemeUnit.


@defproc[(schemeunit-test? [test any]) boolean]

Returns @scheme[#t] if @schemeid[test] is either a
SchemeUnit test suite or test case, and @scheme[#f]
otherwise.


@section[#:tag "delirium-instaweb"]{Delirium Instaweb Integration}

The Delirium/Instaweb integration is provided by the file
@file{instaweb.ss} which you can require as follows:

@schemeblock[
  (require (planet "instaweb.ss" ("untyped" "delirium.plt" 1)))]


It provides a single function, @schemeid[instaweb/delirium].

@defproc[(instaweb/delirium  
           [#:port port integer]
           [#:test test schemeunit-test?]
           [#:listen-ip listen-ip (or/c string? #f) "127.0.0.1"]
           [#:run-tests run-tests procedure? test/text-ui]
           [#:servlet-path servlet-path (or/c path? string?) "servlet.ss"]
           [#:htdocs-path htdocs-path (or/c path? string?) instaweb-default]
           [#:servlet-namespace servlet-namespace (listof require-spec?) instaweb-default]
           [run-tests? boolean #t]
           [send-url? boolean #t]
           [test-url url? (string->url (format "http://localhost:~a/test" port))]
           [new-window? boolean #t]) void?]

Constructs a servlet that serves requests to @schemeid[test-url] with Delirium and all other requests with files in @schemeid[htdocs-path] or the servlet given in @scheme[servlet-path] as per the standard Instaweb rules.

The arguments @schemeid[port], @schemeid[listen-ip], @schemeid[servlet-path], @schemeid[htdocs-path], and @schemeid[servlet-namespace] have the same meaning as in Instaweb

The argument @schemeid[run-tests] has the same meaning as in @scheme[run-delirium].

The argument @schemeid[test-url] is the URL that invokes Delirum.  By default it is @tt{http://localhost:<port>/test}.

The argument @schemeid[run-tests?] determines if Delirium is actually installed at @schemeid[test-url].  This provides a simple way to toggle test and production versions of your site.

The argument @schemeid[send-url?] determines if a web browser is immediatelydirected to @schemeid[test-url], and @schemeid[new-window?] determines if a new window is opened if a web browser is already running.

Practically speaking, to use @scheme[instaweb/delirium] the options you will want to set are as follows:

@itemize{
  @item{Set a value for @schemeid[port] and @schemeid[test]}
  @item{Set options as for Instaweb}
  @item{Set @schemeid[run-tests?] to @scheme[#f] if you're running in production}
}

If you're not running in production a web browser will be automatically opened and start running your tests.  If you are running in production your web site will just run as normal!