| hxt-8.5.4: A collection of tools for processing XML with Haskell. | Source code | Contents | Index

Text.XML.HXT.Arrow.XmlIOStateArrow

Portability | portable
Stability | stable
Maintainer | Uwe Schmidt (uwe@fh-wedel.de)

Contents

Data Types
Running Arrows
User State Manipulation
Global System State Access
Error Message Handling
Document Base
Tracing
URI Manipulation
Mime Type Handling

Description

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 XIOState us = XIOState {

xio_sysState :: !XIOSysState
xio_userState :: !us

}

data XIOSysState = XIOSys {

xio_trace :: !Int
xio_traceCmd :: Int -> String -> IO ()
xio_errorStatus :: !Int
xio_errorModule :: !String
xio_errorMsgHandler :: String -> IO ()
xio_errorMsgCollect :: !Bool
xio_errorMsgList :: !XmlTrees
xio_baseURI :: !String
xio_defaultBaseURI :: !String
xio_attrList :: !(AssocList String XmlTrees)
xio_mimeTypes :: MimeTypeTable

}

type IOStateArrow s b c = IOSLA (XIOState s) b c
type IOSArrow b c = IOStateArrow () b c
initialState :: us -> XIOState us
initialSysState :: XIOSysState
runX :: IOSArrow XmlTree c -> IO [c]
getUserState :: IOStateArrow s b s
setUserState :: IOStateArrow s s s
changeUserState :: (b -> s -> s) -> IOStateArrow s b b
withExtendedUserState :: s1 -> IOStateArrow (s1, s0) b c -> IOStateArrow s0 b c
withOtherUserState :: s1 -> IOStateArrow s1 b c -> IOStateArrow s0 b c
getSysParam :: (XIOSysState -> c) -> IOStateArrow s b c
changeSysParam :: (b -> XIOSysState -> XIOSysState) -> IOStateArrow s b b
setParamList :: String -> IOStateArrow s XmlTrees XmlTree
setParam :: String -> IOStateArrow s XmlTree XmlTree
unsetParam :: String -> IOStateArrow s b b
getParam :: String -> IOStateArrow s b XmlTree
getAllParams :: IOStateArrow s b (AssocList String XmlTrees)
getAllParamsString :: IOStateArrow s b (AssocList String String)
setParamString :: String -> String -> IOStateArrow s b b
getParamString :: String -> IOStateArrow s b String
setParamInt :: String -> Int -> IOStateArrow s b b
getParamInt :: Int -> String -> IOStateArrow s b Int
clearErrStatus :: IOStateArrow s b b
setErrStatus :: IOStateArrow s Int Int
getErrStatus :: IOStateArrow s XmlTree Int
setErrMsgStatus :: IOStateArrow s XmlTree XmlTree
setErrorMsgHandler :: Bool -> (String -> IO ()) -> IOStateArrow s b b
errorMsgStderr :: IOStateArrow s b b
errorMsgCollect :: IOStateArrow s b b
errorMsgStderrAndCollect :: IOStateArrow s b b
errorMsgIgnore :: IOStateArrow s b b
getErrorMessages :: IOStateArrow s b XmlTree
filterErrorMsg :: IOStateArrow s XmlTree XmlTree
issueWarn :: String -> IOStateArrow s b b
issueErr :: String -> IOStateArrow s b b
issueFatal :: String -> IOStateArrow s b b
setDocumentStatus :: Int -> String -> IOStateArrow s XmlTree XmlTree
setDocumentStatusFromSystemState :: String -> IOStateArrow s XmlTree XmlTree
documentStatusOk :: ArrowXml a => a XmlTree XmlTree
setBaseURI :: IOStateArrow s String String
getBaseURI :: IOStateArrow s b String
changeBaseURI :: IOStateArrow s String String
setDefaultBaseURI :: String -> IOStateArrow s b String
getDefaultBaseURI :: IOStateArrow s b String
runInLocalURIContext :: IOStateArrow s b c -> IOStateArrow s b c
setTraceLevel :: Int -> IOStateArrow s b b
getTraceLevel :: IOStateArrow s b Int
withTraceLevel :: Int -> IOStateArrow s b c -> IOStateArrow s b c
setTraceCmd :: (Int -> String -> IO ()) -> IOStateArrow s b b
getTraceCmd :: IOStateArrow a b (Int -> String -> IO ())
trace :: Int -> IOStateArrow s b String -> IOStateArrow s b b
traceMsg :: Int -> String -> IOStateArrow s b b
traceValue :: Int -> (b -> String) -> IOStateArrow s b b
traceString :: Int -> (b -> String) -> IOStateArrow s b b
traceSource :: IOStateArrow s XmlTree XmlTree
traceTree :: IOStateArrow s XmlTree XmlTree
traceDoc :: String -> IOStateArrow s XmlTree XmlTree
traceState :: IOStateArrow s b b
expandURIString :: String -> String -> Maybe String
expandURI :: ArrowXml a => a (String, String) String
mkAbsURI :: IOStateArrow s String String
getFragmentFromURI :: ArrowList a => a String String
getPathFromURI :: ArrowList a => a String String
getPortFromURI :: ArrowList a => a String String
getQueryFromURI :: ArrowList a => a String String
getRegNameFromURI :: ArrowList a => a String String
getSchemeFromURI :: ArrowList a => a String String
getUserInfoFromURI :: ArrowList a => a String String
setMimeTypeTable :: MimeTypeTable -> IOStateArrow s b b
setMimeTypeTableFromFile :: FilePath -> IOStateArrow s b b

