doc.txt

WEB (planet "web.scm" ("soegaard" "web.plt" 1 0))

------------------------------------------------------------------
  WEB              (planet "web.scm" ("soegaard" "web.plt" 1 0))      
------------------------------------------------------------------

This module provides all exports from the modules below. That is
from:

  - binding.scm
  - cookie.scm
  - default.scm
  - doctype.scm
  - response.scm
  - request.scm
  - servlet.scm

furthermore the bindings from

  - (lib "xml.ss" "xml")
  - (lib "servlet.ss" "web-server")

are provided.

------------------------------------------------------------------
  COOKIES       (planet "cookie.scm" ("soegaard" "web.plt" 1 0))
------------------------------------------------------------------

This module provides a convenient interface to the cookies.

The following functions are available:

  - make-cookie       to create cookies
  - request-cookies   to extract cookies from a request
  - cookie-value      to extract a value stored in a cookie
  - cookie-values     to extract values stored in a cookie
  - output-cookie     to add a cookie to current-output-cookies

Furthermore two parameters are provided:

  - current-cookies          holds the cookies received in the current request
  - current-output-cookies   holds the cookies which will be sent out in the
                              response to the current request

The current-cookies parameter is to be set in the servlet's start functions.
The list of cookies in current-output-cookies is to be included in
in the response returned from the servler's start function.


