ContentsIndex
CGI
Contents
Basics
Links and Images
Forms and Widgets
Form Creation
Form Submission
Textual Input
Checkbox
Button
Image
Selection Box
File
Abstract Selection
Handle Manipulation
Attribute Shortcuts
Advanced
Installing Translators
Outputable Stuff
Predefined Types for Input Fields
Lowlevel Stuff
Servlets
HTML and Style
Experimental Stuff
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.
Synopsis
data CGI a
ask :: WithHTML x CGI a -> CGI ()
tell :: CGIOutput a => a -> CGI ()
io :: (Read a, Show a) => IO a -> CGI a
run :: CGI () -> IO ()
runWithOptions :: CGIOptions -> CGI () -> IO ()
once :: (Read a, Show a) => CGI a -> CGI a
forever :: CGI () -> CGI ()
htell :: WithHTML x IO () -> CGI a
askOffline :: WithHTML x CGI a -> (Element -> IO ()) -> CGI ()
data Image
internalImage :: FreeForm -> String -> WithHTML x CGI Image
externalImage :: URL -> String -> WithHTML x CGI Image
makeImg :: Image -> HTMLField x y ()
makeRef :: Monad m => String -> WithHTML x m () -> CGI (WithHTML y m ())
makePopupRef :: String -> String -> HTMLCons x y CGI ()
makeA :: String -> String -> HTMLField x y ()
backLink :: Monad m => HTMLCons x y m ()
hlink :: Monad m => URL -> HTMLCons x y m ()
popuplink :: Monad m => String -> URL -> HTMLCons x y m ()
restart :: CGI ()
type HTMLField x y a = WithHTML x CGI () -> WithHTML y CGI a
makeForm :: WithHTML x CGI a -> WithHTML y CGI ()
standardQuery :: String -> WithHTML x CGI a -> CGI ()
submit :: InputHandle h => h INVALID -> (h VALID -> CGI ()) -> HTMLField x y ()
submit0 :: CGI () -> HTMLField x y ()
defaultSubmit :: InputHandle h => h INVALID -> (h VALID -> CGI ()) -> HTMLField x y ()
resetField :: HTMLField x y (InputField () INVALID)
activeInputField :: (Reason a, Read a) => (a -> CGI ()) -> HTMLField x y ()
activate :: (a -> CGI ()) -> HTMLField x y (InputField a INVALID) -> HTMLField x y ()
data DTree x y
submitx :: DTree x y -> HTMLField x y ()
dtleaf :: CGI () -> DTree x y
dtnode :: InputHandle h => h INVALID -> (h VALID -> DTree x y) -> DTree x y
inputField :: (Reason a, Read a) => HTMLField x y (InputField a INVALID)
textInputField :: HTMLField x y (InputField String INVALID)
passwordInputField :: (Reason a, Read a) => HTMLField x y (InputField a INVALID)
makeTextarea :: String -> HTMLField x y (InputField String INVALID)
checkboxInputField :: HTMLField x y (InputField Bool INVALID)
makeButton :: HTMLField x y (InputField Bool INVALID)
data RadioGroup a x
radioGroup :: Read a => WithHTML x CGI (RadioGroup a INVALID)
radioButton :: Show a => RadioGroup a INVALID -> a -> HTMLField x y ()
radioError :: RadioGroup a INVALID -> WithHTML x CGI ()
imageField :: Image -> HTMLField x y (InputField (Int, Int) INVALID)
selectMultiple :: Eq a => (a -> String) -> [a] -> [a] -> (Int, Int) -> HTMLField x y (InputField [a] INVALID)
selectSingle :: Eq a => (a -> String) -> Maybe a -> [a] -> HTMLField x y (InputField a INVALID)
selectBounded :: (Enum a, Bounded a, Read a, Show a, Eq a) => Maybe a -> HTMLField x y (InputField a INVALID)
fileInputField :: HTMLField x y (InputField FileReference INVALID)
as_rows :: AT -> Int
as_cols :: AT -> Int
table_io :: IO [[String]] -> CGI AT
getText :: Monad m => AT -> Int -> Int -> WithHTML x m ()
unAR :: AR -> [String]
selectionGroup :: WithHTML x CGI (SelectionGroup AR INVALID)
selectionButton :: SelectionGroup AR INVALID -> AT -> Int -> HTMLField x y ()
selectionDisplay :: SelectionGroup AR INVALID -> AT -> Int -> (WithHTML x CGI () -> [WithHTML x CGI ()] -> WithHTML x CGI a) -> WithHTML x CGI a
data InputField a x
data VALID
data INVALID
value :: HasValue i => i a VALID -> a
class InputHandle h
data F0 x = F0
data F1 a x = F1 (a x)
data F2 a b x = F2 (a x) (b x)
data F3 a b c x = F3 (a x) (b x) (c x)
data F4 a b c d x = F4 (a x) (b x) (c x) (d x)
data F5 a b c d e x = F5 (a x) (b x) (c x) (d x) (e x)
data F6 a b c d e f x = F6 (a x) (b x) (c x) (d x) (e x) (f x)
data F8 a b c d e f g h x = F8 (a x) (b x) (c x) (d x) (e x) (f x) (g x) (h x)
data FL a x = FL [a x]
data FA a b x = FA a (b x)
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 Phone = Phone {
unPhone :: 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
type CGIOptions = [CGIOption]
data URL
makeServlet :: CGI () -> CGIProgram
makeServletWithHook :: ([String] -> CGI ()) -> CGI () -> CGIProgram
module HTMLWrapper
module Style
data FrameSet
data FrameLayout
= ROWS
| COLS
data FrameSpacing
= FrameAbsolute Int
| FrameRelative Int
| FramePercent Int
makeFrame :: WithHTML x IO () -> CGI () -> CGI FrameSet
makeFrameset :: FrameLayout -> [(FrameSpacing, CGI FrameSet)] -> CGI FrameSet
framesetPage :: String -> CGI FrameSet -> CGI ()
Basics
data CGI a
Instances
Monad CGI
ask :: 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 :: 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.
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
runWithOptions :: CGIOptions -> CGI () -> IO ()

Turns a CGI action into an IO action. Used to turn the main CGI action into the main function of the program. Takes additional low-level options. Typical use:

 main = runWithOptions [] mainCGI
once :: (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 buildup of long backlogs.
forever :: CGI () -> CGI ()
Repeats a CGI action without saving its state so that the size of the log remains constant.
htell :: WithHTML x IO () -> CGI a
Terminate script by sending a HTML page constructed by monadic argument.
askOffline :: 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
Instances
internalImage
:: FreeFormthe raw image
-> Stringalternative text
-> WithHTML x CGI Image
Reference to internal image.
externalImage
:: URLURL of image
-> Stringalternative text
-> WithHTML x CGI Image
Reference to image by URL.
makeImg :: Image -> HTMLField x y ()
Create an inline image.
makeRef
:: Monad m
=> Stringinternal name of entity
-> WithHTML x m ()body of the reference
-> CGI (WithHTML y m ())
Create a hyperlink to internal entity.
makePopupRef
:: Stringname of popup window
-> Stringinternal name of entity
-> HTMLCons x y CGI ()
Create a popup hyperlink to internal entity.
makeA :: String -> String -> HTMLField 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.
popuplink :: Monad m => String -> URL -> HTMLCons x y m ()
Hyperlink that creates a named popup window from an URL string.
restart :: CGI ()
restart application.
Forms and Widgets
type HTMLField 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 :: 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 :: 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
:: InputHandle h
=> h INVALIDinput field handles to be validated and passed to callback action
-> (h VALID -> CGI ())callback maps valid input handles to a CGI action
-> HTMLField x y ()returns a field so that attributes can be attached
Create a submission button with attached action.
submit0 :: CGI () -> HTMLField x y ()
Create a continuation button that takes no parameters.
defaultSubmit :: InputHandle h => h INVALID -> (h VALID -> CGI ()) -> HTMLField x y ()
Create a submission button whose attached action is fired whenever the form is submitted without explicitly clicking any submit button. This can happen if an input field has an attached onclick=submit() action.
resetField :: HTMLField x y (InputField () INVALID)
Creates a reset button that clears all fields of a form.
activeInputField
:: (Reason a, Read a)
=> (a -> CGI ())Function that maps input data to a CGI action.
-> HTMLField x y ()
Creates an input field that submits the field to the browser when data is entered into this field.
activate :: (a -> CGI ()) -> HTMLField x y (InputField a INVALID) -> HTMLField x y ()
Attach a CGI action to the value returned by the input field. Activation means that data is submitted as soon as it is entered.
data DTree x y
Abstract type of decisions trees. These trees provide structured validation.
Instances
submitx :: DTree x y -> HTMLField x y ()
Create a submission button whose validation proceeds according to a decision tree. Trees are built using dtleaf and dtnode.
dtleaf :: CGI () -> DTree x y
Create a leaf in a decision tree from a CGI action.
dtnode :: InputHandle h => h INVALID -> (h VALID -> DTree x y) -> DTree x y
Create a node in a decision tree. Takes an invalid input field and a continuation. Validates the input field and passes it to the continuation if the validation was successful. The continuation can dispatch on the value of the input field and produces a new decision tree.
Textual Input
inputField :: (Reason a, Read a) => HTMLField x y (InputField a INVALID)
Create a textual input field. Return type can be *anything* in class Reason and Read.
textInputField :: HTMLField x y (InputField String INVALID)
Create a textual input field that returns the string entered. (Avoids having to put quotes around a string.)
passwordInputField :: (Reason a, Read a) => HTMLField x y (InputField a INVALID)
Like inputField but the characters are not echoed on the screen.
makeTextarea :: String -> HTMLField x y (InputField String INVALID)
Create a text area with a preset string.
Checkbox
checkboxInputField :: HTMLField x y (InputField Bool INVALID)
Creates a checkbox. Returns True if box was checked.
Button
makeButton :: HTMLField 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 :: 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 => RadioGroup a INVALID -> a -> HTMLField x y ()
Create a new radio button and attach it to an existing RadioGroup.
radioError :: 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 :: Image -> HTMLField x y (InputField (Int, Int) INVALID)
Create an input field from an image. Returns (x,y) position clicked in the image.
Selection Box
selectMultiple
:: 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 x y (InputField [a] INVALID)
Create a selection box where multiple entries can be selected.
selectSingle
:: Eq a
=> (a -> String)function to display values of type a
-> Maybe aoptional preselected value
-> [a]list of all possible values
-> HTMLField x y (InputField a INVALID)
Create a selection box where exactly one entry can be selected.
selectBounded :: (Enum a, Bounded a, Read a, Show a, Eq a) => Maybe a -> HTMLField x y (InputField a INVALID)
Selection box for elements of a Bounded type. Argument is the optional preselected value.
File
fileInputField :: HTMLField 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.
Abstract Selection
as_rows :: AT -> Int
as_cols :: AT -> Int
table_io :: IO [[String]] -> CGI AT
Transform an IO action that produces a table in list form into a CGI action that returns an abstract table.
getText :: Monad m => AT -> Int -> Int -> WithHTML x m ()
Access abstract table by row and column. Produces a test node in the document monad.
unAR :: AR -> [String]
selectionGroup :: WithHTML x CGI (SelectionGroup AR INVALID)
Create a selection group for a table.
selectionButton :: SelectionGroup AR INVALID -> AT -> Int -> HTMLField x y ()
Create a selection button for an abstract table
selectionDisplay :: SelectionGroup AR INVALID -> AT -> Int -> (WithHTML x CGI () -> [WithHTML x CGI ()] -> WithHTML x CGI a) -> WithHTML x CGI a
Create a labelled selection display for an abstract table. The display function takes the button element and a list of text nodes corresponding to the selected row and is expected to perform the layout.
Handle Manipulation
data InputField a x
Instances
HasValue InputField
InputHandle (InputField a)
StripHandle (InputField a x) a
data VALID
Instances
data INVALID
Instances
value :: HasValue i => i a VALID -> a
class InputHandle h
Instances
InputHandle (InputField a)
InputHandle F0
InputHandle a => InputHandle (F1 a)
(InputHandle a, InputHandle b) => InputHandle (F2 a b)
(InputHandle a, InputHandle b, InputHandle c) => InputHandle (F3 a b c)
(InputHandle a, InputHandle b, InputHandle c, InputHandle d) => InputHandle (F4 a b c d)
(InputHandle a, InputHandle b, InputHandle c, InputHandle d, InputHandle e) => InputHandle (F5 a b c d e)
(InputHandle a, InputHandle b, InputHandle c, InputHandle d, InputHandle e, InputHandle f) => InputHandle (F6 a b c d e f)
(InputHandle a, InputHandle b, InputHandle c, InputHandle d, InputHandle e, InputHandle f, InputHandle g) => InputHandle (F7 a b c d e f g)
(InputHandle a, InputHandle b, InputHandle c, InputHandle d, InputHandle e, InputHandle f, InputHandle g, InputHandle h) => InputHandle (F8 a b c d e f g h)
InputHandle a => InputHandle (FL a)
InputHandle b => InputHandle (FA a b)
InputHandle (RadioGroup a)
InputHandle (SelectionGroup a)
data F0 x
Constructors
F0
Instances
InputHandle F0
data F1 a x
Constructors
F1 (a x)
Instances
InputHandle a => InputHandle (F1 a)
data F2 a b x
Constructors
F2 (a x) (b x)
Instances
(InputHandle a, InputHandle b) => InputHandle (F2 a b)
data F3 a b c x
Constructors
F3 (a x) (b x) (c x)
Instances
(InputHandle a, InputHandle b, InputHandle c) => InputHandle (F3 a b c)
data F4 a b c d x
Constructors
F4 (a x) (b x) (c x) (d x)
Instances
(InputHandle a, InputHandle b, InputHandle c, InputHandle d) => InputHandle (F4 a b c d)
data F5 a b c d e x
Constructors
F5 (a x) (b x) (c x) (d x) (e x)
Instances
(InputHandle a, InputHandle b, InputHandle c, InputHandle d, InputHandle e) => InputHandle (F5 a b c d e)
data F6 a b c d e f x
Constructors
F6 (a x) (b x) (c x) (d x) (e x) (f x)
Instances
(InputHandle a, InputHandle b, InputHandle c, InputHandle d, InputHandle e, InputHandle f) => InputHandle (F6 a b c d e f)
data F8 a b c d e f g h x
Constructors
F8 (a x) (b x) (c x) (d x) (e x) (f x) (g x) (h x)
Instances
(InputHandle a, InputHandle b, InputHandle c, InputHandle d, InputHandle e, InputHandle f, InputHandle g, InputHandle h) => InputHandle (F8 a b c d e f g h)
data FL a x
Constructors
FL [a x]
Instances
InputHandle a => InputHandle (FL a)
data FA a b x
Constructors
FA a (b x)
Instances
InputHandle b => InputHandle (FA a b)
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 a => CGIOutput [a]
CGIOutput ELEMENT_
CGIOutput Char
CGIOutput FileReference
CGIOutput ResponseFileReference
CGIOutput Status
CGIOutput Location
CGIOutput FreeForm
data Status
Constructors
Status
statusCode :: Intstatus code
statusReason :: Stringreason phrase
statusContent :: (Maybe (WithHTML () IO ()))more explanation
Instances
CGIOutput Status
newtype Location
Constructors
Location URLredirection
Instances
CGIOutput Location
data FreeForm
Constructors
FreeForm
ffName :: Stringinternal name
ffContentType :: StringMIME type
ffRawContents :: Stringcontents as octet stream
Instances
CGIOutput FreeForm
data FileReference
Constructors
FileReference
fileReferenceName :: FilePathvalid local filename where this file can be accessed
fileReferenceContentType :: String
fileReferenceExternalName :: String
Instances
Reason FileReference
CGIOutput FileReference
Show FileReference
Read FileReference
Predefined Types for Input Fields
newtype Text
Arbitrary string data. No quotes required.
Constructors
Text
unText :: String
Instances
Read Text
Show Text
Reason Text
newtype NonEmpty
Non-empty strings.
Constructors
NonEmpty
unNonEmpty :: String
Instances
Read NonEmpty
Show NonEmpty
Reason NonEmpty
newtype AllDigits
Non-empty strings of digits.
Constructors
AllDigits
unAllDigits :: String
Instances
Read AllDigits
Show AllDigits
Reason AllDigits
newtype Phone
Phone numbers.
Constructors
Phone
unPhone :: String
Instances
Read Phone
Show Phone
Reason Phone
newtype EmailAddress
Reads an email address according to RFC 2822
Constructors
EmailAddress
unEmailAddress :: String
Instances
Read EmailAddress
Show EmailAddress
Reason EmailAddress
newtype CreditCardNumber
Reads a credit card number and performs Luhn check on it.
Constructors
CreditCardNumber
unCreditCardNumber :: String
Instances
Read CreditCardNumber
Show CreditCardNumber
Reason CreditCardNumber
data CreditCardExp
Reads credit card expiration dates in format .
Constructors
CreditCardExp
cceMonth :: Int
cceYear :: Int
Instances
Read CreditCardExp
Show CreditCardExp
Reason CreditCardExp
Lowlevel Stuff
data CGIOption
Constructors
NoPortdo not include port number in generated URLs
AutoPortinclude automatically generated port number in generated URLs
Port Intuse this port number in generated URLs
NoHttpsdo not attempt to detect Https
AutoHttpsautodetect Https by checking for port number 443 and env var HTTPS
Instances
Eq CGIOption
type CGIOptions = [CGIOption]
data URL
Instances
Read URL
Show URL
Reason URL
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 HTMLWrapper
module Style
Experimental Stuff
data FrameSet
Abstract data type of frame set generators.
Instances
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 Intin pixels
FrameRelative Intthe * format
FramePercent Intthe % format
Instances
Show FrameSpacing
makeFrame
:: WithHTML x IO ()additional attributes to frame
-> CGI ()contents of the frame
-> CGI FrameSetreturns HTML generator for the frame
Create a single frame. Returns the assigned name of the frame.
makeFrameset :: FrameLayout -> [(FrameSpacing, CGI FrameSet)] -> CGI FrameSet
Create a frameset, given a layout, its spacing, and its subframe(set)s.
framesetPage :: 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.5