| |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||
Description | |||||||||||||||||||||||||||
Version : $Id: XmlIOStateArrow.hs,v 1.39 20061109 20:27:42 hxml Exp $ the basic state arrows for XML processing A state is needed for global processing options, like encoding options, document base URI, trace levels and error message handling The state is separated into a user defined state and a system state. The system state contains variables for error message handling, for tracing, for the document base for accessing XML documents with relative references, e.g. DTDs, and a global key value store. This assoc list has strings as keys and lists of XmlTrees as values. It is used to store arbitrary XML and text values, e.g. user defined global options. The user defined part of the store is in the default case empty, defined as (). It can be extended with an arbitray data type | |||||||||||||||||||||||||||
Synopsis | |||||||||||||||||||||||||||
Data Types | |||||||||||||||||||||||||||
data XIOState us | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||
data XIOSysState | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||
type IOStateArrow s b c = IOSLA (XIOState s) b c | |||||||||||||||||||||||||||
The arrow type for stateful arrows | |||||||||||||||||||||||||||
type IOSArrow b c = IOStateArrow () b c | |||||||||||||||||||||||||||
The arrow for stateful arrows with no user defined state | |||||||||||||||||||||||||||
Running Arrows | |||||||||||||||||||||||||||
initialState :: us -> XIOState us | |||||||||||||||||||||||||||
the default global state, used as initial state when running an IOSArrow with runIOSLA or runX | |||||||||||||||||||||||||||
initialSysState :: XIOSysState | |||||||||||||||||||||||||||
runX :: IOSArrow XmlTree c -> IO [c] | |||||||||||||||||||||||||||
apply an IOSArrow to an empty root node with initialState () as initial state the main entry point for running a state arrow with IO when running runX f an empty XML root node is applied to f. usually f will start with a constant arrow (ignoring the input), e.g. a readDocument arrow. for usage see examples with writeDocument if input has to be feed into the arrow use runIOSLA like in runIOSLA f emptyX inputDoc | |||||||||||||||||||||||||||
User State Manipulation | |||||||||||||||||||||||||||
getUserState :: IOStateArrow s b s | |||||||||||||||||||||||||||
read the user defined part of the state | |||||||||||||||||||||||||||
setUserState :: IOStateArrow s s s | |||||||||||||||||||||||||||
set the user defined part of the state | |||||||||||||||||||||||||||
changeUserState :: (b -> s -> s) -> IOStateArrow s b b | |||||||||||||||||||||||||||
change the user defined part of the state | |||||||||||||||||||||||||||
withExtendedUserState :: s1 -> IOStateArrow (s1, s0) b c -> IOStateArrow s0 b c | |||||||||||||||||||||||||||
extend user state Run an arrow with an extended user state component, The old component is stored together with a new one in a pair, the arrow is executed with this extended state, and the augmented state component is removed form the state when the arrow has finished its execution | |||||||||||||||||||||||||||
withOtherUserState :: s1 -> IOStateArrow s1 b c -> IOStateArrow s0 b c | |||||||||||||||||||||||||||
change the type of user state This conversion is useful, when running a state arrow with another structure of the user state, e.g. with () when executing some IO arrows | |||||||||||||||||||||||||||
Global System State Access | |||||||||||||||||||||||||||
getSysParam :: (XIOSysState -> c) -> IOStateArrow s b c | |||||||||||||||||||||||||||
changeSysParam :: (b -> XIOSysState -> XIOSysState) -> IOStateArrow s b b | |||||||||||||||||||||||||||
setParamList :: String -> IOStateArrow s XmlTrees XmlTree | |||||||||||||||||||||||||||
store a list of XML trees in global system state under a given attribute name | |||||||||||||||||||||||||||
setParam :: String -> IOStateArrow s XmlTree XmlTree | |||||||||||||||||||||||||||
store a single XML tree in global state under a given attribute name | |||||||||||||||||||||||||||
unsetParam :: String -> IOStateArrow s b b | |||||||||||||||||||||||||||
remove an entry in global state, arrow input remains unchanged | |||||||||||||||||||||||||||
getParam :: String -> IOStateArrow s b XmlTree | |||||||||||||||||||||||||||
read an attribute value from global state | |||||||||||||||||||||||||||
getAllParams :: IOStateArrow s b (AssocList String XmlTrees) | |||||||||||||||||||||||||||
read all attributes from global state | |||||||||||||||||||||||||||
setParamString :: String -> String -> IOStateArrow s b b | |||||||||||||||||||||||||||
getParamString :: String -> IOStateArrow s b String | |||||||||||||||||||||||||||
read a string value from global state, if parameter not set "" is returned | |||||||||||||||||||||||||||
setParamInt :: String -> Int -> IOStateArrow s b b | |||||||||||||||||||||||||||
store an int value in global state | |||||||||||||||||||||||||||
getParamInt :: Int -> String -> IOStateArrow s b Int | |||||||||||||||||||||||||||
read an int value from global state getParamInt 0 myIntAttr | |||||||||||||||||||||||||||
Error Message Handling | |||||||||||||||||||||||||||
clearErrStatus :: IOStateArrow s b b | |||||||||||||||||||||||||||
setErrStatus :: IOStateArrow s Int Int | |||||||||||||||||||||||||||
set global error variable | |||||||||||||||||||||||||||
getErrStatus :: IOStateArrow s XmlTree Int | |||||||||||||||||||||||||||
read current global error status | |||||||||||||||||||||||||||
setErrMsgStatus :: IOStateArrow s XmlTree XmlTree | |||||||||||||||||||||||||||
raise the global error status level to that of the input tree | |||||||||||||||||||||||||||
setErrorMsgHandler :: Bool -> (String -> IO ()) -> IOStateArrow s b b | |||||||||||||||||||||||||||
set the error message handler and the flag for collecting the errors | |||||||||||||||||||||||||||
errorMsgStderr :: IOStateArrow s b b | |||||||||||||||||||||||||||
the default error message handler: error output to stderr | |||||||||||||||||||||||||||
errorMsgCollect :: IOStateArrow s b b | |||||||||||||||||||||||||||
error message handler for collecting errors | |||||||||||||||||||||||||||
errorMsgStderrAndCollect :: IOStateArrow s b b | |||||||||||||||||||||||||||
error message handler for output to stderr and collecting | |||||||||||||||||||||||||||
errorMsgIgnore :: IOStateArrow s b b | |||||||||||||||||||||||||||
error message handler for ignoring errors | |||||||||||||||||||||||||||
getErrorMessages :: IOStateArrow s b XmlTree | |||||||||||||||||||||||||||
if error messages are collected by the error handler for processing these messages by the calling application, this arrow reads the stored messages and clears the error message store | |||||||||||||||||||||||||||
filterErrorMsg :: IOStateArrow s XmlTree XmlTree | |||||||||||||||||||||||||||
filter error messages from input trees and issue errors | |||||||||||||||||||||||||||
issueWarn :: String -> IOStateArrow s b b | |||||||||||||||||||||||||||
generate a warnig message | |||||||||||||||||||||||||||
issueErr :: String -> IOStateArrow s b b | |||||||||||||||||||||||||||
generate an error message | |||||||||||||||||||||||||||
issueFatal :: String -> IOStateArrow s b b | |||||||||||||||||||||||||||
generate a fatal error message, e.g. document not found | |||||||||||||||||||||||||||
setDocumentStatus :: Int -> String -> IOStateArrow s XmlTree XmlTree | |||||||||||||||||||||||||||
add the error level and the module where the error occured to the attributes of a document root node and remove the children when level is greater or equal to c_err. called by setDocumentStatusFromSystemState when the system state indicates an error | |||||||||||||||||||||||||||
setDocumentStatusFromSystemState :: String -> IOStateArrow s XmlTree XmlTree | |||||||||||||||||||||||||||
check whether the error level attribute in the system state is set to error, in this case the children of the document root are removed and the module name where the error occured and the error level are added as attributes with setDocumentStatus else nothing is changed | |||||||||||||||||||||||||||
documentStatusOk :: ArrowXml a => a XmlTree XmlTree | |||||||||||||||||||||||||||
check whether tree is a document root and the status attribute has a value less than c_err | |||||||||||||||||||||||||||
Document Base | |||||||||||||||||||||||||||
setBaseURI :: IOStateArrow s String String | |||||||||||||||||||||||||||
set the base URI of a document, used e.g. for reading includes, e.g. external entities, the input must be an absolute URI | |||||||||||||||||||||||||||
getBaseURI :: IOStateArrow s b String | |||||||||||||||||||||||||||
read the base URI from the globale state | |||||||||||||||||||||||||||
changeBaseURI :: IOStateArrow s String String | |||||||||||||||||||||||||||
change the base URI with a possibly relative URI, can be used for evaluating the xml:base attribute. Returns the new absolute base URI. Fails, if input is not parsable with parseURIReference see also: setBaseURI, mkAbsURI | |||||||||||||||||||||||||||
setDefaultBaseURI :: String -> IOStateArrow s b String | |||||||||||||||||||||||||||
set the default base URI, if parameter is null, the system base ( file:///<cwd>/ ) is used, else the parameter, must be called before any document is read | |||||||||||||||||||||||||||
getDefaultBaseURI :: IOStateArrow s b String | |||||||||||||||||||||||||||
get the default base URI | |||||||||||||||||||||||||||
runInLocalURIContext :: IOStateArrow s b c -> IOStateArrow s b c | |||||||||||||||||||||||||||
remember base uri, run an arrow and restore the base URI, used with external entity substitution | |||||||||||||||||||||||||||
Tracing | |||||||||||||||||||||||||||
setTraceLevel :: Int -> IOStateArrow s b b | |||||||||||||||||||||||||||
set the global trace level | |||||||||||||||||||||||||||
getTraceLevel :: IOStateArrow s b Int | |||||||||||||||||||||||||||
read the global trace level | |||||||||||||||||||||||||||
withTraceLevel :: Int -> IOStateArrow s b c -> IOStateArrow s b c | |||||||||||||||||||||||||||
run an arrow with a given trace level, the old trace level is restored after the arrow execution | |||||||||||||||||||||||||||
trace :: Int -> IOStateArrow s b String -> IOStateArrow s b b | |||||||||||||||||||||||||||
apply a trace arrow and issue message to stderr | |||||||||||||||||||||||||||
traceMsg :: Int -> String -> IOStateArrow s b b | |||||||||||||||||||||||||||
issue a string message as trace | |||||||||||||||||||||||||||
traceString :: Int -> (String -> String) -> IOStateArrow s String String | |||||||||||||||||||||||||||
issue the string input of an arrow | |||||||||||||||||||||||||||
traceSource :: IOStateArrow s XmlTree XmlTree | |||||||||||||||||||||||||||
issue the source representation of a document if trace level >= 3 for better readability the source is formated with indentDoc | |||||||||||||||||||||||||||
traceTree :: IOStateArrow s XmlTree XmlTree | |||||||||||||||||||||||||||
issue the tree representation of a document if trace level >= 4 | |||||||||||||||||||||||||||
traceDoc :: String -> IOStateArrow s XmlTree XmlTree | |||||||||||||||||||||||||||
trace a main computation step issue a message when trace level >= 1, issue document source if level >= 3, issue tree when level is >= 4 | |||||||||||||||||||||||||||
traceState :: IOStateArrow s b b | |||||||||||||||||||||||||||
trace the global state | |||||||||||||||||||||||||||
URI Manipulation | |||||||||||||||||||||||||||
expandURIString :: String -> String -> Maybe String | |||||||||||||||||||||||||||
compute the absolut URI for a given URI and a base URI | |||||||||||||||||||||||||||
expandURI :: ArrowXml a => a (String, String) String | |||||||||||||||||||||||||||
arrow variant of expandURIString, fails if expandURIString returns Nothing | |||||||||||||||||||||||||||
mkAbsURI :: IOStateArrow s String String | |||||||||||||||||||||||||||
arrow for expanding an input URI into an absolute URI using global base URI, fails if input is not a legal URI | |||||||||||||||||||||||||||
getFragmentFromURI :: ArrowList a => a String String | |||||||||||||||||||||||||||
arrow for computing the fragment component of an URI, fails if input is not a legal URI | |||||||||||||||||||||||||||
getPathFromURI :: ArrowList a => a String String | |||||||||||||||||||||||||||
arrow for computing the path component of an URI, fails if input is not a legal URI | |||||||||||||||||||||||||||
getPortFromURI :: ArrowList a => a String String | |||||||||||||||||||||||||||
arrow for selecting the port number of the URI without leading ':', fails if input is not a legal URI | |||||||||||||||||||||||||||
getQueryFromURI :: ArrowList a => a String String | |||||||||||||||||||||||||||
arrow for computing the query component of an URI, fails if input is not a legal URI | |||||||||||||||||||||||||||
getRegNameFromURI :: ArrowList a => a String String | |||||||||||||||||||||||||||
arrow for selecting the registered name (host) of the URI, fails if input is not a legal URI | |||||||||||||||||||||||||||
getSchemeFromURI :: ArrowList a => a String String | |||||||||||||||||||||||||||
arrow for selecting the scheme (protocol) of the URI, fails if input is not a legal URI. See Network.URI for URI components | |||||||||||||||||||||||||||
getUserInfoFromURI :: ArrowList a => a String String | |||||||||||||||||||||||||||
arrow for selecting the user info of the URI without trailing '@', fails if input is not a legal URI | |||||||||||||||||||||||||||
Produced by Haddock version 0.8 |