1\name{parseXMLAndAdd}
2\alias{parseXMLAndAdd}
3\title{Parse XML content and add it to a node}
4\description{
5  This function parses the given XML content as a string
6  by putting it inside a top-level node and then returns
7  the document or adds the children to the specified parent.
8  The motivation for this function is when we can use
9  string manipulation to efficiently create the  XML content
10  by using vectorized operations in R, but then
11  converting that content into parsed nodes.
12
13  Generating XML/HTML content by glueing strings together
14  is a poor approach. It is often convenient, but rarely
15  good general software design. It makes for bad software that is not
16  very extensible and difficult to maintain and enhance.
17  Structure that it is
18  programmatically accessible is much better. The tree
19  approach provides this structure.
20  Using strings is convenient and somewhat appropriate when done
21  atomically for large amounts of highly regular content.
22  But then the results should be converted to the structured tree
23  so that they can be modified and extended.
24  This function facilitates using strings and returning structured content.
25}
26\usage{
27parseXMLAndAdd(txt, parent = NULL, top = "tmp", nsDefs = character())
28}
29%- maybe also 'usage' for other objects documented here.
30\arguments{
31  \item{txt}{the XML content to parse}
32  \item{parent}{an XMLInternalNode to which the top-level nodes in
33    \code{txt} will be added as children}
34  \item{top}{the name for the top-level node. If \code{parent} is
35    specified, this is used but irrelevant.}
36  \item{nsDefs}{a character vector of name = value pairs giving
37  namespace definitions to be added to the top node.}
38}
39\value{
40  If \code{parent} is \code{NULL}, the root node of the
41  parsed document is returned.  This will be an element
42  whose name is given by \code{top} unless the XML content in \code{txt}
43  is AsIs or \code{code} is empty.
44
45  If \code{parent} is non-\code{NULL}, .
46}
47
48\author{
49Duncan Temple Lang
50}
51
52\seealso{
53  \code{\link{newXMLNode}}
54  \code{\link{xmlParse}}
55  \code{\link{addChildren}}
56}
57\examples{
58  long = runif(10000, -122, -80)
59  lat = runif(10000, 25, 48)
60
61  txt = sprintf("<Placemark><Point><coordinates>\%.3f,\%.3f,0</coordinates></Point></Placemark>",
62                  long, lat)
63  f = newXMLNode("Folder")
64  parseXMLAndAdd(txt, f)
65  xmlSize(f)
66
67
68\dontrun{
69      # this version is much slower as i) we don't vectorize the
70      #  creation of the XML nodes, and ii) the parsing of the XML
71      # as a string is very fast as it is done in C.
72  f = newXMLNode("Folder")
73  mapply(function(a, b) {
74           newXMLNode("Placemark",
75                       newXMLNode("Point",
76                                   newXMLNode("coordinates",
77                                               paste(a, b, "0", collapse = ","))),
78		       parent = f)
79           },
80         long, lat)
81  xmlSize(f)
82
83
84  o = c("<x>dog</x>", "<omg:x>cat</omg:x>")
85  node = parseXMLAndAdd(o, nsDefs  = c("http://cran.r-project.org",
86                                       omg = "http://www.omegahat.net"))
87  xmlNamespace(node[[1]])
88  xmlNamespace(node[[2]])
89
90  tt = newXMLNode("myTop")
91  node = parseXMLAndAdd(o, tt, nsDefs  = c("http://cran.r-project.org",
92                                           omg = "http://www.omegahat.net"))
93  tt
94}
95
96
97}
98\keyword{IO}
99
100