Safe Haskell	None
Language	Haskell98

Text.XML

Contents

Data types
Parsing
Rendering
Settings
- Parsing
  - Entity decoding
- Rendering
Conversion

Description

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.

Synopsis

Data types

data Document Source

Constructors

Document
Fields documentPrologue :: Prologue documentRoot :: Element documentEpilogue :: [Miscellaneous]

Instances

Eq Document Source
Data Document Source
Show Document Source
ToMarkup Document Source
NFData Document Source

data Prologue :: *

Constructors

Prologue
Fields prologueBefore :: [Miscellaneous] prologueDoctype :: Maybe Doctype prologueAfter :: [Miscellaneous]

Instances

Eq Prologue
Data Prologue
Ord Prologue
Show Prologue
Generic Prologue
NFData Prologue
type Rep Prologue = D1 D1Prologue (C1 C1_0Prologue ((::) (S1 S1_0_0Prologue (Rec0 [Miscellaneous])) ((::) (S1 S1_0_1Prologue (Rec0 (Maybe Doctype))) (S1 S1_0_2Prologue (Rec0 [Miscellaneous])))))

data Instruction :: *

Constructors

Instruction
Fields instructionTarget :: Text instructionData :: Text

Instances

Eq Instruction
Data Instruction
Ord Instruction
Show Instruction
Generic Instruction
NFData Instruction
type Rep Instruction = D1 D1Instruction (C1 C1_0Instruction ((:*:) (S1 S1_0_0Instruction (Rec0 Text)) (S1 S1_0_1Instruction (Rec0 Text))))

data Miscellaneous :: *

Constructors

MiscInstruction Instruction
MiscComment Text

Instances

Eq Miscellaneous
Data Miscellaneous
Ord Miscellaneous
Show Miscellaneous
Generic Miscellaneous
NFData Miscellaneous
type Rep Miscellaneous = D1 D1Miscellaneous ((:+:) (C1 C1_0Miscellaneous (S1 NoSelector (Rec0 Instruction))) (C1 C1_1Miscellaneous (S1 NoSelector (Rec0 Text))))

data Node Source

Constructors

NodeElement Element
NodeInstruction Instruction
NodeContent Text
NodeComment Text

Instances

Eq Node Source
Data Node Source
Ord Node Source
Show Node Source
ToMarkup Node Source
NFData Node Source

data Element Source

Constructors

Element
Fields elementName :: Name elementAttributes :: Map Name Text elementNodes :: [Node]

Instances

Eq Element Source
Data Element Source
Ord Element Source
Show Element Source
ToMarkup Element Source	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 Source

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
Generic Name
NFData Name
type Rep Name = D1 D1Name (C1 C1_0Name ((::) (S1 S1_0_0Name (Rec0 Text)) ((::) (S1 S1_0_1Name (Rec0 (Maybe Text))) (S1 S1_0_2Name (Rec0 (Maybe Text))))))

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
Generic Doctype
NFData Doctype
type Rep Doctype = D1 D1Doctype (C1 C1_0Doctype ((:*:) (S1 S1_0_0Doctype (Rec0 Text)) (S1 S1_0_1Doctype (Rec0 (Maybe ExternalID)))))

data ExternalID :: *

Constructors

SystemID Text
PublicID Text Text

Instances

Eq ExternalID
Data ExternalID
Ord ExternalID
Show ExternalID
Generic ExternalID
NFData ExternalID
type Rep ExternalID = D1 D1ExternalID ((:+:) (C1 C1_0ExternalID (S1 NoSelector (Rec0 Text))) (C1 C1_1ExternalID ((:*:) (S1 NoSelector (Rec0 Text)) (S1 NoSelector (Rec0 Text)))))

Parsing

Files

readFile :: ParseSettings -> FilePath -> IO Document Source

Bytes

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

parseLBS_ :: ParseSettings -> ByteString -> Document Source

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

Text

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

parseText_ :: ParseSettings -> Text -> Document Source

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

Other

fromEvents :: MonadThrow m => Consumer EventPos m Document Source

data UnresolvedEntityException Source

Constructors

UnresolvedEntityException (Set Text)

Instances

Show UnresolvedEntityException Source
Exception UnresolvedEntityException Source

data XMLException Source

Constructors

InvalidXMLFile FilePath SomeException

Instances

Show XMLException Source
Exception XMLException Source

Rendering

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

renderLBS :: RenderSettings -> Document -> ByteString Source

renderText :: RenderSettings -> Document -> Text Source

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

Settings

def :: Default a => a

The default value for this type.

Parsing

data ParseSettings Source

Instances

Default ParseSettings Source

psDecodeEntities :: ParseSettings -> DecodeEntities Source

psRetainNamespaces :: ParseSettings -> Bool Source

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 Source

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

decodeHtmlEntities :: DecodeEntities Source

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 Source

Instances

Default RenderSettings Source

rsPretty :: RenderSettings -> Bool Source

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

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

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

rsUseCDATA :: RenderSettings -> Content -> Bool Source

Determines if for a given text content the renderer should use a CDATA node.

Default: False

Since: 1.3.3

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

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 Source

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

toXMLNode :: Node -> Node Source

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

toXMLElement :: Element -> Element Source

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