Last chance! 50% off unlimited learning
Sale ends in
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?
xmlDoc(node, addFinalizer = TRUE)
newXMLDoc(dtd = "", namespaces=NULL, addFinalizer = TRUE,
name = character(), node = NULL, isHTML = FALSE)
newHTMLDoc(dtd = "loose", addFinalizer = TRUE, name = character(),
node = newXMLNode("html",
newXMLNode("head", addFinalizer = FALSE),
newXMLNode("body", addFinalizer = FALSE),
addFinalizer = FALSE))
newXMLNode(name, ..., attrs = NULL, namespace = character(),
namespaceDefinitions = character(),
doc = NULL, .children = list(...), parent = NULL,
at = NA, cdata = FALSE,
suppressNamespaceWarning =
getOption("suppressXMLNamespaceWarning", FALSE),
sibling = NULL, addFinalizer = NA,
noNamespace = length(namespace) == 0 && !missing(namespace),
fixNamespaces = c(dummy = TRUE, default = TRUE))
newXMLTextNode(text, parent = NULL, doc = NULL, cdata = FALSE,
escapeEntities = is(text, "AsIs"), addFinalizer = NA)
newXMLCDataNode(text, parent = NULL, doc = NULL, at = NA, sep = "\n",
addFinalizer = NA)
newXMLCommentNode(text, parent = NULL, doc = NULL, at = NA, addFinalizer = NA)
newXMLPINode(name, text, parent = NULL, doc = NULL, at = NA, addFinalizer = NA)
newXMLDTDNode(nodeName, externalID = character(),
systemID = character(), doc = NULL, addFinalizer = NA)a XMLInternalNode object that will be copied to
create a subtree for a new document.
the name of the DTD to use for the XML document. Currently ignored!
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.net/XML/SHelp")
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.
This can also be the name of a C routine or a reference
to a C routine retrieved using
getNativeSymbolInfo.
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.
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 specified
ideally via the namespaceDefinitions argument,
or even the namespace argument.
The reason is that namespace definitions are special attributes
that are shared across nodes wherease regular attributes are
particular to a node. So a namespace needs to be explicitly defined
so that the XML representation can recognize it as such.
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 vector with a) one element
and b) with an empty names attribute
and c) whose value does not start with http:/ or
ftp:/, then it is assumed that the value is a
namespace prefix for a namespace defined in an ancestor node.
To be able to resolve this prefix to a namespace definition,
parent must be specified so that we can traverse the chain of ancestor nodes.
However, if c) does not hold, i.e. the string starts with http:/ or
ftp:/,
then we take this single element to be a namespace definition and
the since it has no name b), this is the definition for the default namespace for this
new node, i.e. corresponding to xmlns='http:/...'.
It is cumbersome to specify "" as a name for an element in a
character vector (as c('' = 'value') gives an unnecessary
error!.
Elements with names are expanded to namespace definitions
with the name as the prefix and the value as the namespace URI.
the XMLInternalDocument object created with
newXMLDoc that is used to root the node.
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.
the text content for the new XML node
the name of the node to put in the DOCTYPE element that will appear as the top-most node in the XML document.
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.
the SYSTEM identifier for the DTD for the document. This is a URI
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 to remove any ambiguity
that arises when specifying a single string
with no names attribute as the value for namespace.
The values here are used only for defining new namespaces
and not for determining the namespace to use for this
particular node.
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.
if this is specified (rather than parent)
this should be an XMLInternalNode and the new node is added as
a sibling of this node, after this node, i.e. to the right.
This is just a convenient form of parent = xmlParent(node).
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 characters are in
the text, it is useful to use TRUE to ensure that they are
“escaped”.
It is an argument for newXMLNode as the child nodes can be
given as simple strings and are converted to text nodes. This
cdata value is passed to the calls to create these text nodes
and so controls whether they are enclosed within CDATA nodes.
see addChildren
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.
when adding text nodes, this is used as an additional separator text to insert between the specified strings.
a logical value indicating whether to mark the
internal text node in such a way that protects characters in its contents from
being escaped as entities when being serialized via
saveXML
a logical value that allows the caller to specify that the new node has no namespace. This can avoid searching parent and ancestor nodes up the tree for the default namespace.
a logical value that indicates whether the XML document being created is HTML or generic XML. This helps to create an object that is identified as an HTML document.
a logical vector controlling how namespaces in
child nodes are to be processed. The two entries should be named
dummy and default. The dummy element controls
whether we process child nodes that have a namespace which was not
defined when the node was created. These are created as “dummy”
namespaces and can be resolved now that the parent node is defined and
the name space may be defined. When we know it is not yet defined, but
will be defined in an ancestor node, we can turn off this processing
with a value of FALSE.
The default element controls how we process the child nodes
and give them the default name space defined in the parent or ancestor nodes.
Each function returns an R object that points to the
C-level structure instance.
These are of class XMLInternalDocument
and XMLInternalNode, respectively
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.
http://www.w3.org/XML, http://www.xmlsoft.org, http://www.omegahat.net
xmlTree
saveXML
# NOT RUN {
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\n 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.net/XML/types.dtd"))
# public and system
z = xmlTree("people", dtd = c("people", "//a//b//c//d", "http://www.omegahat.net/XML/types.dtd"))
# Using a DTD node directly.
dtd = newXMLDTDNode(c("people", "", "http://www.omegahat.net/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.net"),
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")
#
txt = newXMLTextNode("x < 1")
txt # okay
saveXML(txt) # x < 1
# By escaping the text, we ensure the entities don't
# get expanded, i.e. < doesn't become <
txt = newXMLTextNode(I("x < 1"))
txt # okay
saveXML(txt) # x < 1
newXMLNode("r:expr", newXMLTextNode(I("x < 1")),
namespaceDefinitions = c(r = "http://www.r-project.org"))
# }
Run the code above in your browser using DataLab