XML (version 3.1-1)

xmlSource: Source the R code, examples, etc. from an XML document

Description

This is the equivalent of a smart 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 nodes. We can restrict to a subset by specifying the node ids of interest.

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.

Usage

xmlSource(url, ...,
          envir = globalenv(),
          xpath = character(),
          ids = character(),
          omit = character(),
          ask = FALSE,
          example = NA,
          fatal = TRUE, verbose = FALSE, echo = verbose, print = echo,
          xnodes = c("//r:function", 
                     "//r:init[not(@eval='false')]",
                     "//r:code[not(@eval='false')]",
                     "//r:plot[not(@eval='false')]"),
          namespaces = DefaultXPathNamespaces, section = character(),
          eval = TRUE, init = TRUE)
xmlSourceFunctions(doc, ids = character(), ...)
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, ...)

Value

• An R object (typically a list) that contains the results of evaluating the content of the different selected code segments in the XML document. We use 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.

concept

• Annotated code
• Literate Programming
• Mixed language

Details

This evaluates the 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.

See Also

xmlTreeParse

Examples

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)