hxt-9.0.1: A collection of tools for processing XML with Haskell.Source codeContentsIndex
Text.XML.HXT.Arrow.XmlState
Portabilityportable
Stabilitystable
MaintainerUwe Schmidt (uwe@fh-wedel.de)
Contents
Data Types
User State Manipulation
Run IO State arrows
Global System State Configuration and Access
Error Handling
Tracing
Document Base
URI Manipulation
Mime Type Handling
Description
the interface for the basic state maipulation functions
Synopsis
data XIOState us
data XIOSysState
type IOStateArrow s b c = IOSLA (XIOState s) b c
type IOSArrow b c = IOStateArrow () b c
type SysConfig = XIOSysState -> XIOSysState
type SysConfigList = [SysConfig]
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
withoutUserState :: IOSArrow b c -> IOStateArrow s0 b c
runX :: IOSArrow XmlTree c -> IO [c]
configSysVars :: SysConfigList -> IOStateArrow s c c
setSysAttr :: String -> IOStateArrow s String String
unsetSysAttr :: String -> IOStateArrow s b b
getSysAttr :: String -> IOStateArrow s b String
getAllSysAttrs :: IOStateArrow s b Attributes
setSysAttrString :: String -> String -> IOStateArrow s b b
setSysAttrInt :: String -> Int -> IOStateArrow s b b
getSysAttrInt :: Int -> String -> IOStateArrow s b Int
getConfigAttr :: String -> SysConfigList -> String
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
issueExc :: String -> IOStateArrow s SomeException b
setDocumentStatus :: Int -> String -> IOStateArrow s XmlTree XmlTree
setDocumentStatusFromSystemState :: String -> IOStateArrow s XmlTree XmlTree
documentStatusOk :: ArrowXml a => a XmlTree XmlTree
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
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
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
getMimeTypeTable :: IOStateArrow s b MimeTypeTable
setMimeTypeTable :: MimeTypeTable -> IOStateArrow s b b
setMimeTypeTableFromFile :: FilePath -> IOStateArrow s b b
yes :: Bool
no :: Bool
withAcceptedMimeTypes :: [String] -> SysConfig
withAddDefaultDTD :: Bool -> SysConfig
withSysAttr :: String -> String -> SysConfig
withCanonicalize :: Bool -> SysConfig
withCompression :: (CompressionFct, DeCompressionFct) -> SysConfig
withCheckNamespaces :: Bool -> SysConfig
withDefaultBaseURI :: String -> SysConfig
withEncodingErrors :: Bool -> SysConfig
withErrors :: Bool -> SysConfig
withFileMimeType :: String -> SysConfig
withIgnoreNoneXmlContents :: Bool -> SysConfig
withIndent :: Bool -> SysConfig
withInputEncoding :: String -> SysConfig
withInputOption :: String -> String -> SysConfig
withInputOptions :: Attributes -> SysConfig
withMimeTypeFile :: String -> SysConfig
withNoEmptyElemFor :: [String] -> SysConfig
withXmlPi :: Bool -> SysConfig
withOutputEncoding :: String -> SysConfig
withOutputXML :: SysConfig
withOutputHTML :: SysConfig
withOutputXHTML :: SysConfig
withOutputPLAIN :: SysConfig
withParseByMimeType :: Bool -> SysConfig
withParseHTML :: Bool -> SysConfig
withPreserveComment :: Bool -> SysConfig
withProxy :: String -> SysConfig
withRedirect :: Bool -> SysConfig
withRemoveWS :: Bool -> SysConfig
withShowHaskell :: Bool -> SysConfig
withShowTree :: Bool -> SysConfig
withStrictInput :: Bool -> SysConfig
withTextMode :: Bool -> SysConfig
withTrace :: Int -> SysConfig
withValidate :: Bool -> SysConfig
withWarnings :: Bool -> SysConfig
Data Types
data XIOState us Source
state datatype consists of a system state and a user state the user state is not fixed
data XIOSysState Source
predefined system state data type with all components for the system functions, like trace, error handling, ...
type IOStateArrow s b c = IOSLA (XIOState s) b cSource
The arrow type for stateful arrows
type IOSArrow b c = IOStateArrow () b cSource
The arrow for stateful arrows with no user defined state
type SysConfig = XIOSysState -> XIOSysStateSource
type SysConfigList = [SysConfig]Source
User State Manipulation
getUserState :: IOStateArrow s b sSource
read the user defined part of the state
setUserState :: IOStateArrow s s sSource
set the user defined part of the state
changeUserState :: (b -> s -> s) -> IOStateArrow s b bSource
change the user defined part of the state
withExtendedUserState :: s1 -> IOStateArrow (s1, s0) b c -> IOStateArrow s0 b cSource

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 cSource

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

withoutUserState :: IOSArrow b c -> IOStateArrow s0 b cSource
Run IO State arrows
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

