XML (version 3.98-1.1)

addChildren: Add child nodes to an XML node

Description

This collection of functions allow us to add, remove and replace children from an XML node and also to and and remove attributes on an XML node. These are generic functions that work on both internal C-level XMLInternalElementNode objects and regular R-level XMLNode objects.

addChildren is similar to addNode and the two may be consolidated into a single generic function and methods in the future.

Usage

addChildren(node, ..., kids = list(...), at = NA, cdata = FALSE, append = TRUE)
removeChildren(node, ..., kids = list(...), free = FALSE)
removeNodes(node, free = rep(FALSE, length(node)))
replaceNodes(oldNode, newNode, ...)
addAttributes(node, ..., .attrs = NULL, 
               suppressNamespaceWarning = getOption("suppressXMLNamespaceWarning", FALSE),
                append = TRUE)
removeAttributes(node, ..., .attrs = NULL, .namespace = FALSE,
                  .all = (length(list(...)) + length(.attrs)) == 0)

Arguments

node

the XML node whose state is to be modified, i.e. to which the child nodes are to be added or whose attribute list is to be changed.

...

This is for use in interactive settings when specifying a collection of values individuall. In programming contexts when one obtains the collection as a vector or list from another call, use the kids or .attrs p

kids

when adding children to a node, this is a list of children nodes which should be of the same "type" (i.e. internal or R-level nodes) as the node argument. However, they can also be regular strings in which case they ar

at

if specified, an integer identifying the position in the original list of children at which the new children should be added. The children are added after that child. This can also be a vector of indices which is as long as t

cdata

a logical value which controls whether children that are specified as strings/text are enclosed within a CDATA node when converted to actual nodes. This value is passed on to the relevant function that creates the text nodes, e.g.

.attrs

a character vector identifying the names of the attributes. These strings can have name space prefixes, e.g. r:length and the namespaces will be resolved relative to the list supported by node to ensure t

.namespace

This is currently ignored and may never be supported. The intent is to identify on which set of attributes the operation is to perform - the name space declarations or the regular node attributes. This is a logical value ind

free

a logical value indicating whether to free the C-level memory associated with the child nodes that were removed. TRUE means to free that memory. This is only applicable for the internal nodes created with x

.all

a logical value indicating whether to remove all of the attributes within the XML node without having to specify them by name.

oldNode

the node which is to be replaced

newNode

the node which is to take the place of oldNode in the list of children of the parent of oldNode

suppressNamespaceWarning

a logical value or a character string. This is used to control the situation when an XML node or attribute is created with a name space prefix that currently has no definition for that node. This is not necessarily an error but

append

a logical value that indicates whether (TRUE) the specified attributes or children should be added to the existing attributes on the XML node (if any exist), or, if FALSE these should replace any existing attributes.

Value

• Each of these functions returns the modified node. For an internal node, this is the same R object and only the C-level data structures have changed. For an R XMLNode object, this is is an entirely separate object from the original node. It must be inserted back into its parent "node" or context if the changes are to be seen in that wider context.

concept

• XML
• document tree

References

libxml2 http://www.xmlsoft.org

See Also

xmlTree newXMLNode

Examples

b = newXMLNode("bob",
              namespace = c(r = "http://www.r-project.org",
                            omg = "http://www.omegahat.org"))

cat(saveXML(b), "")

addAttributes(b, a = 1, b = "xyz", "r:version" = "2.4.1", "omg:len" = 3)
cat(saveXML(b), "")

removeAttributes(b, "a", "r:version")
cat(saveXML(b), "")


removeAttributes(b, .attrs = names(xmlAttrs(b)))


addChildren(b, newXMLNode("el", "Red", "Blue", "Green",
                           attrs = c(lang ="en")))

k = lapply(letters, newXMLNode)
addChildren(b, kids = k)

cat(saveXML(b), "")

removeChildren(b, "a", "b", "c", "z")

  # can mix numbers and names
removeChildren(b, 2, "e")  # d and e

cat(saveXML(b), "")


i = xmlChildren(b)[[5]]
xmlName(i)

 # have the identifiers
removeChildren(b, kids = c("m", "n", "q"))



x <- xmlNode("a", 
               xmlNode("b", "1"),
               xmlNode("c", "1"),
	       "some basic text")

v = removeChildren(x, "b")

  # remove c and b
v = removeChildren(x, "c", "b")

  # remove the text and "c" leaving just b
v = removeChildren(x, 3, "c")

# this won't work as the 10 gets coerced to a 
    # character vector element to be combined with 'w'
    # and there is no node name 10.
 removeChildren(b, kids = c(10, "w"))


 # for R-level nodes (not internal)

z = xmlNode("arg", attrs = c(default="TRUE"),
              xmlNode("name", "foo"), xmlNode("defaultValue","1:10"))

o = addChildren(z,
                "some text",
                xmlNode("a", "a link",
                         attrs = c(href = "http://www.omegahat.org/RSXML")))
o


  # removing nodes

 doc = xmlParse("<top><a/><b/><c><d/><e>bob</e></c></top>")
 top = xmlRoot(doc)
 top
 
 removeNodes(list(top[[1]], top[[3]]))

    # a and c have disappeared.
 top