XML (version 2.3-0)

newXMLDoc: Create internal XML node or document object

Description

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.

newXMLDoc allows one to create a regular XML node with a name and attributes. One can provide new namespace definitions via namespaceDefinitions. While these might also be given in the attributes in the slightly more verbose form of c('xmlns:prefix' = 'http://...'), the result is that the XML node does not interpret that as a namespace definition but merely an attribute with a name 'xmlns:prefix'. Instead, one should specify the namespace definitions via the namespaceDefinitions parameter.

In addition to namespace definitions, a node name can also have a namespace definition. This can be specified in the name argument as prefix:name and newXMLDoc will do the right thing in separating this into the namespace and regular name. Alternatively, one can specify a namespace separately via the namespace argument. This can be either a simple name or an internal namespace object defined earlier.

How do we define a default namespace?

Usage

xmlDoc(node, addFinalizer = FALSE)
newXMLDoc(dtd = NA, namespaces=NULL, addFinalizer = TRUE, 
           name = character(), node = NULL)
newXMLNode(name, ..., attrs = NULL, namespace="",
            namespaceDefinitions = character(),
             doc = NULL, .children = list(...), parent = NULL,
	     at = NA, cdata = FALSE,
             suppressNamespaceWarning =
                 getOption("suppressXMLNamespaceWarning", FALSE))
newXMLTextNode(text, parent = NULL, doc = NULL, cdata = FALSE)
newXMLCDataNode(text, parent = NULL, doc = NULL, at = NA)
newXMLCommentNode(text, parent = NULL, doc = NULL, at = NA)
newXMLPINode(name, text, parent = NULL, doc = NULL, at = NA)
newXMLDTDNode(nodeName, externalID = character(), systemID = character(), doc = NULL)

Arguments

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. Currently ignored!

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

addFinalizer

a logical value indicating whether the default finalizer routine should be registered to free the internal xmlDoc when R no longer has a reference to this external pointer object.

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. One should not use this argument to define namespaces, i.e. attributes of the form xmlns:prefix='http:/...'. Instead, such definitions should be spec

namespace

a character vector specifying the namespace for this new node. Typically this is used to specify i) the prefix of the namespace to use, or ii) one or more namespace definitions, or iii) a combination of both. If this is a character ve

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

systemID

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

namespaceDefinitions

a character vector or a list with each element being a string. These give the URIs identifying the namespaces uniquely. The elements should have names which are used as prefixes. A default namespace has "" as the name. This argument can be used

parent

the node which will act as the parent of this newly created node. This need not be specified and one can add the new node to another node in a separate operation via addChildren.

cdata

a logical value indicating whether to enclose the text within a CDATA node (TRUE) or not (FALSE). This is a convenience mechanism to avoid having to create the text node and then the CDATA node. If one is not certain what

suppressNamespaceWarning

see addChildren

at

this allows one to control the position in the list of children at which the node should be added. The default means at the end and this can be any position from 0 to the current number of children.

Value

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

Details

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.

References

http://www.w3.org/XML, http://www.xmlsoft.org, http://www.omegahat.org

See Also

xmlTree saveXML

Examples

doc = newXMLDoc()

 # Simple creation of an XML tree using these functions
top = newXMLNode("a")
newXMLNode("b", attrs = c(x = 1, y = 'abc'), parent = top)
newXMLNode("c", "With some text", parent = top)
d = newXMLNode("d", newXMLTextNode("With text as an explicit node"), parent = top)
newXMLCDataNode("x <- 1
 x > 2", parent = d)

newXMLPINode("R", "library(XML)", top)
newXMLCommentNode("This is a comment", parent = top)

o = newXMLNode("ol", parent = top)

kids = lapply(letters[1:3],
               function(x)
                  newXMLNode("li", x))
addChildren(o, kids)

cat(saveXML(top))


x = newXMLNode("block", "xyz", attrs = c(id = "bob"),
                      namespace = "fo",
                      namespaceDefinitions = c("fo" = "http://www.fo.org"))

xmlName(x, TRUE) == "fo"

  # a short cut to define a name space and make it the prefix for the
  # node, thus avoiding repeating the prefix via the namespace argument.
x = newXMLNode("block", "xyz", attrs = c(id = "bob"),
                      namespace = c("fo" = "http://www.fo.org"))


 # name space on the attribute
x = newXMLNode("block", attrs = c("fo:id" = "bob"),
                      namespaceDefinitions = c("fo" = "http://www.fo.org"))




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