Data Types

data XIOState us | Source

state datatype consists of a system state and a user state the user state is not fixed
Constructors

XIOState |

xio_sysState :: !XIOSysState |
xio_userState :: !us |

Instances

NFData us => NFData (XIOState us)

data XIOSysState | Source

predefined system state data type with all components for the system functions, like trace, error handling, ...
Constructors

XIOSys |

xio_trace :: !Int |
xio_traceCmd :: Int -> String -> IO () |
xio_errorStatus :: !Int |
xio_errorModule :: !String |
xio_errorMsgHandler :: String -> IO () |
xio_errorMsgCollect :: !Bool |
xio_errorMsgList :: !XmlTrees |
xio_baseURI :: !String |
xio_defaultBaseURI :: !String |
xio_attrList :: !(AssocList String XmlTrees) |
xio_mimeTypes :: MimeTypeTable |

Instances

NFData XIOSysState

type IOStateArrow s b c = IOSLA (XIOState s) b c | Source

The arrow type for stateful arrows

type IOSArrow b c = IOStateArrow () b c | Source

The arrow for stateful arrows with no user defined state
Running Arrows

initialState :: us -> XIOState us | Source

the default global state, used as initial state when running an `IOSArrow` with `runIOSLA` or `runX`

initialSysState :: XIOSysState | Source

runX :: IOSArrow XmlTree c -> IO [c] | Source

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 Text.XML.HXT.Arrow.ReadDocument.readDocument arrow.

for usage see examples with Text.XML.HXT.Arrow.WriteDocument.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 | Source

read the user defined part of the state

setUserState :: IOStateArrow s s s | Source

set the user defined part of the state

changeUserState :: (b -> s -> s) -> IOStateArrow s b b | Source

change the user defined part of the state

withExtendedUserState :: s1 -> IOStateArrow (s1, s0) b c -> IOStateArrow s0 b c | Source

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 | Source

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 | Source

changeSysParam :: (b -> XIOSysState -> XIOSysState) -> IOStateArrow s b b | Source

setParamList :: String -> IOStateArrow s XmlTrees XmlTree | Source

store a list of XML trees in global system state under a given attribute name

setParam :: String -> IOStateArrow s XmlTree XmlTree | Source

store a single XML tree in global state under a given attribute name

unsetParam :: String -> IOStateArrow s b b | Source

remove an entry in global state, arrow input remains unchanged

getParam :: String -> IOStateArrow s b XmlTree | Source

read an attribute value from global state

getAllParams :: IOStateArrow s b (AssocList String XmlTrees) | Source

read all attributes from global state

getAllParamsString :: IOStateArrow s b (AssocList String String) | Source

read all attributes from global state and convert the values to strings

setParamString :: String -> String -> IOStateArrow s b b | Source

getParamString :: String -> IOStateArrow s b String | Source

read a string value from global state, if parameter not set "" is returned

setParamInt :: String -> Int -> IOStateArrow s b b | Source

store an int value in global state

getParamInt :: Int -> String -> IOStateArrow s b Int | Source

read an int value from global state

     getParamInt 0 myIntAttr

Error Message Handling

clearErrStatus :: IOStateArrow s b b | Source

setErrStatus :: IOStateArrow s Int Int | Source

set global error variable

getErrStatus :: IOStateArrow s XmlTree Int | Source

read current global error status

setErrMsgStatus :: IOStateArrow s XmlTree XmlTree | Source

