undead.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 <i>may</i> 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.

Members

Classes

CData
class CData

Class representing a Character Data section

CDataException
class CDataException

Thrown during CData constructor

CheckException
class CheckException

Thrown during check()

Comment
class Comment

Class representing a comment

CommentException
class CommentException

Thrown during Comment constructor

DecodeException
class DecodeException

Thrown during decode()

Document
class Document

Class representing an XML document.

DocumentParser
class DocumentParser

Class for parsing an XML Document.

Element
class Element

Class representing an XML element.

ElementParser
class ElementParser

Class for parsing an XML element.

InvalidTypeException
class InvalidTypeException

Thrown if comparing with wrong type

Item
class Item

Abstract base class for XML items

PIException
class PIException

Thrown during ProcessingInstruction constructor

ProcessingInstruction
class ProcessingInstruction

Class representing a Processing Instruction section

Tag
class Tag

Class representing an XML tag.

TagException
class TagException

Thrown when parsing for Tags

Text
class Text

Class representing a text (aka Parsed Character Data) section

TextException
class TextException

Thrown during Text constructor

XIException
class XIException

Thrown during XMLInstruction constructor

XMLException
class XMLException

The base class for exceptions thrown by this module

XMLInstruction
class XMLInstruction

Class representing an XML Instruction section

Enums

DecodeMode
enum DecodeMode

Mode to use for decoding.

TagType
enum TagType

Tag types.

Functions

check
void check(string s)

Check an entire XML document for well-formedness

decode
string decode(string s, DecodeMode mode)

Decodes a string by unescaping all predefined XML entities.

encode
S encode(S s)

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

isBaseChar
bool isBaseChar(dchar c)

Returns true if the character is a base character according to the XML standard

isChar
bool isChar(dchar c)

Returns true if the character is a character according to the XML standard

isCombiningChar
bool isCombiningChar(dchar c)

Returns true if the character is a combining character according to the XML standard

isDigit
bool isDigit(dchar c)

Returns true if the character is a digit according to the XML standard

isExtender
bool isExtender(dchar c)

Returns true if the character is an extender according to the XML standard

isIdeographic
bool isIdeographic(dchar c)

Returns true if the character is an ideographic character according to the XML standard

isLetter
bool isLetter(dchar c)

Returns true if the character is a letter according to the XML standard

isSpace
bool isSpace(dchar c)

Returns true if the character is whitespace according to the XML standard

Manifest constants

cdata
enum cdata;
Undocumented in source.

Examples

This example creates a DOM (Document Object Model) tree from an XML file.

import undead.xml;
import std.stdio;
import std.string;
import std.file;

// books.xml is used in various samples throughout the Microsoft XML Core
// Services (MSXML) SDK.
//
// See http://msdn2.microsoft.com/en-us/library/ms762271(VS.85).aspx

void main()
{
    string s = cast(string) std.file.read("books.xml");

    // Check for well-formedness
    check(s);

    // Make a DOM tree
    auto doc = new Document(s);

    // Plain-print it
    writeln(doc);
}

This example does much the same thing, except that the file is deconstructed and reconstructed by hand. This is more work, but the techniques involved offer vastly more power.

1 import undead.xml;
2 import std.stdio;
3 import std.string;
4 
5 struct Book
6 {
7     string id;
8     string author;
9     string title;
10     string genre;
11     string price;
12     string pubDate;
13     string description;
14 }
15 
16 void main()
17 {
18     string s = cast(string) std.file.read("books.xml");
19 
20     // Check for well-formedness
21     check(s);
22 
23     // Take it apart
24     Book[] books;
25 
26     auto xml = new DocumentParser(s);
27     xml.onStartTag["book"] = (ElementParser xml)
28     {
29         Book book;
30         book.id = xml.tag.attr["id"];
31 
32         xml.onEndTag["author"]       = (in Element e) { book.author      = e.text(); };
33         xml.onEndTag["title"]        = (in Element e) { book.title       = e.text(); };
34         xml.onEndTag["genre"]        = (in Element e) { book.genre       = e.text(); };
35         xml.onEndTag["price"]        = (in Element e) { book.price       = e.text(); };
36         xml.onEndTag["publish-date"] = (in Element e) { book.pubDate     = e.text(); };
37         xml.onEndTag["description"]  = (in Element e) { book.description = e.text(); };
38 
39         xml.parse();
40 
41         books ~= book;
42     };
43     xml.parse();
44 
45     // Put it back together again;
46     auto doc = new Document(new Tag("catalog"));
47     foreach (book;books)
48     {
49         auto element = new Element("book");
50         element.tag.attr["id"] = book.id;
51 
52         element ~= new Element("author",      book.author);
53         element ~= new Element("title",       book.title);
54         element ~= new Element("genre",       book.genre);
55         element ~= new Element("price",       book.price);
56         element ~= new Element("publish-date",book.pubDate);
57         element ~= new Element("description", book.description);
58 
59         doc ~= element;
60     }
61 
62     // Pretty-print it
63     writefln(join(doc.pretty(3),"\n"));
64 }

Meta

Authors

Janice Caron