WASH.CGI.CGIXX

WashNGo-2.12: WASH is a family of embedded domain specific languages (EDSL) for programming Web applications in Haskell.

Contents

Index

WASH.CGI.CGIXX

Description

One stop shop for the WASH/CGI library. All high-level scripts should get along with importing just this module. Low-level scripts may have to import RawCGI. This version requires features beyond Haskell98, in particular multi parameter type classes and existential types.

Synopsis

data CGI a

ask :: CGIMonad cgi => WithHTML x cgi a -> cgi ()

tell :: (CGIMonad cgi, CGIOutput a) => a -> cgi ()

io :: (Read a, Show a) => IO a -> CGI a

run :: CGI () -> IO ()

once :: (CGIMonad cgi, Read a, Show a) => cgi a -> cgi a

forever :: CGIMonad cgi => cgi () -> cgi ()

htell :: CGIMonad cgi => WithHTML x IO () -> cgi a

askOffline :: CGIMonad cgi => WithHTML x cgi a -> (Element -> IO ()) -> cgi ()

data Image

internalImage :: CGIMonad cgi => FreeForm -> String -> WithHTML x cgi Image

externalImage :: CGIMonad cgi => URL -> String -> WithHTML x cgi Image

makeImg :: Monad cgi => Image -> HTMLField cgi x y ()

makeRef :: (CGIMonad cgi, Monad m) => String -> WithHTML x m () -> cgi (WithHTML y m ())

makeA :: CGIMonad cgi => String -> String -> HTMLField cgi x y ()

backLink :: Monad m => HTMLCons x y m ()

hlink :: Monad m => URL -> HTMLCons x y m ()

type HTMLField cgi x y a = WithHTML x cgi () -> WithHTML y cgi a

makeForm :: CGIMonad cgi => WithHTML x cgi a -> WithHTML y cgi ()

standardQuery :: CGIMonad cgi => String -> WithHTML x cgi a -> cgi ()

submit :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> cgi ()) -> HTMLField cgi x y ()

submit0 :: CGIMonad cgi => cgi () -> HTMLField cgi x y ()

defaultSubmit :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> cgi ()) -> HTMLField cgi x y ()

resetField :: CGIMonad cgi => HTMLField cgi x y (InputField () INVALID)

activeInputField :: (CGIMonad cgi, Reason a, Read a) => (a -> cgi ()) -> HTMLField cgi x y ()

activate :: (CGIMonad cgi, StripHandle ha a) => (a -> cgi ()) -> HTMLField cgi x y ha -> HTMLField cgi x y ha

submitx :: DTree cgi x y -> HTMLField cgi x y ()

data DTree cgi x y

dtleaf :: CGIMonad cgi => cgi () -> DTree cgi x y

dtnode :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> DTree cgi x y) -> DTree cgi x y

inputField :: (CGIMonad cgi, Reason a, Read a) => HTMLField cgi x y (InputField a INVALID)

textInputField :: CGIMonad cgi => HTMLField cgi x y (InputField String INVALID)

checkedTextInputField :: CGIMonad cgi => (Maybe String -> Maybe String) -> HTMLField cgi x y (InputField String INVALID)

passwordInputField :: (CGIMonad cgi, Reason a, Read a) => HTMLField cgi x y (InputField a INVALID)

makeTextarea :: CGIMonad cgi => String -> HTMLField cgi x y (InputField String INVALID)

checkboxInputField :: CGIMonad cgi => HTMLField cgi x y (InputField Bool INVALID)

makeButton :: CGIMonad cgi => HTMLField cgi x y (InputField Bool INVALID)

data RadioGroup a x

radioGroup :: (CGIMonad cgi, Read a) => WithHTML x cgi (RadioGroup a INVALID)

radioButton :: (Show a, Monad cgi) => RadioGroup a INVALID -> a -> HTMLField cgi x y ()

radioError :: CGIMonad cgi => RadioGroup a INVALID -> WithHTML x cgi ()

imageField :: CGIMonad cgi => Image -> HTMLField cgi x y (InputField (Int, Int) INVALID)

