source
for extracting the R code elements from an XML document and
evaluating them. This allows for a “simple” way to collect
R functions definitions or a sequence of (annotated) R code segments in an XML
document along with other material such as notes, documentation,
data, FAQ entries, etc., and still be able to
access the R code directly from within an R session.
The approach enables one to use the XML document as a container for
a heterogeneous collection of related material, some of which
is R code.
In the literate programming parlance, this function essentially
dynamically "tangles" the document within R, but can work on
small subsets of it that are easily specified in the
xmlSource function call.
This is a convenient way to annotate code in a rich way
and work with source files in a new and potentially more effective
manner.
xmlSourceFunctions provides a convenient way to read only
the function definitions, i.e. the xmlSourceSection allows us to evaluate the code in one or more
specific sections.
This style of authoring code supports mixed language support
in which we put, for example, C and R code together in the same
document.
Indeed, one can use the document to store arbitrary content
and still retrieve the R code. The more structure there is,
the easier it is to create tools to extract that information
using XPath expressions.
We can identify individual r:code nodes in the document to
process, i.e. evaluate. We do this using their id attribute
and specifying which to process via the ids argument.
Alternatively, if a document has a node r:codeIds as a child of
the top-level node (or within an invisible node), we read its contents as a sequence of line
separated id values as if they had been specified via the
argument ids to this function.
We can also use XSL to extract the code. See getCode.xsl
in the Omegahat XSL collection.
This particular version (as opposed to other implementations) uses XPath to conveniently find the nodes of interest.
xmlSource(url, ..., envir = globalenv(), xpath = character(), ids = character(), omit = character(), ask = FALSE, example = NA, fatal = TRUE, verbose = TRUE, echo = verbose, print = echo, xnodes = DefaultXMLSourceXPath, namespaces = DefaultXPathNamespaces, section = character(), eval = TRUE, init = TRUE, setNodeNames = FALSE, parse = TRUE, force = FALSE)
xmlSourceFunctions(doc, ids = character(), parse = TRUE, ...)
xmlSourceSection(doc, ids = character(), xnodes = c(".//r:function", ".//r:init[not(@eval='false')]", ".//r:code[not(@eval='false')]", ".//r:plot[not(@eval='false')]"), namespaces = DefaultXPathNamespaces, ...)xmlTreeParse
which is called with useInternalNodes = TRUE.
xmlTreeParsexmlSource function's
appropriate method. This argument merely allows for a more
convenient form of those steps, collapsing it into one action.
r:code, r:init, r:function,
r:plot) can have an id attribute. This vector
allows the caller to specify the subset of these nodes
to process, i.e. whose code will be evaluated.
The order is currently not important. It may be used
in the future to specify the order in which the nodes are evaluated. If this is not specified and the document has a node
r:codeIds as an immediate child of the top-most node,
the contents of this node or contained within an invisible
node (so that it doesn't have to be filtered when rendering the
document), the names of the r:code id values to process are taken
as the individual lines from the body of this node.
ids argument.
The order is not important.
r:example nodes in the document.
A single document may contain numerous, separate examples
and these can be marked uniquely using an id attribute,
e.g. . This argument allows the caller to
specify which example (or examples) to run.
If this is not specified by the caller and there are r:example
nodes in the document, the user is prompted to select an example via
a (text-based) menu.
If a character vector is given by the caller, we use
partial matching against the collection of id attributes
of the r:example nodes to identify the examples of interest.
Alternatively, one can specify the example(s) to run by number.
TRUE, information about what
code segments are being evaluated is displayed on the console.
echo controls whether code is displayed, but this controls
whether additional informatin is also displayed.
See source.
XML:::DefaultXPathNamespaces.
section node. A string value is used to
match the id attribute of the section node.
A number (assumed to be an integer) is used to index the set of
section nodes. These amount to XPath expressions of the form
//section[number] and //section[@id = string].
TRUE, the function
will evaluate the code in a node even if it is explicitly marked
as not to be evaluated with eval = "false", either on the node
itself or an ancestor.sapply to
iterate over the nodes and so If the results of all the nodes
A list giving the pairs of expressions and evaluated objects
for each of the different XML elements processed.
code, function and example
elements in the XML content that have the appropriate namespace
(i.e. r, s, or no namespace)
and discards all others. It also discards r:output nodes
from the text, along with processing instructions and comments.
And it resolves r:frag or r:code nodes with a ref
attribute by identifying the corresponding r:code node with the
same value for its id attribute and then evaluating that node
in place of the r:frag reference.
xmlTreeParse
xmlSource(system.file("exampleData", "Rsource.xml", package="XML"))
# This illustrates using r:frag nodes.
# The r:frag nodes are not processed directly, but only
# if referenced in the contents/body of a r:code node
f = system.file("exampleData", "Rref.xml", package="XML")
xmlSource(f)
Run the code above in your browser using DataLab