Find an R package R language docs Run R in your browser

Rtangle: R Driver for Stangle

Rtangle

R Documentation

R Driver for Stangle

Description

A driver for Stangle that extracts R code chunks. Notably all RtangleSetup() arguments may be used as arguments in the Stangle() call.

Usage

Rtangle()
RtangleSetup(file, syntax, output = NULL, annotate = TRUE,
             split = FALSE, quiet = FALSE, drop.evalFALSE = FALSE, ...)

Arguments

`file`	name of Sweave source file. See the description of the corresponding argument of `Sweave`.
`syntax`	an object of class `SweaveSyntax`.
`output`	name of output file used unless `split = TRUE`: see ‘Details’.
`annotate`	a logical or `function`. When true, as by default, code chunks are separated by comment lines specifying the names and line numbers of the code chunks. If `FALSE` the decorating comments are omitted. Alternatively, `annotate` may be a function, see section ‘Chunk annotation’.
`split`	split output into a file for each code chunk?
`quiet`	logical to suppress all progress messages.
`drop.evalFALSE`	logical; When false, as by default, all chunks with option `eval = FALSE` are commented out in the output; otherwise (`drop.evalFALSE = TRUE`) they are omitted entirely.
`...`	additional named arguments setting defaults for further options listed in ‘Supported Options’.

Details

Unless split = TRUE, the default name of the output file is basename(file) with an extension corresponding to the Sweave syntax (e.g., ‘Rnw’, ‘Stex’) replaced by ‘R’. File names "stdout" and "stderr" are interpreted as the output and message connection respectively.

If splitting is selected (including by the options in the file), each chunk is written to a separate file with extension the name of the ‘engine’ (default ‘.R’).

Note that this driver does more than simply extract the code chunks verbatim, because chunks may re-use earlier chunks.

Chunk annotation (`annotate`)

By default annotate = TRUE, the annotation is of one of the forms

###################################################
### code chunk number 3: viewport
###################################################

###################################################
### code chunk number 18: grid.Rnw:647-648
###################################################

###################################################
### code chunk number 19: trellisdata (eval = FALSE)
###################################################

using either the chunk label (if present, i.e., when specified in the source) or the file name and line numbers.

annotate may be a function with formal arguments (options, chunk, output), e.g. to produce less dominant chunk annotations; see Rtangle()$runcode how it is called instead of the default.

Supported Options

Rtangle supports the following options for code chunks (the values in parentheses show the default values):

engine:: character string ("R"). Only chunks with engine equal to "R" or "S" are processed.
keep.source:: logical (TRUE). If keep.source == TRUE the original source is copied to the file. Otherwise, deparsed source is output.
eval:: logical (TRUE). If FALSE, the code chunk is copied across but commented out.
prefix: Used if split = TRUE. See prefix.string.
prefix.string:: a character string, default is the name of the source file (without extension). Used if split = TRUE as the prefix for the filename if the chunk has no label, or if it has a label and prefix = TRUE. Note that this is used as part of filenames, so needs to be portable.
show.line.nos: logical (FALSE). Should the output be annotated with comments showing the line number of the first code line of the chunk?

Author(s)

Friedrich Leisch and R-core.

Examples

nmRnw <- "example-1.Rnw"
exfile <- system.file("Sweave", nmRnw, package = "utils")
## Create R source file
Stangle(exfile)
nmR <- sub("Rnw$", "R", nmRnw) # the (default) R output file name
if(interactive()) file.show("example-1.R")

## Smaller R source file with custom annotation:
my.Ann <- function(options, chunk, output) {
  cat("### chunk #", options$chunknr, ": ",
      if(!is.null(ol <- options$label)) ol else .RtangleCodeLabel(chunk),
      if(!options$eval) " (eval = FALSE)", "\n",
      file = output, sep = "")
}
Stangle(exfile, annotate = my.Ann)
if(interactive()) file.show("example-1.R")

Stangle(exfile, annotate = my.Ann, drop.evalFALSE=TRUE)
if(interactive()) file.show("example-1.R")