SAX-like API spec

[danini-the-panini]

The ckdl parser is event-based, inspired by SAX. I wonder if it is worth standardising this API by creating a language-agnostic spec for it.

The benefit to having this API spec would be to encourage other implementations to expose a streaming API to facilitate processing of very large KDL documents without running into memory issues, or efficiently parse a KDL document being read over a slow IO stream.

This API would go hand-in-hand with the Data Model.

Currently, this is what ckdl's events API looks like:

• EOF — Regular end of document (do not continue reading)
• PARSE_ERROR — Parse error (do not continue reading)
• START_NODE — Start of a node
• END_NODE — End of a node. Every START_NODE event is followed, some time later, by an END_NODE event (barring a parse error)
• ARGUMENT — An argument to the most recently started node
• PROPERTY — A property of the most recently started node
• COMMENT — Normally not produced (parser's can emit this if they choose to)

NOTE: ckdl specifically defines KDL_EVENT_COMMENT as 0x10000 in order to bitwise OR with the other event types, facilitating slashdash commented elements. This may be considered an implementation detail and therefore may not be stipulated in the spec. It could also be represented as a boolean commented property in the event data.

Each event is associated with certain event data:

• event — The event type
• name — The name of the node (with START_NODE), or the name of the property (with PROPERTY)
• value — The value of the argument (with ARGUMENT) or of the property (with PROPERTY), including any potential type annotation.

Note: ckdl also uses value to store the type annotation of the START_NODE event, encoded as a (type)#null KDL value. I feel this is a bit strange from an API point of view. While I do see the benefit of re-using the value property of the event data, I feel the API might make more sense to have an explicit type property, even if this results in redundancy due to a KDL Value itself also storing type annotation. Another possible alternative is to represent START_NODE using a node property, which holds the name and type annotation with empty values for arguments, properties, and children.

Potential names for this proposed API:

• Simple API for KDL (SAK) — like SAX
• KDL Events API (KEA) — very close to the furniture manufacturer Ikea, which is known for shipping unassembled products with a list of instructions on how to assemble, much like this API