Sweave Drivers with Extra Tricks Up their Sleeve

Description

Weave and tangle drivers for Sweave extending the standard drivers. RweaveExtraLatex and RtangleExtra provide options to completely ignore code chunks on weaving, tangling, or both. Chunks ignored on weaving are not parsed, yet are written out verbatim on tangling. Chunks ignored on tangling may be evaluated as usual on weaving, but are completely left out of the tangled scripts. The driver RtangleExtra also provides options to control the separation between code chunks in the tangled script, and to specify the extension of the file name (or remove it entirely) when splitting is selected.

Details

The RweaveExtraLatex and RtangleExtra drivers extend the standard Sweave drivers RweaveLatex and Rtangle, respectively. They are selected through the driver argument of Sweave.

The drivers provide additional options to completely ignore code chunks on weaving, tangling, or both. Chunks ignored on weaving are not parsed and are written out verbatim on tangling. Chunks ignored on tangling are processed as usual on weaving, but completely left out of the tangled scripts. The driver RtangleExtra furthermore provides two additional options: chunk.sep to control the separation (or remove it entirely) between code chunks in the tangled script; extension to specify the extension of the file name (or remove it entirely) when splitting is selected.

In a literate programming workflow, the additional options allow to include code chunks in a file such as:

• code that is not parsable by R (say, because of errors inserted for educational purposes);

• code in another programming language entirely (say, a shell script to start an analysis);

• code for a Shiny app.

With the standard drivers, using option eval = FALSE results in code being commented out in tangled scripts files. Chunks may be omitted on tangling with drop.evalFALSE = TRUE, but only provided the chunk is not evaluated on weaving. Therefore, the standard drivers have no provision to either omit a chunk on weaving and tangle it as is, or to process a chunk on weaving but omit it on tangling.

Author(s)

Vincent Goulet [cre, aut], R Core Team [aut] (Code from the original Sweave drivers)

Maintainer: Vincent Goulet <vincent.goulet@act.ulaval.ca>

R Driver for Stangle with Additional Options

Description

A driver for Sweave extending the standard driver Rtangle with additional code chunk options.

Usage

RtangleExtra()

RtangleExtraSetup(file, syntax, output = NULL, annotate = TRUE,
                  split = FALSE, quiet = FALSE, drop.evalFALSE = FALSE,
                  ignore.on.tangle = FALSE, ignore = FALSE,
                  extension = TRUE, chunk.sep = "\n\n", ...)

Arguments

Details

Chunks ignored on tangling are not written out to script files, but they are processed normally on weaving (unless ignore = TRUE). Therefore, chunks may still use eval = TRUE for weaving purposes, yet not be tangled.

The argument extension is specially useful with ignore.on.weave = TRUE of RweaveExtraLatex to include code or text that the engine would not be able to parse.

The argument chunk.sep offers control over the chunk separator that the standard Rtangle driver does not. The chunk separator is added before all chunks, except the first one. Therefore, no chunk separator follows the last chunk. No newline (aka ‘line feed’) is added to the value of the argument. Using control characters (e.g. ‘⁠\n⁠’) in a code chunk option is not supported.

Value

Named list of five functions; see Sweave or the ‘Sweave User Manual’ vignette in the utils package.

Author(s)

Vincent Goulet, based on work by Friedrich Leisch and R-core.

See Also

RweaveExtraLatex, Rtangle, Sweave.

Examples

testfile <- system.file("examples", "example-extra.Rnw",
                        package = "RweaveExtra")


## Check the contents of the file
if (interactive()) file.show(testfile)

## Tangle the file in the current working directory
Stangle(testfile, driver = RtangleExtra())

## View tangled file
if (interactive()) file.show("example-extra.R")

## Reduce to spacing between code chunks to a single
## blank line
Stangle(testfile, driver = RtangleExtra(), chunk.sep = "\n")
if (interactive()) file.show("example-extra.R")