selectMultiple :: (CGIMonad cgi, Eq a) => (a -> String) -> [a] -> [a] -> (Int, Int) -> HTMLField cgi x y (InputField [a] INVALID)

selectSingle :: (CGIMonad cgi, Eq a) => (a -> String) -> Maybe a -> [a] -> HTMLField cgi x y (InputField a INVALID)

selectBounded :: (CGIMonad cgi, Enum a, Bounded a, Read a, Show a, Eq a) => Maybe a -> HTMLField cgi x y (InputField a INVALID)

fileInputField :: CGIMonad cgi => HTMLField cgi x y (InputField FileReference INVALID)

checkedFileInputField :: CGIMonad cgi => (Maybe FileReference -> Maybe FileReference) -> HTMLField cgi x y (InputField FileReference INVALID)

data InputField a x

data VALID

data INVALID

fieldSIZE :: Monad m => Int -> WithHTML x m ()

fieldMAXLENGTH :: Monad m => Int -> WithHTML x m ()

fieldVALUE :: (Monad m, Show a) => a -> WithHTML x m ()

runWithHook :: CGIOptions -> ([String] -> CGI ()) -> CGI () -> IO ()

docTranslator :: [FreeForm] -> ([String] -> CGI ()) -> [String] -> CGI ()

lastTranslator :: [String] -> CGI ()

class CGIOutput a

data Status = Status {

statusCode :: Int

statusReason :: String

statusContent :: (Maybe (WithHTML () IO ()))

}

newtype Location = Location URL

data FreeForm = FreeForm {

ffName :: String

ffContentType :: String

ffRawContents :: String

}

data FileReference = FileReference {

fileReferenceName :: FilePath

fileReferenceContentType :: String

fileReferenceExternalName :: String

}

newtype Text = Text {

unText :: String

}

newtype NonEmpty = NonEmpty {

unNonEmpty :: String

}

newtype AllDigits = AllDigits {

unAllDigits :: String

}

newtype EmailAddress = EmailAddress {

unEmailAddress :: String

}

newtype CreditCardNumber = CreditCardNumber {

unCreditCardNumber :: String

}

data CreditCardExp = CreditCardExp {

cceMonth :: Int

cceYear :: Int

}

data CGIOption

= NoPort

| AutoPort

| Port Int

| NoHttps

| AutoHttps

| FullURL

| PartialURL

| SessionMode {

unSessionMode :: SessionMode

}

type CGIOptions = [CGIOption]

makeServlet :: CGI () -> CGIProgram

makeServletWithHook :: ([String] -> CGI ()) -> CGI () -> CGIProgram

module WASH.CGI.HTMLWrapper

module WASH.CGI.Style

data FrameSet

data FrameLayout

= ROWS

| COLS

data FrameSpacing

= FrameAbsolute Int

| FrameRelative Int

| FramePercent Int

makeFrame :: CGIMonad cgi => WithHTML x IO () -> cgi () -> cgi FrameSet

makeFrameset :: CGIMonad cgi => FrameLayout -> [(FrameSpacing, cgi FrameSet)] -> cgi FrameSet

framesetPage :: CGIMonad cgi => String -> cgi FrameSet -> cgi ()

Basics

data CGI a

Instances

CGIMonad CGI

Monad CGI

MonadFix CGI

WithMonad CGI

ask :: CGIMonad cgi => WithHTML x cgi a -> cgi ()

Takes a monadic value that constructs a HTML page and delivers this page to the browser. This page may contain forms and input widgets.

tell :: (CGIMonad cgi, CGIOutput a) => a -> cgi ()

Terminates script by sending its argument to the browser.

io :: (Read a, Show a) => IO a -> CGI a

Safe embedding of an IO action into the CGI monad. Intentionally not parameterized óver its monad to avoid its use inside of transactions.

run :: CGI () -> IO ()

Turns a CGI action into an IO action. Used to turn the main CGI action into the main function of the program. Typical use:

 main = run mainCGI

once :: (CGIMonad cgi, Read a, Show a) => cgi a -> cgi a

Brackets a CGI action so that only its result is visible. Improves efficiency by not executing the bracketed action after it has been performed once. Use this for avoiding the inefficient buildup of long interaction logs.

