[gdome] Proposed IDL for "sliding DOM"

[Raph Levien <raph acm org>]

Hi peoples,

   I've taken the liberty of whipping up some IDL for the proposed
"sliding DOM" interface. This is fairly minimalist - it supports only
the DOM subset consisting of Element and Text nodes. I think this is
the subset that is interesting for DOMination applications. This is
the interface that custom representations will have to implement (plus
event listeners), so I'm quite interested in keeping it minimal.

   Comments welcome.

Raph

// OMG IDL for "sliding DOM" extensions
// Copyright 1999 Raph Levien <raph acm org>
// Released under IJG-style license

module SlidingDOM {

    typedef sequence<unsigned short> Slide;
    // The Slide is used to locate a specific position in the DOM tree.
    // The semantics of a Slide with respect to a DOM document are defined
    // as follows, using a (hopefully clear) pseudolanguage:

    // DOM::Node getSlideNode (Slide slide, DOM::Document doc) {
    //     unsigned long level;
    //     DOM::Node cur = doc->documentElement;
    //     for (level = 0; level < slide.length; level++) {
    //         cur = cur->childNodes->item(slide[level]);
    //         if (cur == null)
    //             break;
    //     }
    //     return cur;
    // }

    // Additionally, chopLast returns a new Slide with all elements
    // but the last. It raises a NOT_FOUND_ERR on empty Slides.

    interface SlidingDoc {
	// Accessor methods. These methods allow complete traversal
	// of a document made entirely of Element and Text nodes.

	unsigned short nodeTypeSliding (Slide slide);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
        // if (node == null)
	//     return 0;
	// else
	//     return node->nodeType;

	unsigned short nChildrenSliding (Slide slide);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
        // if (node == null)
	//     return 0;
	// else
	//     return node->childNodes->length;

	string tagNameSliding (Slide slide);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::ELEMENT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// return utf16_to_utf8 (((DOM::Element)node)->tagName);

	string nAttrsSliding (Slide slide);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::ELEMENT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// return node->attributes->length;

	string getAttrNameSliding (Slide slide, unsigned long index);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::ELEMENT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// DOM::Attr attr = (DOM::Attr)node->attributes->item(index);
	// return utf16_to_utf8 (attr->name);

	string getAttrValueSliding (Slide slide, unsigned long index);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::ELEMENT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// DOM::Attr attr = (DOM::Attr)node->attributes->item(index);
	// return utf16_to_utf8 (attr->value);

	string getTextSliding (Slide slide);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::TEXT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// return utf16_to_utf8 (((DOM::Text)node)->data);

	// Mutator methods

	void removeSliding (Slide slide);
	// defined as:
	// DOM::Node parent = getSlideNode (chopLast (slide), doc);
	// DOM::Node node = getSlideNode (slide, doc);
	// if (parent == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// parent->removeChild(node);

	void moveSliding (Slide old, Slide new);
	// defined as:
	// DOM::Node oldParent = getSlideNode (chopLast (old), doc);
	// DOM::Node node = getSlideNode (old, doc);
	// if (oldParent == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// parent->removeChild(node);
	// DOM::Node newParent = getSlideNode (chopLast (new), doc);
	// DOM::Node newRef = getSlideNode (new, doc);
	// if (newParent == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// newParent->insertBefore(node, newRef);

	void insertTextSliding (Slide slide, string text);
	// defined as:
	// DOM::Node parent = getSlideNode (chopLast (slide), doc);
	// DOM::Node node = getSlideNode (slide, doc);
	// if (parent == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// DOM::Text textNode = doc->createTextNode (utf8_to_utf16 (text));
	// parent->insertBefore(textNode, node);

	void insertElementSliding (Slide slide, string tagName);
	// defined as:
	// DOM::Node parent = getSlideNode (chopLast (slide), doc);
	// DOM::Node node = getSlideNode (slide, doc);
	// if (parent == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// DOM::Element el = doc->createElement (utf8_to_utf16 (tagName));
	// parent->insertBefore(el, node);

	void setAttrSliding (Slide slide, string name, string value);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::ELEMENT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// ((DOM::Element)node)->setAttribute (utf8_to_utf16 (name),
	//                                     utf8_to_utf16 (value))

	// removeAttrSliding (Slide slide, string name)
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::ELEMENT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// ((DOM::Element)node)->removeAttribute (utf8_to_utf16 (name))

	string replaceTextSliding (Slide slide, string text);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::TEXT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// ((DOM::Text)node)->data = utf8_to_utf16 (text);

	string appendTextSliding (Slide slide, string text);
	// defined as:
	// DOM::Node node = getSlideNode (slide, doc);
	// if (node == null)
	//    raise (DOM::DomException DOM::NOT_FOUND_ERR);
	// if (node->nodeType != DOM::TEXT_NODE)
	//    raise (DOM::DomException DOM::NOT_SUPPORTED_ERR);
	// ((DOM::Text)node)->appendData(utf8_to_utf16 (text));
    }

}

// Notes

// Instead of the nAttrs, getAttrName, getAttrVal, I'm really tempted
// to do this (semantics should be obvious):
// struct Attr {
//     string name;
//     string value;
// }
// typedef sequence<Attr> Attrs;
// Attrs getAttrsSliding (Slide slide);
// void insertElementSliding (Slide slide, string tagName, Attrs attrs);

// I've appended "Sliding" to all methods to avoid namespace
// collisions in case an object inherits both the DOM::Document and
// SlidingDoc interfaces.

// There are some subtleties in the way I've written some definitions.
// For one, in moveSliding, if the new position is not found, the
// subtree is deleted. For another, when inserting new nodes, if the
// last index in the Slide is out of range, the new node is appended
// as the last child of the parent.

// Of the CharacterData "convenience" methods, I've only defined
// appendText. In general, you'll want to shovel entire strings over
// the CORBA interface - in general, this will be more efficient than
// picking at it with lots of little method invocations. However,
// appendText is so fabulously useful when creating a document from
// SAX-like tag stream interfaces that I let go of my usual minimalist
// tendencies and included it. The others are tempting too, though.

// I should probably allow CDATA_NODE in all TEXT_NODE contexts.