## The effect of 'chunk.sep=FALSE' in the second chunk
## is more interesting without the annotations
Stangle(testfile, driver = RtangleExtra(),
        annotate = FALSE, chunk.sep = "\n")
if (interactive()) file.show("example-extra.R")

## Use 'extension=sh' with 'ignore.on.weave=TRUE', and
## the options 'split=TRUE' and 'prefix=FALSE' of Stangle
## to extract the shell script to a file 'hello.sh'
Stangle(testfile, driver = RtangleExtra(),
        split = TRUE, annotate = FALSE)
if (interactive()) file.show("hello.sh")

R/LaTeX Driver for Sweave with Additional Options

Description

A driver for Sweave extending the standard driver RweaveLatex with additional code chunk options.

Usage

RweaveExtraLatex()

RweaveExtraLatexSetup(file, syntax, output = NULL, quiet = FALSE,
                      debug = FALSE, stylepath, ignore.on.weave = FALSE,
                      ignore = FALSE, ...)

Arguments

Details

Chunks ignored on weaving are not parsed and are not evaluated, but they are written out on tangling as normal code chunks (unless ignore=TRUE).

If ignore.on.weave or ignore is FALSE, the code chunk is processed using the standard driver RweaveLatex with its options.

Value

Named list of five functions; see Sweave or the ‘Sweave User Manual’ vignette in the utils package.

Author(s)

Vincent Goulet, based on work by Friedrich Leisch and R-core.

See Also

RtangleExtra, RweaveLatex, Sweave.

Examples

testfile <- system.file("examples", "example-extra.Rnw", package = "RweaveExtra")

## Check the contents of the file
if(interactive()) file.show(testfile)

## Weave, then tangle the file in the current working directory
Sweave(testfile, driver = RweaveExtraLatex())
Stangle(testfile, driver = RtangleExtra())

## View weaved and tangled files
if(interactive()) file.show("example-extra.tex")
if(interactive()) file.show("example-extra.R")

RweaveExtra Driver Utilities

Description

These functions are considered internal and hence not documented. The first mostly calls makeRweaveLatexCodeRunner, whereas the second is a modified version of RtangleRuncode, both from package utils.

Usage

RweaveExtraLatexRuncode(object, chunk, options)
RtangleExtraRuncode(object, chunk, options)

Value

No return value; called for their side effects.

Author(s)

Vincent Goulet, based on work by Friedrich Leisch, R-core and Seth Falcon.

See Also

Sweave, RweaveLatex, Rtangle.

File Processed by Sweave or Stangle

Description

Extract the name of the file currently processed by Sweave or Stangle in a non-interactive session.

Usage

SweaveGetSourceName()

Details

The function returns the name of the source file being processed by Sweave or Stangle when the tool is invoked from the command line through either:

1. an expression passed to R -e or Rscript;

2. R CMD Sweave or R CMD Stangle.

In the first scenario, the filename must be the first, unnamed argument to Sweave or Stangle.

This function cannot be used from an interactive R session.

Value

Filename as a character string.

Author(s)

Vincent Goulet

Examples

testfile <- system.file("examples", "example-source.Rnw",
                        package = "RweaveExtra")

## Check the contents of the file
if (interactive()) file.show(testfile)

## Sweave the file in a separate process
expr <- paste0("Sweave('", testfile, "', ",
               "encoding = 'utf-8')")
system2("R", c("-e", paste0("\"", expr, "\"")))

## View woven file
if (interactive()) file.show("example-source.tex")

## Stangle was called from within Sweave in the file
if (interactive()) file.show("example-source.R")

## Repeat using 'R CMD Sweave'
system2("R", c("CMD", "Sweave", testfile, "--encoding=utf-8"))
if (interactive()) file.show("example-source.tex")
if (interactive()) file.show("example-source.R")

## Do not use the function interactively
## Not run: SweaveGetSourceName()