Global System State Configuration and Access
configSysVars :: SysConfigList -> IOStateArrow s c cSource
setSysAttr :: String -> IOStateArrow s String StringSource
store a string in global state under a given attribute name
unsetSysAttr :: String -> IOStateArrow s b bSource
remove an entry in global state, arrow input remains unchanged
getSysAttr :: String -> IOStateArrow s b StringSource
read an attribute value from global state
getAllSysAttrs :: IOStateArrow s b AttributesSource
read all attributes from global state
setSysAttrString :: String -> String -> IOStateArrow s b bSource
setSysAttrInt :: String -> Int -> IOStateArrow s b bSource
store an int value in global state
getSysAttrInt :: Int -> String -> IOStateArrow s b IntSource

read an int value from global state

 getSysAttrInt 0 myIntAttr
getConfigAttr :: String -> SysConfigList -> StringSource
Error Handling
clearErrStatus :: IOStateArrow s b bSource
reset global error variable
setErrStatus :: IOStateArrow s Int IntSource
set global error variable
getErrStatus :: IOStateArrow s XmlTree IntSource
read current global error status
setErrMsgStatus :: IOStateArrow s XmlTree XmlTreeSource
raise the global error status level to that of the input tree
setErrorMsgHandler :: Bool -> (String -> IO ()) -> IOStateArrow s b bSource
set the error message handler and the flag for collecting the errors
errorMsgStderr :: IOStateArrow s b bSource
the default error message handler: error output to stderr
errorMsgCollect :: IOStateArrow s b bSource
error message handler for collecting errors
errorMsgStderrAndCollect :: IOStateArrow s b bSource
error message handler for output to stderr and collecting
errorMsgIgnore :: IOStateArrow s b bSource
error message handler for ignoring errors
getErrorMessages :: IOStateArrow s b XmlTreeSource
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 XmlTreeSource
filter error messages from input trees and issue errors
issueWarn :: String -> IOStateArrow s b bSource
generate a warnig message
issueErr :: String -> IOStateArrow s b bSource
generate an error message
issueFatal :: String -> IOStateArrow s b bSource
generate a fatal error message, e.g. document not found
issueExc :: String -> IOStateArrow s SomeException bSource

Default exception handler: issue a fatal error message and fail.

The parameter can be used to specify where the error occured

setDocumentStatus :: Int -> String -> IOStateArrow s XmlTree XmlTreeSource
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 XmlTreeSource
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 XmlTreeSource
check whether tree is a document root and the status attribute has a value less than c_err
Tracing
setTraceLevel :: Int -> IOStateArrow s b bSource
set the global trace level
getTraceLevel :: IOStateArrow s b IntSource
read the global trace level
withTraceLevel :: Int -> IOStateArrow s b c -> IOStateArrow s b cSource
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 bSource
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 bSource
apply a trace arrow and issue message to stderr
traceMsg :: Int -> String -> IOStateArrow s b bSource
issue a string message as trace
traceValue :: Int -> (b -> String) -> IOStateArrow s b bSource

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 bSource
an old alias for traceValue
traceSource :: IOStateArrow s XmlTree XmlTreeSource

issue the source representation of a document if trace level >= 3

for better readability the source is formated with indentDoc

traceTree :: IOStateArrow s XmlTree XmlTreeSource
issue the tree representation of a document if trace level >= 4
traceDoc :: String -> IOStateArrow s XmlTree XmlTreeSource
trace a main computation step issue a message when trace level >= 1, issue document source if level >= 3, issue tree when level is >= 4
Document Base
setBaseURI :: IOStateArrow s String StringSource
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 StringSource
read the base URI from the globale state
changeBaseURI :: IOStateArrow s String StringSource

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 StringSource
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 StringSource
get the default base URI
runInLocalURIContext :: IOStateArrow s b c -> IOStateArrow s b cSource
remember base uri, run an arrow and restore the base URI, used with external entity substitution
URI Manipulation
expandURIString :: String -> String -> Maybe StringSource
compute the absolut URI for a given URI and a base URI
expandURI :: ArrowXml a => a (String, String) StringSource
arrow variant of expandURIString, fails if expandURIString returns Nothing
mkAbsURI :: IOStateArrow s String StringSource
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 StringSource
arrow for computing the fragment component of an URI, fails if input is not a legal URI
getPathFromURI :: ArrowList a => a String StringSource
arrow for computing the path component of an URI, fails if input is not a legal URI
getPortFromURI :: ArrowList a => a String StringSource
arrow for selecting the port number of the URI without leading ':', fails if input is not a legal URI
getQueryFromURI :: ArrowList a => a String StringSource
arrow for computing the query component of an URI, fails if input is not a legal URI
getRegNameFromURI :: ArrowList a => a String StringSource
arrow for selecting the registered name (host) of the URI, fails if input is not a legal URI
getSchemeFromURI :: ArrowList a => a String StringSource

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 StringSource
arrow for selecting the user info of the URI without trailing '@', fails if input is not a legal URI
Mime Type Handling
getMimeTypeTable :: IOStateArrow s b MimeTypeTableSource
read the system mimetype table
setMimeTypeTable :: MimeTypeTable -> IOStateArrow s b bSource

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 bSource

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

