Rtangle
R Driver for Stangle
A driver for Stangle
that extracts R code chunks.
Notably all RtangleSetup()
arguments may be used as arguments
in the Stangle()
call.
- Keywords
- utilities
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. IfFALSE
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 withengine
equal to"R"
or"S"
are processed.- keep.source:
logical (
TRUE
). Ifkeep.source == TRUE
the original source is copied to the file. Otherwise, deparsed source is output.- eval:
logical (
TRUE
). IfFALSE
, the code chunk is copied across but commented out.- prefix
Used if
split = TRUE
. Seeprefix.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 andprefix = 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?
See Also
‘Sweave User Manual’, a vignette in the utils package.
Examples
library(utils)
# NOT RUN {
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")
# }
# NOT RUN {
## 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")
# }
# NOT RUN {
Stangle(exfile, annotate = my.Ann, drop.evalFALSE=TRUE)
if(interactive()) file.show("example-1.R")
# }