From: ser@... (Sean Russell)
Date: 2003-06-14T23:22:47+09:00
Subject: REXML, APIs, and POLS

Hello Rublets,

This is a solicitation for API suggestions.

If you read my previous posting, you'll know that the new REXML
architecture makes it easy to add APIs for accessing documents.   One
of these will be DOM; that's a no-brainer.  While I loath DOM, there
are many people who feel that DOM support is a requirement for any XML
library.  In any case, these APIs are non-conflicting; you use the one
you like the most.

The "old" REXML API is still the main API.  It boasts a wide variety
of convenience methods, and I still believe it to be the lowest cost
of entry for dealing with XML.  However, this comes at a price, which
is that each convenience method adds a certain amount of size to the
objects used.

There is, in the new API, a nacent API called the "Light" API.  It
consists of a single class, called Node, and just a few methods -- all
undocumented.  Document trees created with this API are about half the
size of the regular REXML document trees, and creating these trees is
computationally faster.

I'd like to flesh out this API.  Right now, it is more or less a
read-only API, and I'd like to extend it so that it becomes a full
alternative to the classic REXML API.  In the process, I'd like to
explore ways of making it even more POLS than the classic REXML API --
a sort of evolution towards perfection, using lessons learned.  To
that end, I'm soliciting use-case suggestions.  Most interesting to me
are creative alternatives exploiting Ruby language feature to make
this POLS.

To start out the discussion, here are some ideas:

	a = Node.new("a")		# Create a node. But what kind of node?
	a << "b"			# Add a new node to "a"... but what kind.  We can deduce
	# now that "a" is an element, because only elements can have
	# children, but what do we get if we print out "a"?  Let's assume 
	# that all new nodes are text nodes, so "b" is now a text node
	(a << "c").element!	# Add "c" to a, and force "c" to be an element
	(a << "d").element! << "e"
	# Add "d" to "a", make "d" and element, and add "e" to "d"
	# puts a => <a>b<c/><d>e</d></a>
	a[1]					# => "b"
	a[2]					# => <c/>
	(a[2] << "x").instruction!
	(a[2] << "Some comment").comment!
	# ... etcetera
	a['foo'] = 'bar'			# Adding an attribute
	a['foo']				# => "bar"

I *almost* like this, except I wish that there was a more elegant way
of specifying the node type.

Here's a chance to help craft the ultimate, lightweight, intuitive XML
API.