addChildren {XML} | R Documentation

## Add child nodes to an XML node

### Description

This collection of functions allow us to add and remove 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(...))
    removeChildren(node, ..., kids = list(...), free = FALSE)
    removeNodes(node, free = rep(FALSE, length(node)))
    addAttributes(node, ..., .attrs = NULL)
    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` parameter.
`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 are converted to XML text nodes. For `removeChildren`, this is again a list which identifies the child nodes to be removed using the integer identifier of the child, or the name of the XML node (but this will only remove the first such node and not necessarily do what you expect when there are multiple nodes with the same name), or the `XMLInternalNode` object itself.
`.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 those namespaces are defined.
`.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 indicating if `TRUE` that the attributes of interested are name space declarations, i.e. of the form `xmlns:prefix` or `xmlns`. If a value of `FALSE` is supplied this indicates that we are identifying regular attributes. Note that we can still identify attributes with a name space prefix as, e.g., `ns:attr` without this value
`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 `xmlTree` and `newXMLNode` and related functions. It is necessary as automated garbage collection is tricky in this tree-based context spanning both R and C data structures and memory managers.
`.all` | a logical value indicating whether to remove all of the attributes within the XML node without having to specify them by name.

### Details

### 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.

### Note

### Author(s)

Duncan Temple Lang

### References

http://www.xmlsoft.org{libxml2}

### See Also

`xmlTree` `newXMLNode`

### Examples

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

    cat(saveXML(b), "\n")

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

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

    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), "\n")

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

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

    cat(saveXML(b), "\n")

    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")

    ## Not run:
        # 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"))
    ## End(Not run)

     # 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

[Package XML version 1.93-2.1 Index]