> (make-cookie  name val #:key 
>               (comment #f) (domain #f) (max-age #f)
>               (path    #f) (secure #f) (version #f))

Return a cookie where name is associated with val.
If a keyword argument is present with a non-false value
then the corresponding cookie field is set.

Example:
   (make-cookie "time" (number->string (current-seconds)) #:max-age 3600)
   (make-cookie "id" "soegaard")


> (request-cookies request)
request-cookies : request -> bindings

Extract the cookie bindings from a request.


> (cookie-value name #:optional (on-not-found #f))
cookie-value : string -> (union string #f)

Return the first value associated with name.
If none exists, the optional keyword argument
on-not-found is returned - it defaults to #f.


> (cookie-values name)
cookie-values : string -> (list string)

Returns a list of the values associated with name.


> (output-cookie cookie)
output-cookie : cookie -> #void

Add cookie to current-output-cookies. They are to
be sent out eith the response to the current request.


------------------------------------------------------------------
  RESPONSE      (planet "response.scm" ("soegaard" "web.plt" 1 0))
------------------------------------------------------------------

This module provides a convenient interface to generating
responses to a web-server request.

The function

  - make-response   to generate a response

and the parameters

  - current-response-code      defaults to 200
  - current-response-message   defaults to "Okay"
  - current-response-seconds   defaults to (current-seconds)
  - current-response-mime      defaults to (string->bytes/utf-8 "text/html")
  - current-response-extras    defaults to '()

  - current-redirect-permanently   defaults to #f  ; 301 Moved Permanently
  - current-redirect-temporarily   defaults to #f  ; 302 Moved Temporarily
  - current-redirect-see-other     defaults to #f  ; 303 See Other

are available.


> (make-response document #:key
>               (code    (current-response-code))
>               (message (current-response-message))
>               (seconds (current-response-seconds))
>               (mime    (current-response-mime)))

Make-reponse generates a response whose body is document.
If a keyword argument is not present, the corresponding
parameter is used. Cookies are taken from the parameter
current-output-cookies. The parameter current-response-extra
is appended to the cookie associations and used as the
extra field of make-reponse/full [see doc for this funtion].

If any of the redirect parameters are assigned an url (as a string)
then a redirect repsponse is sent instead of a normal response.


------------------------------------------------------------------
  REQUEST      (planet "request.scm" ("soegaard" "web.plt" 1 0))
------------------------------------------------------------------

This module contains the parameter

 - current-request    holds the the current request

further more the function

 - make-test-request  generates a test request

is available.

> (make-test-request
>              #:key
>              (method       'get)
>              (uri          (string->url "http://localhost/"))
>              (headers      '())
>              (bindings     '())
>              (bindings/raw "")
>              (host-ip      0)  ; todo: the correct number for local host?
>              (client-ip    "127.0.0.1"))

Returns a request that can be used to testing purposes. 
The default values are seen above.


------------------------------------------------------------------
  SERVLET      (planet "servlet.scm" ("soegaard" "web.plt" 1 0))
------------------------------------------------------------------

This module provide the servlet syntax to conveniently define
a servlet.

> (servlet body ...)           : syntax

Evaluates to a function that receives a request and returns a 
response. It is intended to be used as the start procedure
in a module based servlet:

(module my-servlet mzscheme
  (provide interface-version timeout start)
  (require (planet "web.scm" ("soegaard" 1 0)))

  (define interface-version 'v1)
  (define timeout 6000)
 
  (define start
    (servlet 
      `(html (head (title "A title"))
             (body "A simple servlet"))))
)

The servlet receives the request and sets the parameters:

  - current-request
  - current-cookies
  - current-output-cookies
  - current-bindings

Then the body expressions are evaluated in order from left
to right. The last body expression must evaluate to an xexpr.
The response is generated by calling make-response with
the xexpr in question. 

Tip: Use

  (servlet 
     (report-errors-to-browser send/finish)
     (dispatch-on-action))

to see web-server errors directly in the browser
during developing.


------------------------------------------------------------------
  BINDING      (planet "binding.scm" ("soegaard" "web.plt" 1 0))
------------------------------------------------------------------

Provides the parameter

  - current-bindings   holds the bindings of the current request

and these exports from Jay McCarthy's with-binding.ss:

  - with-binding
  - with-bindings
  - with-binding/default-values
  - with-bindings/defaults

> (with-binding bindings (single-name ...) body ...)

Evaluates the body expressions in an environment, where each 
  single-name is bound the value associated with single-name
              in bindings, if single-name is not present in
              bindings, it is bound to #f


> (with-bindings bindings 
                 (bool-name ...) 
                 (single-name ...) 
                 (multiple-name ...) 
                 body ...)

Evaluates the body in an environment where each
  bool-name      is bound to #t, if bool-name is present in bindings
                 and #f otherwise
  single-name    is bound the value associated with single-name
                 in bindings, if single-name is not present in
                 bindings, it is bound to #f
  multiple-name  is bound to a list of the values associated to
                 multiple-name in bindings, (if no bindings are
                 present, it is bound to the empty list)


> (with-bindings/default-values bindings 
    (bool-name ...) 
    ((single-name single-default) ...) 
    ((multiple-name multiple-default) ...) 
    body ...)

Evaluates the body in an environment where each
  bool-name      is bound to #t, if bool-name is present in bindings
  single-name    is bound to the value associated with single-name
                 in bindings, if single-name is not present in
                 bindings, then it is bound to the corresponding
                 single-default
  multiple-name  is bound to a list of the values associated to
                 multiple-name in bindings, if no bindings are
                 present, it is bound to the corresponding
                 multuple-default

> (with-bindings/defaults bindings 
    (bool-name ...) 
    ((single-name single-default-thunk) ...) 
    ((multiple-name multiple-default-thunk) ...) 
    body ...)

Evaluates the body in an environment where each
  bool-name      is bound to #t, if bool-name is present in bindings
  single-name    is bound to the value associated with single-name
                 in bindings, if single-name is not present in
                 bindings, then it is bound to the result of
                 calling single-default-thunk
  multiple-name  is bound to a list of the values associated to
                 multiple-name in bindings, if no bindings are
                 present, it is bound to the result of calling
                 the multiple-default-thunk

------------------------------------------------------------------
  DOC TYPE      (planet "doctype.scm" ("soegaard" "web.plt" 1 0))
------------------------------------------------------------------

Contains definitions of all doctypes listed at

    <http://www.w3.org/QA/2002/04/valid-dtd-list.html>

the 16th feb 2006.

The following doctypes are exported:

   doctype-HTML-4.01-Transitional
   doctype-HTML-4.01-Frameset
   doctype-XHTML-1.0-Strict
   doctype-XHTML-1.0-Transitional
   doctype-XHTML-1.0-Frameset
   doctype-XHTML-1.1
   doctype-HTML-2.0
   doctype-HTML-3.2
   doctype-MathML-1.01
   doctype-MathML-2.0
   doctype-XHTML+MathML+SVG
   doctype-SVG-1.0
   doctype-SVG-1.1-Full
   doctype-SVG-1.1-Basic
   doctype-SVG-1.1-Tiny
   doctype-XHTML+MathML+SVG-Profile--XHTML-host
   doctype-XHTML+MathML+SVG-Profile--SVG-host

For example doctype-HTML-4.01-Strict is bound to 

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

Futhermore the parameter 

  - current-doctype   holds the current doctype

is provided. The current-doctype is used as default by make-response.

The default doctype is XHTML-1.0-Strict.


------------------------------------------------------------------
  DEFAULTS            
------------------------------------------------------------------

These functions are undocumented on purpose, since they may
disappear in the next version.

> (define-default name val)
> (override-default stx)
> (with-defaults body ...)

They are an attempt to solve the sevlet/parameter problem
described in this thread:

<http://list.cs.brown.edu/pipermail/plt-scheme/2006-February/011828.html>




------------------------------------------------------------------
  Keywords            
------------------------------------------------------------------

Keywords: _web_ _cookie_ _cookies_ _response_ _request_ _servlet_
          _doctype_