forever :: CGIMonad cgi => cgi () -> cgi ()

Repeats a CGI action without saving its state so that the size of the interaction log remains constant.

htell :: CGIMonad cgi => WithHTML x IO () -> cgi a

Terminate script by sending a HTML page constructed by monadic argument.

askOffline :: CGIMonad cgi => WithHTML x cgi a -> (Element -> IO ()) -> cgi ()

Like ask, but passes the constructed HTML page to the elementAction parameter. This function may send the page via Email or store it into a file. Anyone loading this page in a browser can resume the interaction.

Links and Images

data Image

internalImage

:: CGIMonad cgi
=> FreeForm	the raw image
-> String	alternative text
-> WithHTML x cgi Image
Reference to internal image.

externalImage

:: CGIMonad cgi
=> URL	URL of image
-> String	alternative text
-> WithHTML x cgi Image
Reference to image by URL.

makeImg :: Monad cgi => Image -> HTMLField cgi x y ()

Create an inline image.

makeRef

:: (CGIMonad cgi, Monad m)
=> String	internal name of entity
-> WithHTML x m ()	body of the reference
-> cgi (WithHTML y m ())
Create a hyperlink to internal entity.

makeA :: CGIMonad cgi => String -> String -> HTMLField cgi x y ()

Create hyperlink to internal entity /path?name.

backLink :: Monad m => HTMLCons x y m ()

Link to previous page in browser's history. Uses JavaScript.

hlink :: Monad m => URL -> HTMLCons x y m ()

Plain Hyperlink from an URL string.

Forms and Widgets

type HTMLField cgi x y a = WithHTML x cgi () -> WithHTML y cgi a

Every input widget maps the content generator for the widget (which may produce HTML elements or attributes) to the content generator of the widget.

Form Creation

makeForm :: CGIMonad cgi => WithHTML x cgi a -> WithHTML y cgi ()

Wraps an HTML form around its arguments. All standard attributes are computed and need not be supplied explicitly.

standardQuery :: CGIMonad cgi => String -> WithHTML x cgi a -> cgi ()

Convenient workhorse. Takes the title of a page and a monadic HTML value for the contents of the page. Wraps the contents in a form so that input fields and buttons may be used inside.

Form Submission

submit :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> cgi ()) -> HTMLField cgi x y ()

create a submission button with attached action

submit0 :: CGIMonad cgi => cgi () -> HTMLField cgi x y ()

create a continuation button with parameters

defaultSubmit :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> cgi ()) -> HTMLField cgi x y ()

resetField :: CGIMonad cgi => HTMLField cgi x y (InputField () INVALID)

Creates a reset button that clears all fields of a form.

activeInputField

:: (CGIMonad cgi, Reason a, Read a)
=> (a -> cgi ())	Function that maps input data to a CGI action.
-> HTMLField cgi x y ()
Creates an input field that submits the field to the browser when data is entered into this field.

activate :: (CGIMonad cgi, StripHandle ha a) => (a -> cgi ()) -> HTMLField cgi x y ha -> HTMLField cgi x y ha

Attach a CGI action to the value returned by the input field. Activation means that data is submitted as soon as it is entered.

submitx :: DTree cgi x y -> HTMLField cgi x y ()

submission with staged validation

data DTree cgi x y

dtleaf :: CGIMonad cgi => cgi () -> DTree cgi x y

dtnode :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> DTree cgi x y) -> DTree cgi x y

Textual Input

inputField :: (CGIMonad cgi, Reason a, Read a) => HTMLField cgi x y (InputField a INVALID)

Create a textual input field. Return type can be *anything* in class Reason and Read.

textInputField :: CGIMonad cgi => HTMLField cgi x y (InputField String INVALID)

Create a textual input field that returns the string entered. (Avoids having to put quotes around a string.)

checkedTextInputField :: CGIMonad cgi => (Maybe String -> Maybe String) -> HTMLField cgi x y (InputField String INVALID)

Creates a textual input field that takes a custom validation function.

passwordInputField :: (CGIMonad cgi, Reason a, Read a) => HTMLField cgi x y (InputField a INVALID)

Like inputField but the characters are not echoed on the screen.

