Text.XML

DOM-based parsing and rendering.

This module requires that all entities be resolved at parsing. If you need to interact with unresolved entities, please use Text.XML.Unresolved. This is the recommended module for most uses cases.

While many of the datatypes in this module are simply re-exported from Data.XML.Types, Document, Node and Element are all redefined here to disallow the possibility of unresolved entities. Conversion functions are provided to switch between the two sets of datatypes.

For simpler, bidirectional traversal of the DOM tree, see the Text.XML.Cursor module.

Data types

data Document

Constructors

Document

Fields

documentPrologue :: Prologue

documentRoot :: Element

documentEpilogue :: [Miscellaneous]

Instances

Eq Document

Data Document

Show Document

ToMarkup Document

NFData Document

Typeable * Document

data Prologue :: *

Constructors

Prologue

Fields

prologueBefore :: [Miscellaneous]

prologueDoctype :: Maybe Doctype

prologueAfter :: [Miscellaneous]

Instances

Eq Prologue

Data Prologue

Ord Prologue

Show Prologue

NFData Prologue

Typeable * Prologue

data Instruction :: *

Constructors

Instruction

Fields

instructionTarget :: Text

instructionData :: Text

Instances

Eq Instruction

Data Instruction

Ord Instruction

Show Instruction

NFData Instruction

Typeable * Instruction

data Miscellaneous :: *

Constructors

MiscInstruction Instruction

MiscComment Text

Instances

Eq Miscellaneous

Data Miscellaneous

Ord Miscellaneous

Show Miscellaneous

NFData Miscellaneous

Typeable * Miscellaneous

data Node

Constructors

NodeElement Element

NodeInstruction Instruction

NodeContent Text

NodeComment Text

Instances

Eq Node

Data Node

Ord Node

Show Node

ToMarkup Node

NFData Node

Typeable * Node

data Element

Constructors

Element

Fields

elementName :: Name

elementAttributes :: Map Name Text

elementNodes :: [Node]

Instances

Eq Element

Data Element

Ord Element

Show Element

ToMarkup Element

Note that the special element name {http:/www.snoyman.comxml2html}ie-cond with the single attribute cond is used to indicate an IE conditional comment.

NFData Element

Typeable * Element

data Name :: *

A fully qualified name.

Prefixes are not semantically important; they are included only to simplify pass-through parsing. When comparing names with Eq or Ord methods, prefixes are ignored.

The IsString instance supports Clark notation; see http://www.jclark.com/xml/xmlns.htm and http://infohost.nmt.edu/tcc/help/pubs/pylxml/etree-QName.html. Use the OverloadedStrings language extension for very simple Name construction:

myname :: Name
myname = "{http://example.com/ns/my-namespace}my-name"

Constructors

Name

Fields

nameLocalName :: Text

nameNamespace :: Maybe Text

namePrefix :: Maybe Text

Instances

Eq Name

Data Name

Ord Name

Show Name

IsString Name

NFData Name

Typeable * Name

data Doctype :: *

Note: due to the incredible complexity of DTDs, this type only supports external subsets. I've tried adding internal subset types, but they quickly gain more code than the rest of this module put together.

It is possible that some future version of this library might support internal subsets, but I am no longer actively working on adding them.

Constructors

Doctype

Fields

doctypeName :: Text

doctypeID :: Maybe ExternalID

Instances

Eq Doctype

Data Doctype

Ord Doctype

Show Doctype

NFData Doctype

Typeable * Doctype

data ExternalID :: *

Constructors

SystemID Text

PublicID Text Text

Instances

Eq ExternalID

Data ExternalID

Ord ExternalID

Show ExternalID

NFData ExternalID

Typeable * ExternalID

Parsing

Files

readFile :: ParseSettings -> FilePath -> IO Document

Bytes

parseLBS :: ParseSettings -> ByteString -> Either SomeException Document

parseLBS_ :: ParseSettings -> ByteString -> Document

sinkDoc :: MonadThrow m => ParseSettings -> Consumer ByteString m Document

Text

parseText :: ParseSettings -> Text -> Either SomeException Document

parseText_ :: ParseSettings -> Text -> Document

sinkTextDoc :: MonadThrow m => ParseSettings -> Consumer Text m Document

Other

fromEvents :: MonadThrow m => Consumer EventPos m Document

data UnresolvedEntityException

Constructors

UnresolvedEntityException (Set Text)

Instances

Show UnresolvedEntityException

Exception UnresolvedEntityException

Typeable * UnresolvedEntityException

data XMLException

Constructors

InvalidXMLFile FilePath SomeException

Instances

Show XMLException

Exception XMLException

Typeable * XMLException

Rendering

writeFile :: RenderSettings -> FilePath -> Document -> IO ()

renderLBS :: RenderSettings -> Document -> ByteString

renderText :: RenderSettings -> Document -> Text

renderBytes :: (PrimMonad base, MonadBase base m) => RenderSettings -> Document -> ConduitM a ByteString m ()

Settings

def :: Default a => a

The default value for this type.

Parsing

data ParseSettings

Instances

Default ParseSettings

psDecodeEntities :: ParseSettings -> DecodeEntities

psRetainNamespaces :: ParseSettings -> Bool

Whether the original xmlns attributes should be retained in the parsed values. For more information on motivation, see:

https://github.com/snoyberg/xml/issues/38

Default: False

Since 1.2.1

Entity decoding

decodeXmlEntities :: DecodeEntities

Default implementation of DecodeEntities: handles numeric entities and the five standard character entities (lt, gt, amp, quot, apos).

decodeHtmlEntities :: DecodeEntities

HTML4-compliant entity decoder. Handles numerics, the five standard character entities, and the additional 248 entities defined by HTML 4 and XHTML 1.

Note that HTML 5 introduces a drastically larger number of entities, and this code does not recognize most of them.

Rendering

data RenderSettings

Instances

Default RenderSettings

rsPretty :: RenderSettings -> Bool

rsNamespaces :: RenderSettings -> [(Text, Text)]

Defines some top level namespace definitions to be used, in the form of (prefix, namespace). This has absolutely no impact on the meaning of your documents, but can increase readability by moving commonly used namespace declarations to the top level.

rsAttrOrder :: RenderSettings -> Name -> Map Name Text -> [(Name, Text)]

Specify how to turn the unordered attributes used by the Text.XML module into an ordered list.

orderAttrs :: [(Name, [Name])] -> Name -> Map Name Text -> [(Name, Text)]

Convenience function to create an ordering function suitable for use as the value of rsAttrOrder. The ordering function is created from an explicit ordering of the attributes, specified as a list of tuples, as follows: In each tuple, the first component is the Name of an element, and the second component is a list of attributes names. When the given element is rendered, the attributes listed, when present, appear first in the given order, followed by any other attributes in arbitrary order. If an element does not appear, all of its attributes are rendered in arbitrary order.

Conversion

toXMLDocument :: Document -> Document

fromXMLDocument :: Document -> Either (Set Text) Document

toXMLNode :: Node -> Node

fromXMLNode :: Node -> Either (Set Text) Node

toXMLElement :: Element -> Element

fromXMLElement :: Element -> Either (Set Text) Element