\Header{xmlTree}{An internal, updatable DOM object for building XML trees}
\keyword{IO}{xmlTree}
\begin{Description}\relax
This is a mutable object (implemented via a closure)
for representing an XML tree, in the same
spirit as \code{\Link{xmlOutputBuffer}}
and \code{\Link{xmlOutputDOM}}
but that uses the internal structures of
libxml.
This can be used to create a DOM that can be 
constructed in R and exported to another system
such as XSLT (\url{http://www.omegahat.org/Sxslt})
\end{Description}
\begin{Usage}
\begin{verbatim}
xmlTree(tag, attrs = NULL, dtd=NULL, namespaces=list())
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{tag}] the tagname of the top-level element. This is basically
ignored!
\item[\code{attrs}] attributes for the top-level node, in the form of a named
vector or list.
\item[\code{dtd}] the name of the external DTD for this document. See \code{\Link{newXMLDoc}}
\item[\code{namespaces}] a named character vector with each element giving the name space identifier and the
corresponding URI, \bsl{}
e.g \code{c(shelp = "http://www.omegahat.org/XML/SHelp")}
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This creates a collection of functions that manipulate a shared
state to build and maintain an XML tree in C-level code.
\end{Details}
\begin{Value}
An object of class
\code{XMLInternalDOM}
that extends \code{XMLOutputStream}
and has the same interface (i.e. ``methods'') as
\code{\Link{xmlOutputBuffer}} 
and \code{\Link{xmlOutputDOM}}.
Each object has methods for 
adding a new XML tag, 
closing a tag, adding an XML comment,
and retrieving the contents of the tree.
\begin{ldescription}
\item[\code{addTag}] create a new tag at the current position,
optionally leaving it as the active open tag to which
new nodes will be added as children
\item[\code{closeTag}] close the currently active tag
making its parent the active element into
which new nodes will be added.
\item[\code{addComment}] add an XML comment node
as a child of the active node in the document.
\item[\code{value}] retrieve an object representing the 
XML tree. See \code{\Link{saveXML}} to serialize the
contents of the tree.
\item[\code{add}] degenerate method in this context.
\end{ldescription}
\end{Value}
\begin{Note}\relax
This is an early version of this function and I need to iron out some
of the minor details.
\end{Note}
\begin{Author}\relax
Duncan Temple Lang
\end{Author}
\begin{References}\relax
\url{http://www.w3.org/XML}, \url{http://www.xmlsoft.org},
\url{http://www.omegahat.org}
\end{References}
\begin{SeeAlso}\relax
\code{\Link{saveXML}}
\code{\Link{newXMLDoc}}
\code{\Link{newXMLNode}}
\code{\Link{xmlOutputBuffer}}
\code{\Link{xmlOutputDOM}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  tr <- xmlTree("Duncan")
  tr$addTag("name", attrs=c(a=1,b="xyz"), close=FALSE)
    tr$addTag("first", "Larry")
    tr$addTag("last", "User")
  tr$closeTag()
  tr$value()
  cat(saveXML(tr$value()))

  tr <- xmlTree("CDataTest")
  tr$addTag("top", close=FALSE)
  tr$addCData("x <- list(1, a='&');\nx[[2]]")
  tr$addPI("S", "plot(1:10)")
  tr$closeTag()
  cat(saveXML(tr$value()))
\end{ExampleCode}
\end{Examples}