makeTextarea :: CGIMonad cgi => String -> HTMLField cgi x y (InputField String INVALID)

Create a text area with a preset string.

Checkbox

checkboxInputField :: CGIMonad cgi => HTMLField cgi x y (InputField Bool INVALID)

Creates a checkbox. Returns True if box was checked.

Button

makeButton :: CGIMonad cgi => HTMLField cgi x y (InputField Bool INVALID)

Create a single button.

data RadioGroup a x

Instances

HasValue RadioGroup

InputHandle (RadioGroup a)

StripHandle (RadioGroup a x) a

radioGroup :: (CGIMonad cgi, Read a) => WithHTML x cgi (RadioGroup a INVALID)

Create a handle for a new radio group. This handle is invisible on the screen!

radioButton :: (Show a, Monad cgi) => RadioGroup a INVALID -> a -> HTMLField cgi x y ()

Create a new radio button and attach it to an existing RadioGroup.

radioError :: CGIMonad cgi => RadioGroup a INVALID -> WithHTML x cgi ()

Create and place the error indicator for an existing RadioGroup. Becomes visible only if no button of a radio group is pressed.

Image

imageField :: CGIMonad cgi => Image -> HTMLField cgi x y (InputField (Int, Int) INVALID)

Create an input field from an image. Returns (x,y) position clicked in the image.

Selection Box

selectMultiple

:: (CGIMonad cgi, Eq a)
=> (a -> String)	function to display values of type a
-> [a]	list of preselected entries
-> [a]	list of all possible entries
-> (Int, Int)	(min, max) number of fields that must be selected
-> HTMLField cgi x y (InputField [a] INVALID)
Create a selection box where multiple entries can be selected.

selectSingle

:: (CGIMonad cgi, Eq a)
=> (a -> String)	function to display values of type a
-> Maybe a	optional preselected value
-> [a]	list of all possible values
-> HTMLField cgi x y (InputField a INVALID)
Create a selection box where exactly one entry can be selected.

selectBounded :: (CGIMonad cgi, Enum a, Bounded a, Read a, Show a, Eq a) => Maybe a -> HTMLField cgi x y (InputField a INVALID)

Selection box for elements of a Bounded type. Argument is the optional preselected value.

File

fileInputField :: CGIMonad cgi => HTMLField cgi x y (InputField FileReference INVALID)

Creates a file input field. Returns a temporary FileReference. The fileReferenceName of the result is *not* guaranteed to be persistent. The application is responsible for filing it away at a safe place.

checkedFileInputField :: CGIMonad cgi => (Maybe FileReference -> Maybe FileReference) -> HTMLField cgi x y (InputField FileReference INVALID)

Creates a file input field. Like fileInputField but has an additional parameter for additional validation of the input.

Handle Manipulation

data InputField a x

Instances

HasValue InputField

InputHandle (InputField a)

StripHandle (InputField a x) a

data VALID

data INVALID

Attribute Shortcuts

fieldSIZE :: Monad m => Int -> WithHTML x m ()

Create a SIZE attribute from an Int.

fieldMAXLENGTH :: Monad m => Int -> WithHTML x m ()

Create a MAXLENGTH attribute from an Int.

fieldVALUE :: (Monad m, Show a) => a -> WithHTML x m ()

Create a VALUE attribute from any Showable.

Advanced

Installing Translators

runWithHook :: CGIOptions -> ([String] -> CGI ()) -> CGI () -> IO ()

Variant of run where an additional argument cgigen specifies an action taken when the script is invoked with a non-empty query string as in script-name?query-string

docTranslator :: [FreeForm] -> ([String] -> CGI ()) -> [String] -> CGI ()

A translator is a function [String] -> CGI (). It takes the query string of the URL (of type [String]) and translates it into a CGI action. docTranslator docs next takes a list of FreeForm documents and a next translator. It tries to select a document by its ffName and falls through to the next translator if no document matches.

lastTranslator :: [String] -> CGI ()

Terminates a sequence of translators.

Outputable Stuff

class CGIOutput a

Instances

CGIOutput Char

CGIOutput ELEMENT_

CGIOutput FileReference

