XML output streams

DESCRIPTION:

These two functions provide different ways to construct XML documents incrementally. They provide a single, common interface for adding and closing tags, and inserting nodes. The buffer version stores the XML representation as a string. The DOM version builds the tree of XML node objects.

USAGE:

xmlOutputBuffer(dtd=NULL, nameSpace=NULL, buf=NULL,
                 nsURI=NULL, header="<?xml version=\"1.0\"?>")

xmlOutputDOM(tag="doc", attrs = NULL, dtd=NULL,
                 nameSpace=NULL, nsURI=character(0))

ARGUMENTS:

dtd
a DTD object (see and ) which contains specifications about what elements are valid within other elements and what attributes are supported by different elements. This can be used to validate the document as it is being constructed incrementally. Note that this argument is currently ignored.
attrs
attributes for the top-level node, in the form of a named vector or list.
nameSpace
the default namespace identifier to be used when an element is created without an explicit namespace. This provides a convenient way to specify the default name space that appers in tags throughout the resulting document.
buf
a connection object or a string into which the XML content is written. This is currently a simplistic implementation since we will use the OOP-style classes from the Omegahat projects in the future.
nsURI
the URI or value for the name space which is used when declaring the namespace. For xmlOuputDOM, this is a named character vector with each element giving the name space identifier and the corresponding URI, e.g c(shelp = "http://www.omegahat.org/XML/SHelp")
header
if non-NULL, this is immediately written to the output stream allowing one to control the initial section of the XML document.
tag
the name of the top-level node/element in the DOM being created.

DETAILS:

These functions create a list of functions that, when attached as a frame, can operate on shared data used to represent the contents of the XML document being created and the current state of that creation.

VALUE:

Both of these functions return a list containing functions which operate on the XML data in the frame. The externally-usable functions in the list are:
value
get the contents of the XML document as they are currently defined.
addTag
add a new element to the document, specifying its name and attributes. This allows the tag to be left open so that new elements will be added as children of it.
closeTag
close the currently open tag, indicating that new elements will be added, by default, as siblings of this one.
reset
discard the current contents of the document so that we can start over and free the resources (memory) associated with this document.
addNode
insert an complete XMLNode object into the currently active (i.e. open) node. There are also helper functions addComment, addPI , and addCData for adding these types of nodes.
attach.DOM
attach an xmlOutputDOM object in order to use it to generate DOM objects.
detach.DOM
detach the object (note: DOM object will be lost)
getCurrent
returns the currently active/open node.

NOTE:

Only one xmlOutputDOM or xmlOutputBuffer object can be active (attached) at a time. When you activate/attach a new object, you may lose the information you had built up in the previously attached object. Calling the xmlEventHandler function automatically activates/attaches its xmlOutputDOM object; with the other functions, you must first call the function, and then attach the object.

AUTHOR(S):

Duncan Temple Lang

REFERENCES:

http://www.omegahat.org/RSXML, http://www.w3.org/xml

SEE ALSO:

, , ,

EXAMPLES:

con <- xmlOutputDOM()
attach.DOM(con)
con$reset() 
con$addTag("author", "Duncan Temple Lang")
con$addTag("address",  close=FALSE)
 con$addTag("office", "2C-259")
 con$addTag("street", "Mountain Avenue.")
 con$addTag("phone", close=FALSE)
   con$addTag("area", "908", attrs=c(state="NJ"))
   con$addTag("number", "582-3217")
 con$closeTag() # phone
con$closeTag() # address
con$addTag("section", close=FALSE)
 con$addNode(xmlTextNode("This is some text "))
 con$addTag("a","and a link", attrs=c(href="http://www.omegahat.org"))
 con$addNode(xmlTextNode("and some follow up text"))
 con$addTag("subsection", close=FALSE)
   con$addNode(xmlTextNode("some addtional text "))
   con$addTag("a", attrs=c(href="http://www.omegahat.org"), close=FALSE)
     con$addNode(xmlTextNode("the content of the link"))
   con$closeTag() # a
 con$closeTag() # "subsection"
con$closeTag() # section

print(con$value())
detach.DOM()

b <- xmlOutputBuffer()
attach.DOM(b)
b$reset() 
b$addTag("doc", close=F)
b$addPI("S", "plot(1:10)")
b$addCData('x <- list(1, a="&");\nx[[2]]')
b$closeTag()
cat(b$value())
detach.DOM()