Changeset 553

Timestamp:

02/09/08 08:54:42 (10 months ago)

Author:

Janice Caron

Message:

Removed functions addComment(), addText(), etc.
Added classes Comment, Text, etc.
Added pretty-printing
Added example of XML construction to ddoc comments.

Files:

• candidate/phobos/std/xml.d (modified) (35 diffs)

candidate/phobos/std/xml.d

@@ -17 +17 @@
-import std.xml;
-import std.stdio;
+import std.string;
-
-// 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
-
+struct Book
+{
+    string id;
+    string author;
+    string title;
+    string genre;
+    string price;
+    string pubDate;
+    string description;
+}
+
-void main()
-{
-    string s = import("books.xml");
+
+    // Take it apart
+    Book[] books;
+
-    auto xml = new DocumentParser(s);
-
-    xml.onStartTag["book"] = delegate void(ElementParser xml)
-    {
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
-
-        xml.parse();
-
-
-
-
-
-
-
-
+
-    };
-
-    xml.parse();
+
+    // Put it back together again;
+    auto doc = new Document("catalog");
+    foreach(book;books)
+    {
+        auto element = new Element("book");
+        element.tag.attr["id"] = book.id;
+
+        element ~= new Element("author",      book.author);
+        element ~= new Element("title",       book.title);
+        element ~= new Element("genre",       book.genre);
+        element ~= new Element("price",       book.price);
+        element ~= new Element("publish-date",book.pubDate);
+        element ~= new Element("description", book.description);
+
+        doc ~= element;
+    }
+
+    // Now let's see pretty-print it to see what it looks like
+    writefln(join(doc.pretty(3),"\n"));
-}
---------------------------------------------------------------------------------------------------
@@ -66 +90 @@
-
-    void check(string xml);
-
-
-
-
+
-*/
-
@@ -130 +151 @@
- * Returns: The decoded string
- *
-XML
+
- *
- * Examples:
@@ -158 +179 @@
-                dchar parseHex(string hex)
-                {
-XML
+
-                    dchar d = 0;
-                    foreach(dchar c;hex)
@@ -181 +202 @@
-                            case '1': ++d;
-                            case '0': break;
-XML
+
-                        }
-                    }
@@ -190 +211 @@
-                {
-                    dchar d = parse!(uint)(dec);
-XML
+
-                    return d;
-                }
-
-                int j = s[i..$].find(';');
-XML
+
-                j += i;
-                string codepoint = s[i+2..j];
-XML
+
-                if (codepoint[0] == 'x' || codepoint[0] == 'X') buffer ~= parseHex(codepoint[1..$]);
-                else buffer ~= parseDecimal(codepoint);
@@ -208 +229 @@
-            else if (startsWith(s[i..$],"&lt;"  )) { buffer ~= '<';  i += 3; }
-            else if (startsWith(s[i..$],"&gt;"  )) { buffer ~= '>';  i += 3; }
-XML
+
-        }
-    }
@@ -220 +241 @@
-        bool b = false;
-        try { decode(s); }
-XML
+
-        assert(b,s);
-    }
@@ -258 +279 @@
-
-    /**
- and the string interior
+
-     *
-     * Params:
-     *      name = the name of the root element of the document.
-
-
-
-
-
+
+
+
+
-    }
-
@@ -276 +296 @@
-     *      interior = (optional) the string interior of the root element. Must be well-formed XML.
-     */
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
-    }
-
@@ -340 +348 @@
-         * can be used as associative array keys.
-         */
-
-
-
-
-
-
+
-
-        /**
@@ -352 +355 @@
-        override string toString()
-        {
-"\r\n" ~ 
+
-        }
-    }
@@ -366 +369 @@
- * Bugs: class invariant not yet written
- */
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
-     *
-     * Params:
-     *      name = the name of the element.
- of the root element. Must be well-formed XML
-   
+
+    
-    this(string name, string interior=null)
-    {
-
-
-
-
-
+
+
+
+
+
+
-     *
-     * Params:
-
-
-
-
-
-
-
-
-
-
+
+
+
-    {
-        this.tag = tag;
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-    }
-
@@ -433 +406 @@
-
-    /**
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-     *
-     * Params:
@@ -546 +414 @@
-     * --------------
-     * Element element;
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-    }
-
@@ -565 +491 @@
-         * XML such as "&lt;title&gt;Good &amp;amp; Bad&lt;/title&gt;", will return "Good &amp; Bad".
-         *
-XML
+
-         */
-        string text()
-        {
-
+
+
+
+
+
+
+
+
-        }
-
-        /**
-Compares two Elements for equality
+Returns an indented string representation of this item
-         *
-
-
-
-
-
+
+
-         */
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        }
-
@@ -635 +549 @@
-        override string toString()
-        {
-
-
-
-
+
+
+
+
+
+
+
+
+
-    }
-}
@@ -699 +618 @@
-        this.name = name;
-        this.type = type;
-    }
-
-    /**
-     * Copy constructor. Makes a deep copy.
-     *
-     * Params:
-     *      tag = another Tag.
-     */
-    this(Tag tag)
-    {
-        this(name, tag.type);
-        foreach(k,v;tag.attr) { attr[k] = v; }
-    }
-
@@ -745 +652 @@
-            if (opt(s,'/'))
-            {
-XML
+
-                type = TagType.EMPTY;
-            }
@@ -751 +658 @@
-            tagString.length = (s.ptr - tagString.ptr);
-        }
-XML
+
-        {
-            tagString.length = (s.ptr - tagString.ptr);
-XML
+
-        }
-    }
@@ -835 +742 @@
-                string s = "<" ~ name;
-                foreach(key,val;attr) s ~= format(" %s=\"%s\"",key,decode(val));
- ~ ">"
+
-            }
-
@@ -875 +782 @@
-        bool isEmpty() { return type == TagType.EMPTY; }
-    }
+}
+
+/**
+ * Class representing a comment
+ */
+class Comment : Item
+{
+    private string content;
+
+    /**
+     * Construct a comment
+     *
+     * Params:
+     *      content = the body of the comment
+     *
+     * Throws: CommentException if the comment body is illegal (contains "--" or exactly equals "-")
+     *
+     * Examples:
+     * --------------
+     * auto item = new Comment("This is a comment");
+     *    // constructs <!--This is a comment-->
+     * --------------
+     */
+    this(string content)
+    {
+        if (content == "-" || content.find("==") != -1) throw new CommentException(content);
+        this.content = content;
+    }
+
+    /**
+     * Compares two comments for equality
+     *
+     * Examples:
+     * --------------
+     * Comment item1,item2;
+     * if (item1 == item2) { }
+     * --------------
+     */
+    override int opEquals(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(Comment)item;
+        return t !is null && content == t.content;
+    }
+
+    /**
+     * Compares two comments
+     *
+     * You should rarely need to call this function. It exists so that Comments
+     * can be used as associative array keys.
+     *
+     * Examples:
+     * --------------
+     * Comment item1,item2;
+     * if (item1 < item2) { }
+     * --------------
+     */
+    override int opCmp(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(Comment)item;
+        return t !is null && (content != t.content ? (content < t.content ? -1 : 1 ) : 0 );
+    }
+
+    /**
+     * Returns the hash of a Comment
+     *
+     * You should rarely need to call this function. It exists so that Comments
+     * can be used as associative array keys.
+     */
+    override hash_t toHash() { return stringToHash(content); }
+
+    /**
+     * Returns a string representation of this comment
+     */
+    override const string toString() { return "<!--" ~ content ~ "-->"; }
+
+    override const bool isEmptyXML() { return false; } /// Returns false always
+}
+
+/**
+ * Class representing a Character Data section
+ */
+class CData : Item
+{
+    private string content;
+
+    /**
+     * Construct a chraracter data section
+     *
+     * Params:
+     *      content = the body of the character data segment
+     *
+     * Throws: CDataException if the segment body is illegal (contains "]]>")
+     *
+     * Examples:
+     * --------------
+     * auto item = new CData("<b>hello</b>");
+     *    // constructs <![CDATA[<b>hello</b>]]>
+     * --------------
+     */
+    this(string content)
+    {
+        if (content.find("]]>") != -1) throw new CDataException(content);
+        this.content = content;
+    }
+
+    /**
+     * Compares two CDatas for equality
+     *
+     * Examples:
+     * --------------
+     * CData item1,item2;
+     * if (item1 == item2) { }
+     * --------------
+     */
+    override int opEquals(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(CData)item;
+        return t !is null && content == t.content;
+    }
+
+    /**
+     * Compares two CDatas
+     *
+     * You should rarely need to call this function. It exists so that CDatas
+     * can be used as associative array keys.
+     *
+     * Examples:
+     * --------------
+     * CData item1,item2;
+     * if (item1 < item2) { }
+     * --------------
+     */
+    override int opCmp(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(CData)item;
+        return t !is null && (content != t.content ? (content < t.content ? -1 : 1 ) : 0 );
+    }
+
+    /**
+     * Returns the hash of a CData
+     *
+     * You should rarely need to call this function. It exists so that Documents
+     * can be used as associative array keys.
+     */
+    override hash_t toHash() { return stringToHash(content); }
+
+    /**
+     * Returns a string representation of this CData section
+     */
+    override const string toString() { return "<[CDATA[" ~ content ~ "]]>"; }
+
+    override const bool isEmptyXML() { return false; } /// Returns false always
+}
+
+/**
+ * Class representing a text (aka Parsed Character Data) section
+ */
+class Text : Item
+{
+    private string content;
+
+    /**
+     * Construct a text (aka PCData) section
+     *
+     * Params:
+     *      content = the text. This function encodes the text before insertion,
+     *      so it is safe to insert any text
+     *
+     * Examples:
+     * --------------
+     * auto Text = new CData("a < b");
+     *    // constructs a &lt; b
+     * --------------
+     */
+    this(string content)
+    {
+        this.content = encode(content);
+    }
+
+    /**
+     * Compares two text sections for equality
+     *
+     * Examples:
+     * --------------
+     * Text item1,item2;
+     * if (item1 == item2) { }
+     * --------------
+     */
+    override int opEquals(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(Text)item;
+        return t !is null && content == t.content;
+    }
+
+    /**
+     * Compares two text sections
+     *
+     * You should rarely need to call this function. It exists so that Texts
+     * can be used as associative array keys.
+     *
+     * Examples:
+     * --------------
+     * Text item1,item2;
+     * if (item1 < item2) { }
+     * --------------
+     */
+    override int opCmp(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(Text)item;
+        return t !is null && (content != t.content ? (content < t.content ? -1 : 1 ) : 0 );
+    }
+
+    /**
+     * Returns the hash of a text section
+     *
+     * You should rarely need to call this function. It exists so that Texts
+     * can be used as associative array keys.
+     */
+    override hash_t toHash() { return stringToHash(content); }
+
+    /**
+     * Returns a string representation of this Text section
+     */
+    override const string toString() { return content; }
+
+    override const bool isEmptyXML() { return content.length == 0; } /// Returns true if the content is the empty string
+}
+
+/**
+ * Class representing an XML Instruction section
+ */
+class XMLInstruction : Item
+{
+    private string content;
+
+    /**
+     * Construct an XML Instruction section
+     *
+     * Params:
+     *      content = the body of the instruction segment
+     *
+     * Throws: XIException if the segment body is illegal (contains ">")
+     *
+     * Examples:
+     * --------------
+     * auto item = new XMLInstruction("ATTLIST");
+     *    // constructs <!ATTLIST>
+     * --------------
+     */
+    this(string content)
+    {
+        if (content.find(">") != -1) throw new XIException(content);
+        this.content = content;
+    }
+
+    /**
+     * Compares two XML instructions for equality
+     *
+     * Examples:
+     * --------------
+     * XMLInstruction item1,item2;
+     * if (item1 == item2) { }
+     * --------------
+     */
+    override int opEquals(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(XMLInstruction)item;
+        return t !is null && content == t.content;
+    }
+
+    /**
+     * Compares two XML instructions
+     *
+     * You should rarely need to call this function. It exists so that XmlInstructions
+     * can be used as associative array keys.
+     *
+     * Examples:
+     * --------------
+     * XMLInstruction item1,item2;
+     * if (item1 < item2) { }
+     * --------------
+     */
+    override int opCmp(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(XMLInstruction)item;
+        return t !is null && (content != t.content ? (content < t.content ? -1 : 1 ) : 0 );
+    }
+
+    /**
+     * Returns the hash of an XMLInstruction
+     *
+     * You should rarely need to call this function. It exists so that XmlInstructions
+     * can be used as associative array keys.
+     */
+    override hash_t toHash() { return stringToHash(content); }
+
+    /**
+     * Returns a string representation of this XmlInstruction
+     */
+    override const string toString() { return "<!" ~ content ~ ">"; }
+
+    override const bool isEmptyXML() { return false; } /// Returns false always
+}
+
+/**
+ * Class representing a Processing Instruction section
+ */
+class ProcessingInstruction : Item
+{
+    private string content;
+
+    /**
+     * Construct a Processing Instruction section
+     *
+     * Params:
+     *      content = the body of the instruction segment
+     *
+     * Throws: PIException if the segment body is illegal (contains ">")
+     *
+     * Examples:
+     * --------------
+     * auto item = new ProcessingInstruction("php");
+     *    // constructs <?php>
+     * --------------
+     */
+    this(string content)
+    {
+        if (content.find(">") != -1) throw new XIException(content);
+        this.content = content;
+    }
+
+    /**
+     * Compares two processing instructions for equality
+     *
+     * Examples:
+     * --------------
+     * ProcessingInstruction item1,item2;
+     * if (item1 == item2) { }
+     * --------------
+     */
+    override int opEquals(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(ProcessingInstruction)item;
+        return t !is null && content == t.content;
+    }
+
+    /**
+     * Compares two processing instructions
+     *
+     * You should rarely need to call this function. It exists so that ProcessingInstructions
+     * can be used as associative array keys.
+     *
+     * Examples:
+     * --------------
+     * ProcessingInstruction item1,item2;
+     * if (item1 < item2) { }
+     * --------------
+     */
+    override int opCmp(Object o)
+    {
+        const item = toType!(const Item)(o);
+        const t = cast(ProcessingInstruction)item;
+        return t !is null && (content != t.content ? (content < t.content ? -1 : 1 ) : 0 );
+    }
+
+    /**
+     * Returns the hash of a ProcessingInstruction
+     *
+     * You should rarely need to call this function. It exists so that ProcessingInstructions
+     * can be used as associative array keys.
+     */
+    override hash_t toHash() { return stringToHash(content); }
+
+    /**
+     * Returns a string representation of this ProcessingInstruction
+     */
+    override const string toString() { return "<?" ~ content ~ ">"; }
+
+    override const bool isEmptyXML() { return false; } /// Returns false always
+}
+
+/**
+ * Abstract base class for XML items
+ */
+abstract class Item
+{
+    abstract override int opEquals(Object o); /// Compares with another Item of same type for equality
+    abstract override int opCmp(Object o); /// Compares with another Item of same type
+    abstract override hash_t toHash(); /// Returns the hash of this item
+    abstract override const string toString(); /// Returns a string representation of this item
+
+    /**
+     * Returns an indented string representation of this item
+     *
+     * Params:
+     *      indent = number of spaces by which to indent child elements
+     */
+    const string[] pretty(uint indent) { return [ toString() ]; }
+
+    abstract const bool isEmptyXML(); /// Returns true if the item represents empty XML text
-}
-
@@ -1041 +1357 @@
-     * --------------
-     */
-            (Handler handler) { textHandler         
+(Handler handler) { textHandler 
-
-    /**
@@ -1060 +1376 @@
-     * --------------
-     */
-       (Handler handler) { cdataHandler        
+(Handler handler) { cdataHandler 
-
-