CGIOutput FreeForm

CGIOutput Location

CGIOutput ResponseFileReference

CGIOutput Status

CGIOutput a => CGIOutput [a]

data Status

Constructors

Status

statusCode :: Int	status code
statusReason :: String	reason phrase
statusContent :: (Maybe (WithHTML () IO ()))	more explanation

Instances

CGIOutput Status

newtype Location

Constructors

Location URL

redirection

Instances

CGIOutput Location

data FreeForm

Constructors

FreeForm

ffName :: String	internal name
ffContentType :: String	MIME type
ffRawContents :: String	contents as octet stream

Instances

CGIOutput FreeForm

data FileReference

Constructors

FileReference

fileReferenceName :: FilePath	valid local filename where this file can be accessed
fileReferenceContentType :: String
fileReferenceExternalName :: String

Instances

CGIOutput FileReference

Read FileReference

Reason FileReference

Show FileReference

Predefined Types for Input Fields

newtype Text

Arbitrary string data. No quotes required.

Constructors

Text

unText :: String

Instances

Read Text

Reason Text

Show Text

newtype NonEmpty

Non-empty strings.

Constructors

NonEmpty

unNonEmpty :: String

Instances

Read NonEmpty

Reason NonEmpty

Show NonEmpty

newtype AllDigits

Non-empty strings of digits.

Constructors

AllDigits

unAllDigits :: String

Instances

Read AllDigits

Reason AllDigits

Show AllDigits

newtype EmailAddress

Reads an email address according to RFC 2822

Constructors

EmailAddress

unEmailAddress :: String

Instances

Read EmailAddress

Reason EmailAddress

Show EmailAddress

newtype CreditCardNumber

Reads a credit card number and performs Luhn check on it.

Constructors

CreditCardNumber

unCreditCardNumber :: String

Instances

Read CreditCardNumber

Reason CreditCardNumber

Show CreditCardNumber

data CreditCardExp

Reads credit card expiration dates in format .

Constructors

CreditCardExp

cceMonth :: Int
cceYear :: Int

Instances

data CGIOption

Constructors

NoPort

do not include port number in generated URLs

AutoPort

include automatically generated port number in generated URLs (default)

Port Int

use this port number in generated URLs

NoHttps

do not attempt to detect Https

AutoHttps

autodetect Https by checking for port number 443 and env var HTTPS (default)

FullURL

generate full URL including scheme, host, and port

PartialURL

generate absolute path URL, only (default)

SessionMode

unSessionMode :: SessionMode

Instances

Eq CGIOption

Show CGIOption

type CGIOptions = [CGIOption]

Servlets

makeServlet :: CGI () -> CGIProgram

Transform a CGI action into a servlet suitable for running from Marlow's web server.

makeServletWithHook :: ([String] -> CGI ()) -> CGI () -> CGIProgram

Like makeServlet with additional CGI generator as in runWithHook.

HTML and Style

module WASH.CGI.HTMLWrapper

module WASH.CGI.Style

Experimental Stuff

data FrameSet

Abstract data type of frame set generators.

data FrameLayout

Overall layout of a frame set: row-wise or column-wise.

Constructors

ROWS
COLS

Instances

Show FrameLayout

data FrameSpacing

Division of space between elements of a frameset. See http://wp.netscape.com/assist/net_sites/frame_syntax.html

Constructors

FrameAbsolute Int	in pixels
FrameRelative Int	the `*` format
FramePercent Int	the `%` format

Instances

Show FrameSpacing

makeFrame

:: CGIMonad cgi
=> WithHTML x IO ()	additional attributes to frame
-> cgi ()	contents of the frame
-> cgi FrameSet	returns HTML generator for the frame
Create a single frame. Returns the assigned name of the frame.

makeFrameset :: CGIMonad cgi => FrameLayout -> [(FrameSpacing, cgi FrameSet)] -> cgi FrameSet

Create a frameset, given a layout, its spacing, and its subframe(set)s.

framesetPage :: CGIMonad cgi => String -> cgi FrameSet -> cgi ()

Required wrapper for pages with frames. Takes a title and a FrameSet generator and displays the page.

Produced by Haddock version 0.8