yes :: BoolSource
no :: BoolSource
withAcceptedMimeTypes :: [String] -> SysConfigSource
withAddDefaultDTD :: Bool -> SysConfigSource
withSysAttr :: String -> String -> SysConfigSource
withSysAttr key value : store an arbitarty key value pair in system state
withCanonicalize :: Bool -> SysConfigSource
withCanonicalize yes/no : read option, canonicalize document, default is yes
withCompression :: (CompressionFct, DeCompressionFct) -> SysConfigSource
Configure compression and decompression for binary serialization/deserialization. First component is the compression function applied after serialization, second the decompression applied before deserialization.
withCheckNamespaces :: Bool -> SysConfigSource
withCheckNamespaces yes/no: read option, check namespaces, default is no
withDefaultBaseURI :: String -> SysConfigSource

withDefaultBaseURI URI , input option, set the default base URI

This option can be useful when parsing documents from stdin or contained in a string, and interpreting relative URIs within the document

withEncodingErrors :: Bool -> SysConfigSource
withEncodingErrors yes/no : input option, ignore all encoding errors, default is no
withErrors :: Bool -> SysConfigSource
withErrors yes/no : system option for suppressing error messages, default is no
withFileMimeType :: String -> SysConfigSource

Force a given mime type for all file contents.

The mime type for file access will then not be computed by looking into a mime.types file

withIgnoreNoneXmlContents :: Bool -> SysConfigSource

withIgnoreNoneXmlContents yes/no : input option, ignore document contents of none XML/HTML documents.

This option can be useful for implementing crawler like applications, e.g. an URL checker. In those cases net traffic can be reduced.

withIndent :: Bool -> SysConfigSource
withIndent yes/no : output option, indent document before output, default is no
withInputEncoding :: String -> SysConfigSource

withInputEncoding encodingName : input option

Set default document encoding (utf8, isoLatin1, usAscii, iso8859_2, ... , iso8859_16, ...). Only XML, HTML and text documents are decoded, default decoding for XML/HTML is utf8, for text iso latin1 (no decoding).

withInputOption :: String -> String -> SysConfigSource
withInputOptions :: Attributes -> SysConfigSource
withMimeTypeFile :: String -> SysConfigSource
withMimeTypeFile filename : input option, set the mime type table for file: documents by given file. The format of this config file must be in the syntax of a debian linux "mime.types" config file
withNoEmptyElemFor :: [String] -> SysConfigSource
withXmlPi :: Bool -> SysConfigSource
withOutputEncoding :: String -> SysConfigSource
withOutputEncoding encoding , output option, default is the default input encoding or utf8, if input encoding is not set
withOutputXML :: SysConfigSource

withOutputXML : output option, default writing

Default is writing XML: quote special XML chars >,<,",',& where neccessary, add XML processing instruction and encode document with respect to withOutputEncoding

withOutputHTML :: SysConfigSource
Write XHTML: quote all special XML chars, use HTML entity refs or char refs for none ASCII chars
withOutputXHTML :: SysConfigSource
Write XML: quote only special XML chars, don't substitute chars by HTML entities, and don't generate empty elements for HTML elements, which may contain any contents, e.g. script src=...></script>@ instead of @<script src=... /
withOutputPLAIN :: SysConfigSource
suppreses all char and entitiy substitution
withParseByMimeType :: Bool -> SysConfigSource

withParseByMimeType yes/no : read option, select the parser by the mime type of the document (pulled out of the HTTP header).

When the mime type is set to "text/html" the configured HTML parser is taken, when it's set to "text/xml" or "text/xhtml" the configured XML parser is taken. If the mime type is something else, no further processing is performed, the contents is given back to the application in form of a single text node. If the default document encoding is set to isoLatin1, this even enables processing of arbitray binary data.

withParseHTML :: Bool -> SysConfigSource
withParseHTML yes/no: read option, use HTML parser, default is no (use XML parser)
withPreserveComment :: Bool -> SysConfigSource
withPreserveComment yes/no : read option, preserve comments during canonicalization, default is no
withProxy :: String -> SysConfigSource
withProxy "host:port" : input option, configure a proxy for HTTP access, e.g. www-cache:3128
withRedirect :: Bool -> SysConfigSource
withRedirect yes/no : input option, automatically follow redirected URIs, default is yes
withRemoveWS :: Bool -> SysConfigSource
withRemoveWS yes/no : read and write option, remove all whitespace, used for document indentation, default is no
withShowHaskell :: Bool -> SysConfigSource
withShowTree :: Bool -> SysConfigSource
withStrictInput :: Bool -> SysConfigSource
withStrictInput yes/no : input option, input of file and HTTP contents is read eagerly, default is no
withTextMode :: Bool -> SysConfigSource
withTrace :: Int -> SysConfigSource
withTace level : system option, set the trace level, (0..4)
withValidate :: Bool -> SysConfigSource
withValidate yes/no: read option, validate document againsd DTD, default is yes
withWarnings :: Bool -> SysConfigSource
withWarnings yes/no : system option, issue warnings during reading, HTML parsing and processing, default is yes
Produced by Haddock version 2.6.1