src/lib/web.sig

   1 (*
   2  * Dynamic web page generation with Standard ML
   3  * Copyright (C) 2003  Adam Chlipala
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18  *)
  19
  20 (* CGI interaction *)
  21
  22 signature WEB =
  23 sig
  24     val for : (int -> unit) -> int * int -> unit
  25     (* (for f (min, max)) runs f on i for every i from min to max, inclusive.
  26      * min may also be greater than max, for backward order. *)
  27
  28     val print : string -> unit
  29     (* Add to the web output buffer *)
  30     val clear : unit -> unit
  31     (* Clear web output buffer *)
  32     val noOutput : unit -> bool
  33     (* True if there is no output in the buffer *)
  34     val output : unit -> unit
  35     (* Flush the buffer *)
  36
  37     val setParam : string * string list -> unit
  38     (* Set the values associated with a single URL parameter.
  39      * Parameters acquire multiple values when things like the following
  40      *   appear in URL's: ...&x=1&x=2&...
  41      *)
  42     val setSingleParam : string * string -> unit
  43     (* Set a parameter with a single value *)
  44     val getParam : string -> string
  45     (* Get the first value set for a parameter, or "" if none is set *)
  46     val getMultiParam : string -> string list
  47     (* Get all values of a parameter *)
  48
  49     val pushParams : (string * string list) list -> unit
  50     (* Save the current parameter map and set the new ones given *)
  51     val popParams : unit -> unit
  52     (* Restore the last parameter map saved with pushParams *)
  53     val withParams : (unit -> 'a) -> (string * string list) list -> 'a
  54     (* (withParams f params) executes f with params added to the parameter
  55      * map, removing them afterwards *)
  56
  57     val getCgi : string -> string option
  58     (* Get a named value defined by the CGI protocol, such as HTTP_COOKIE *)
  59
  60     val html : string -> string
  61     (* Escape a plaintext string to appear in HTML *)
  62     val htmlNl : string -> string
  63     (* Like html, but changes newlines to <br>'s *)
  64     val urlEncode : string -> string
  65     (* Escape a plaintext string to appear in a URL *)
  66
  67     exception Format of string
  68     val stoi : string -> int
  69     (* Convert a string to an int, raising Format on error *)
  70     val stor : string -> real
  71     (* Convert a string to a real, raising Format on error *)
  72
  73     val summary : unit -> string
  74     (* Debugging info on CGI state *)
  75
  76     val getExn : unit -> exn
  77     (* Get the current exception when in an exception handler template *)
  78     val setExn : exn -> unit
  79     (* Set the exception to be returned by getExn *)
  80
  81     val setHeader : string * string list -> unit
  82     (* Set the values of an HTTP response header *)
  83     val getHeader : string -> string list option
  84     (* Get the values of an HTTP response header *)
  85     val addHeader : string * string -> unit
  86     (* Add a value for a header *)
  87     val getSingleHeader : string -> string option
  88     (* Get the first value of a header *)
  89
  90     type cookie = {name : string, value : string, expires : Date.date option,
  91                    domain : string option, path : string option, secure : bool}
  92     (* name: Key
  93      * value: Data to associate with name
  94      * expires: When browser should discard this cookie.
  95      *   NONE clears the cookie immediately. SOME of a date clears it at
  96      *   that date. Use a very far-off date for "non-expiring" cookies.
  97      * domain: If NONE, cookie is valid in current domain.
  98      *   If SOME, specifies a particular domain pattern for the cookie.
  99      * path: Like domain, but specifies path on a server
 100      * secure: If set, cookie may only be transferred over HTTPS
 101      *)
 102     val setCookie : cookie -> unit
 103     (* Add a cookie set request to the HTTP response *)
 104     val getCookie : string -> string option
 105     (* Get a cookie's value by looking up its name *)
 106
 107     val remoteHost : unit -> string option
 108     (* Get REMOTE_HOST CGI variable *)
 109
 110     val plusSeconds : Time.time * int -> Time.time
 111     (* Add seconds to a time *)
 112     val minusSeconds : Time.time * int -> Time.time
 113     (* Subtract seconds from a time *)
 114
 115     val replaceUrlVar : string * string * string -> string
 116     (* (replaceUrlVar (url, name, value)) replaces the value of
 117      * URL variable name in url by value. If name is not set in
 118      * url, it is added.
 119      *)
 120 end