newXMLDoc                package:XML                R Documentation

_C_r_e_a_t_e _i_n_t_e_r_n_a_l _X_M_L _n_o_d_e _o_r _d_o_c_u_m_e_n_t _o_b_j_e_c_t

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

     These are used to create internal `libxml' nodes and top-level
     document objects  that are used to write XML trees.  While the
     functions are available, their direct use is not encouraged.
     Instead, use 'xmlTree' as the functions need to be used within a
     strict regime to avoid corrupting C level structures.

     'xmlDoc' creates a new XMLInternalDocument object by copying the
     given node and all of its descendants and putting them into a new
     document. This is useful when we want to work with sub-trees with
     general tools that work on documents, e.g. XPath queries.

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

     xmlDoc(node)
     newXMLDoc(dtd, namespaces=NULL)
     newXMLNode(name, ..., attrs = NULL, namespace="", doc=NULL, .children = list(...))
     newXMLTextNode(text, doc = NULL)
     newXMLCDataNode(text, doc = NULL)
     newXMLCommentNode(text, doc = NULL)
     newXMLPINode(name, text, doc = NULL)
     newXMLDTDNode(nodeName, externalID = character(), systemID = character(), doc = NULL)  

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

    node: a 'XMLInternalNode' object that will be copied to create a
          subtree for a new document.

     dtd: the name of the DTD to use for the XML document.

namespaces: a named character vector with each element specifying a
          name space identifier and the corresponding URI for that
          namespace that are to be declared and used in the XML
          document, \ e.g. 'c(shelp =
          "http://www.omegahat.org/XML/SHelp")'

    name: the tag/element name for the XML node and the for a
          Processing Instruction (PI) node, this is the "target", e.g.
          the identifier for the system for whose attention this PI
          node is intended.

     ...: the children of this node. These can be other nodes created
          earlier or R strings that are converted to text nodes and
          added as children to this newly created node.

   attrs: a named list of name-value pairs to be used as  attributes
          for the XML node.

namespace: the short or alias for the namespace to use for this XML
          node

     doc: the 'XMLInternalDocument' object created with 'newXMLDoc'
          that is used to root the node.

.children: a list containing XML node elements or content. This is an
          alternative form of specifying the child nodes than ... which
          is useful for programmatic interaction when the "sub"-content
          is already in a list rather than a loose collection of
          values.

    text: the text content for the new XML node

nodeName: the name of the node to put in the DOCTYPE element that will
          appear as the top-most node in the XML document.

externalID: the PUBLIC identifier for the document type. This is a
          string of the form 'A//B//C//D'. A is either + or -; B
          identifies the person or insitution that defined the format
          (i.e. the "creator"); C is the name of the format; and
          language is an encoding for the language that comes from the
          ISO 639 document.

systemID: the SYSTEM identifier for the DTD for the document. This is a
          URI

_D_e_t_a_i_l_s:

     These create internal C level objects/structure instances that can
     be added to a libxml DOM and subsequently inserted into other
     document objects or ``serialized'' to textual form.

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

     Each function returns an R object that points to the C-level
     structure instance. These are of class 'XMLInternalDocument' and
     'XMLInternalNode', respectively

_N_o_t_e:

     These functions are used to build up an internal XML tree. This
     can be used in the Sxslt package (<URL:
     http://www.omegahat.org/Sxslt>) when creating content in R that is
     to be dynamicall inserted into an XML document.

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

     Duncan Temple Lang

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

     <URL: http://www.w3.org/XML>, <URL: http://www.xmlsoft.org>, <URL:
     http://www.omegahat.org>

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

     'xmlTree' 'saveXML'

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

     x = summary(rnorm(1000))
     d = xmlTree()
     d$addNode("table", close = FALSE)

     d$addNode("tr", .children = sapply(names(x), function(x) d$addNode("th", x)))
     d$addNode("tr", .children = sapply(x, function(x) d$addNode("td", format(x))))

     d$closeNode()

     # Just doctype
     z = xmlTree("people", dtd = "people")
     # no public element
     z = xmlTree("people", dtd = c("people", "", "http://www.omegahat.org/XML/types.dtd"))
     # public and system
     z = xmlTree("people", dtd = c("people", "//a//b//c//d", "http://www.omegahat.org/XML/types.dtd"))

     # Using a DTD node directly.
     dtd = newXMLDTDNode(c("people", "", "http://www.omegahat.org/XML/types.dtd"))
     z = xmlTree("people", dtd = dtd)

     x = rnorm(3)
     z = xmlTree("r:data", namespaces = c(r = "http://www.r-project.org"))
     z$addNode("numeric", attrs = c("r:length" = length(x)), close = FALSE)
     lapply(x, function(v) z$addNode("el", x))
     z$closeNode()
     # should give   <r:data><numeric r:length="3"/></r:data>

     # shows namespace prefix on an attribute, and different from the one on the node.
     z = xmlTree()
     z$addNode("r:data",  namespace = c(r = "http://www.r-project.org", omg = "http://www.omegahat.org"), close = FALSE)
     x = rnorm(3)
     z$addNode("r:numeric", attrs = c("omg:length" = length(x)))


     z = xmlTree("people", namespaces = list(r = "http://www.r-project.org"))
     z$setNamespace("r")

     z$addNode("person", attrs = c(id = "123"), close = FALSE)
     z$addNode("firstname", "Duncan")
     z$addNode("surname", "Temple Lang")
     z$addNode("title", "Associate Professor")
     z$addNode("expertize", close = FALSE)
     z$addNode("topic", "Data Technologies")
     z$addNode("topic", "Programming Language Design")
     z$addNode("topic", "Parallel Computing")
     z$addNode("topic", "Data Visualization")
     z$closeTag()
     z$addNode("address", "4210 Mathematical Sciences Building, UC Davis")