raise the global error status level to that of the input tree

setErrorMsgHandler :: Bool -> (String -> IO ()) -> IOStateArrow s b b | Source

set the error message handler and the flag for collecting the errors

errorMsgStderr :: IOStateArrow s b b | Source

the default error message handler: error output to stderr

errorMsgCollect :: IOStateArrow s b b | Source

error message handler for collecting errors

errorMsgStderrAndCollect :: IOStateArrow s b b | Source

error message handler for output to stderr and collecting

errorMsgIgnore :: IOStateArrow s b b | Source

error message handler for ignoring errors

getErrorMessages :: IOStateArrow s b XmlTree | Source

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 | Source

filter error messages from input trees and issue errors

issueWarn :: String -> IOStateArrow s b b | Source

generate a warnig message

issueErr :: String -> IOStateArrow s b b | Source

generate an error message

issueFatal :: String -> IOStateArrow s b b | Source

generate a fatal error message, e.g. document not found

setDocumentStatus :: Int -> String -> IOStateArrow s XmlTree XmlTree | Source

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 | Source

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 | Source

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 | Source

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 | Source

read the base URI from the globale state

changeBaseURI :: IOStateArrow s String String | Source

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 | Source

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 | Source

get the default base URI

runInLocalURIContext :: IOStateArrow s b c -> IOStateArrow s b c | Source

remember base uri, run an arrow and restore the base URI, used with external entity substitution
Tracing

setTraceLevel :: Int -> IOStateArrow s b b | Source

set the global trace level

getTraceLevel :: IOStateArrow s b Int | Source

read the global trace level

withTraceLevel :: Int -> IOStateArrow s b c -> IOStateArrow s b c | Source

run an arrow with a given trace level, the old trace level is restored after the arrow execution

setTraceCmd :: (Int -> String -> IO ()) -> IOStateArrow s b b | Source

set the global trace command. This command does the trace output

getTraceCmd :: IOStateArrow a b (Int -> String -> IO ()) | Source

acces the command for trace output

trace :: Int -> IOStateArrow s b String -> IOStateArrow s b b | Source

apply a trace arrow and issue message to stderr

traceMsg :: Int -> String -> IOStateArrow s b b | Source

issue a string message as trace

traceValue :: Int -> (b -> String) -> IOStateArrow s b b | Source

trace the current value transfered in a sequence of arrows. The value is formated by a string conversion function. This is a substitute for the old and less general traceString function

traceString :: Int -> (b -> String) -> IOStateArrow s b b | Source

an old alias for `traceValue`

traceSource :: IOStateArrow s XmlTree XmlTree | Source

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 | Source

issue the tree representation of a document if trace level >= 4

traceDoc :: String -> IOStateArrow s XmlTree XmlTree | Source

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 | Source

trace the global state
URI Manipulation

expandURIString :: String -> String -> Maybe String | Source

compute the absolut URI for a given URI and a base URI

expandURI :: ArrowXml a => a (String, String) String | Source

arrow variant of `expandURIString`, fails if `expandURIString` returns Nothing

mkAbsURI :: IOStateArrow s String String | Source

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 | Source

arrow for computing the fragment component of an URI, fails if input is not a legal URI

getPathFromURI :: ArrowList a => a String String | Source

arrow for computing the path component of an URI, fails if input is not a legal URI

getPortFromURI :: ArrowList a => a String String | Source

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 | Source

arrow for computing the query component of an URI, fails if input is not a legal URI

getRegNameFromURI :: ArrowList a => a String String | Source

arrow for selecting the registered name (host) of the URI, fails if input is not a legal URI

getSchemeFromURI :: ArrowList a => a String String | Source

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 | Source

arrow for selecting the user info of the URI without trailing '@', fails if input is not a legal URI
Mime Type Handling

setMimeTypeTable :: MimeTypeTable -> IOStateArrow s b b | Source

set the table mapping of file extensions to mime types in the system state Default table is defined in Text.XML.HXT.DOM.MimeTypeDefaults. This table is used when reading loacl files, (file: protocol) to determine the mime type

setMimeTypeTableFromFile :: FilePath -> IOStateArrow s b b | Source

set the table mapping of file extensions to mime types by an external config file

The config file must follow the conventions of etcmime.types on a debian linux system, that means all empty lines and all lines starting with a # are ignored. The other lines must consist of a mime type followed by a possible empty list of extensions. The list of extenstions and mime types overwrites the default list in the system state of the IOStateArrow

Produced by Haddock version 2.4.2