Report a bug If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page Quickly fork, edit online, and submit a pull request for this page.
Requires a signed-in GitHub account. This works well for small changes.
If you'd like to make larger changes you may want to consider using
local clone.

std.xml

Warning: This module is considered out-dated and not up to Phobos'
current standards. It will remain until we have a suitable replacement,
but be aware that it will not remain long term.

Classes and functions for creating and parsing XML

The basic architecture of this module is that there are standalone functions,
classes for constructing an XML document from scratch (Tag, Element and
Document), and also classes for parsing a pre-existing XML file (ElementParser
and DocumentParser). The parsing classes may be used to build a
Document, but that is not their primary purpose. The handling capabilities of
DocumentParser and ElementParser are sufficiently customizable that you can
make them do pretty much whatever you want.

Encodes a string by replacing all characters which need to be escaped with
appropriate predefined XML entities.

encode() escapes certain characters (ampersand, quote, apostrophe, less-than
and greater-than), and similarly, decode() unescapes them. These functions
are provided for convenience only. You do not need to use them when using
the std.xml classes, because then all the encoding and decoding will be done
for you automatically.

encode() escapes certain characters (ampersand, quote, apostrophe, less-than
and greater-than), and similarly, decode() unescapes them. These functions
are provided for convenience only. You do not need to use them when using
the std.xml classes, because then all the encoding and decoding will be done
for you automatically.

This function decodes the entities &amp;, &quot;, &apos;,
&lt; and &gt,
as well as decimal and hexadecimal entities such as &#x20AC;

If the string does not contain an ampersand, the original will be returned.

Note that the "mode" parameter can be one of DecodeMode.NONE (do not
decode), DecodeMode.LOOSE (decode, but ignore errors), or DecodeMode.STRICT
(decode, and throw a DecodeException in the event of an error).

Note that you cannot construct instances of this class directly. You can
construct a DocumentParser (which is a subclass of ElementParser), but
otherwise, Instances of ElementParser will be created for you by the
library, and passed your way via onStartTag handlers.

const @property const(Tag) tag();

The Tag at the start of the element being parsed. You can read this to
determine the tag's name and attributes.

ParserHandler[string] onStartTag;

Register a handler which will be called whenever a start tag is
encountered which matches the specified name. You can also pass null as
the name, in which case the handler will be called for any unmatched
start tag.

This library will supply your function with a new instance of
ElementHandler, which may be used to parse inside the element whose
start tag was just found, or to identify the tag attributes of the
element, etc.

Note that your function will be called for both start tags and empty
tags. That is, we make no distinction between <br></br>
and <br/>.

ElementHandler[string] onEndTag;

Register a handler which will be called whenever an end tag is
encountered which matches the specified name. You can also pass null as
the name, in which case the handler will be called for any unmatched
end tag.

Examples:

// Call this function whenever a </podcast> end tag is encountered
onEndTag["podcast"] = (in Element e)
{
// Your code here
//
// This is a a closure, so code here may reference
// variables which are outside of this scope
};
// call myEpisodeEndHandler (defined elsewhere) whenever an </episode>
// end tag is encountered
onEndTag["episode"] = &myEpisodeEndHandler;
// call delegate dg for all other end tags
onEndTag[null] = dg;

Note that your function will be called for both start tags and empty
tags. That is, we make no distinction between <br></br>
and <br/>.

@property void onText(Handler handler);

Register a handler which will be called whenever text is encountered.

Examples:

// Call this function whenever text is encountered
onText = (string s)
{
// Your code here
// The passed parameter s will have been decoded by the time you see
// it, and so may contain any character.
//
// This is a a closure, so code here may reference
// variables which are outside of this scope
};

void onTextRaw(Handler handler);

Register an alternative handler which will be called whenever text
is encountered. This differs from onText in that onText will decode
the text, whereas onTextRaw will not. This allows you to make design
choices, since onText will be more accurate, but slower, while
onTextRaw will be faster, but less accurate. Of course, you can
still call decode() within your handler, if you want, but you'd
probably want to use onTextRaw only in circumstances where you
know that decoding is unnecessary.

Examples:

// Call this function whenever text is encountered
onText = (string s)
{
// Your code here
// The passed parameter s will NOT have been decoded.
//
// This is a a closure, so code here may reference
// variables which are outside of this scope
};

@property void onCData(Handler handler);

Register a handler which will be called whenever a character data
segment is encountered.

Examples:

// Call this function whenever a CData section is encountered
onCData = (string s)
{
// Your code here
// The passed parameter s does not include the opening <![CDATA[
// nor closing ]]>
//
// This is a a closure, so code here may reference
// variables which are outside of this scope
};

@property void onComment(Handler handler);

Register a handler which will be called whenever a comment is
encountered.

Examples:

// Call this function whenever a comment is encountered
onComment = (string s)
{
// Your code here
// The passed parameter s does not include the opening <!-- nor
// closing -->
//
// This is a a closure, so code here may reference
// variables which are outside of this scope
};

@property void onPI(Handler handler);

Register a handler which will be called whenever a processing
instruction is encountered.

Examples:

// Call this function whenever a processing instruction is encountered
onPI = (string s)
{
// Your code here
// The passed parameter s does not include the opening <? nor
// closing ?>
//
// This is a a closure, so code here may reference
// variables which are outside of this scope
};

@property void onXI(Handler handler);

Register a handler which will be called whenever an XML instruction is
encountered.

Examples:

// Call this function whenever an XML instruction is encountered
// (Note: XML instructions may only occur preceding the root tag of a
// document).
onPI = (string s)
{
// Your code here
// The passed parameter s does not include the opening <! nor
// closing >
//
// This is a a closure, so code here may reference
// variables which are outside of this scope
};

void parse();

Parse an XML element.

Parsing will continue until the end of the current element. Any items
encountered for which a handler has been registered will invoke that
handler.

Throws:

various kinds of XMLException

const string toString();

Returns that part of the element which has already been parsed

void check(string s);

Check an entire XML document for well-formedness

Parameters:

string s

the document to be checked, passed as a string

Throws:

CheckException if the document is not well formed

CheckException's toString() method will yield the complete hierarchy of
parse failure (the XML equivalent of a stack trace), giving the line and
column number of every failure at every level.

class XMLException: object.Exception;

The base class for exceptions thrown by this module

class CommentException: std.xml.XMLException;

Thrown during Comment constructor

class CDataException: std.xml.XMLException;

Thrown during CData constructor

class XIException: std.xml.XMLException;

Thrown during XMLInstruction constructor

class PIException: std.xml.XMLException;

Thrown during ProcessingInstruction constructor

class TextException: std.xml.XMLException;

Thrown during Text constructor

class DecodeException: std.xml.XMLException;

Thrown during decode()

class InvalidTypeException: std.xml.XMLException;

Thrown if comparing with wrong type

class TagException: std.xml.XMLException;

Thrown when parsing for Tags

class CheckException: std.xml.XMLException;

Thrown during check()

CheckException err;

Parent in hierarchy

string msg;

Name of production rule which failed to parse,
or specific error message