R: R Driver for Stangle

Rtangle {utils} | 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.

### See Also

‘Sweave User Manual’, a vignette in the utils package.

`Sweave`, `RweaveLatex`

### 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")

[Package utils version 4.0.5 Index]