https://github.com/cran/XML
Tip revision: 3a07a987862761e82155132624e23012048a7341 authored by CRAN Team on 25 June 2024, 13:05:01 UTC
version 3.99-0.17
version 3.99-0.17
Tip revision: 3a07a98
newXMLDoc.Rd
% insert facilities
\name{newXMLDoc}
\alias{newXMLDoc}
\alias{newHTMLDoc}
\alias{newXMLNode}
\alias{newXMLPINode}
\alias{newXMLCDataNode}
\alias{newXMLCommentNode}
\alias{newXMLTextNode}
\alias{newXMLDTDNode}
\alias{xmlDoc}
\alias{coerce,vector,XMLInternalNode-method}
\title{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 \code{\link{xmlTree}}
as the functions need to be used within a strict regime to avoid
corrupting C level structures.
\code{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.
\code{newXMLDoc} allows one to create a regular XML node
with a name and attributes.
One can provide new namespace definitions via
\code{namespaceDefinitions}. While these might also
be given in the attributes in the slightly more verbose
form of \code{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 \code{namespaceDefinitions} parameter.
In addition to namespace definitions, a node name can also have a
namespace definition. This can be specified in the \code{name} argument
as \code{prefix:name} and \code{newXMLDoc} will do the right thing in
separating this into the namespace and regular name. Alternatively, one
can specify a namespace separately via the \code{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 = 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)
}
\arguments{
\item{node}{a \code{XMLInternalNode} object that will be copied to
create a subtree for a new document.}
\item{dtd}{the name of the DTD to use for the XML document.
Currently ignored!}
\item{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. \code{c(shelp = "https://www.omegahat.net/XML/SHelp")}}
\item{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.
This can also be the name of a C routine or a reference
to a C routine retrieved using
\code{\link{getNativeSymbolInfo}}. }
\item{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.}
\item{...}{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.}
\item{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 \code{xmlns:prefix='http:/...'}.
Instead, such definitions should be specified
ideally via the \code{namespaceDefinitions} argument,
or even the \code{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.
}
\item{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 vector with a) one element
and b) with an empty \code{names} attribute
and c) whose value does not start with \code{http:/} or
\code{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,
\code{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 \code{http:/} or
\code{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 \code{xmlns='http:/...'}.
It is cumbersome to specify \code{""} as a name for an element in a
character vector (as \code{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.
}
\item{doc}{the \code{XMLInternalDocument} object created with
\code{newXMLDoc} that is used to root the node.}
\item{.children}{a list containing XML node elements or content.
This is an alternative form of specifying the child nodes than \dots
which is useful for programmatic interaction when the "sub"-content is
already in a list rather than a loose collection of values.}
\item{text}{the text content for the new XML node}
\item{nodeName}{the name of the node to put in the DOCTYPE element
that will appear as the top-most node in the XML document.}
\item{externalID}{the PUBLIC identifier for the document type.
This is a string of the form \code{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.}
\item{systemID}{the SYSTEM identifier for the DTD for the document.
This is a URI}
\item{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 to remove any ambiguity
that arises when specifying a single string
with no names attribute as the value for \code{namespace}.
The values here are used only for defining new namespaces
and not for determining the namespace to use for this
particular node.
}
\item{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
\code{\link{addChildren}}.}
\item{sibling}{if this is specified (rather than \code{parent})
this should be an \code{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 \code{parent = xmlParent(node)}.}
\item{cdata}{a logical value indicating whether to enclose the text
within a CDATA node (\code{TRUE}) or not (\code{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 \code{TRUE} to ensure that they are
\dQuote{escaped}.
It is an argument for \code{newXMLNode} as the child nodes can be
given as simple strings and are converted to text nodes. This
\code{cdata} value is passed to the calls to create these text nodes
and so controls whether they are enclosed within CDATA nodes.
}
\item{suppressNamespaceWarning}{see \code{\link{addChildren}}}
\item{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.}
\item{sep}{when adding text nodes, this is used as an additional separator text to insert between the specified strings.}
\item{escapeEntities}{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
\code{\link{saveXML}}}
\item{noNamespace}{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.}
\item{isHTML}{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.}
\item{fixNamespaces}{a logical vector controlling how namespaces in
child nodes are to be processed. The two entries should be named
\code{dummy} and \code{default}. The \code{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 \dQuote{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 \code{FALSE}.
The \code{default} element controls how we process the child nodes
and give them the default name space defined in the parent or ancestor nodes.}
}
\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.
}
\value{
Each function returns an R object that points to the
C-level structure instance.
These are of class \code{XMLInternalDocument}
and \code{XMLInternalNode}, respectively
}
\references{\url{https://www.w3.org/XML/}, \url{http://www.xmlsoft.org},
\url{https://www.omegahat.net}}
\author{ Duncan Temple Lang }
\note{These functions are used to build up an internal XML tree.
This can be used in the Sxslt package (\url{https://www.omegahat.net/Sxslt/})
when creating content in R that is to be dynamically inserted into an XML
document.}
\seealso{
\code{\link{xmlTree}}
\code{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\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", "", "https://www.omegahat.net/XML/types.dtd"))
# public and system
z = xmlTree("people", dtd = c("people", "//a//b//c//d", "https://www.omegahat.net/XML/types.dtd"))
# Using a DTD node directly.
dtd = newXMLDTDNode(c("people", "", "https://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 = "https://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 &lt; 1
# By escaping the text, we ensure the entities don't
# get expanded, i.e. < doesn't become &lt;
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"))
}
\keyword{IO}