addChildren               package:XML               R Documentation

_A_d_d _c_h_i_l_d _n_o_d_e_s _t_o _a_n _X_M_L _n_o_d_e

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

    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. 

      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 the number of
          children being added and specifies the position for each
          child being added. If the vector is shorter than the number
          of children being added, it is padded with NAs and so the
          corresponding children are added at the end of the list.

          This parameter is only implemented for internal nodes at
          present. 

   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. 
          'xmlTextNode' and 'newXMLTextNode'. 

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

 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 can lead to one. This argument controls whether a
          warning is issued or if a separate function is called. A
          value of 'FALSE' means not to suppress the warning and  so it
          is issued. A value of 'TRUE' causes the potential problem to
          be ignored assuming that the namespace will be added to this
          node or one of its ancestors at a later point. And if this
          value is a character string, we search for a function of that
          name and invoke it.  

_V_a_l_u_e:

     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.

_A_u_t_h_o_r(_s):

     Duncan Temple Lang

_R_e_f_e_r_e_n_c_e_s:

     <URL: http://www.xmlsoft.org>{libxml2}

_S_e_e _A_l_s_o:

     'xmlTree' 'newXMLNode'

_E_x_a_m_p_l_e_s:

     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

