1% File src/library/utils/man/Rtangle.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2016 R Core Team 4% Distributed under GPL 2 or later 5 6\name{Rtangle} 7\alias{Rtangle} 8\alias{RtangleSetup} 9\title{R Driver for Stangle} 10\description{ 11 A driver for \code{\link{Stangle}} that extracts \R code chunks. 12 Notably all \code{RtangleSetup()} arguments may be used as arguments 13 in the \code{\link{Stangle}()} call. 14} 15\usage{ 16Rtangle() 17RtangleSetup(file, syntax, output = NULL, annotate = TRUE, 18 split = FALSE, quiet = FALSE, drop.evalFALSE = FALSE, ...) 19} 20\arguments{ 21 \item{file}{name of Sweave source file. See the description of the 22 corresponding argument of \code{\link{Sweave}}.} 23 \item{syntax}{an object of class \code{SweaveSyntax}.} 24 \item{output}{name of output file used unless \code{split = TRUE}: 25 see \sQuote{Details}.} 26 \item{annotate}{a logical or \code{\link{function}}. When true, as by 27 default, code chunks are separated by comment lines specifying the 28 names and line numbers of the code chunks. 29 If \code{FALSE} the decorating comments are omitted. Alternatively, 30 \code{annotate} may be a function, see section \sQuote{Chunk annotation}.} 31 \item{split}{split output into a file for each code chunk?} 32 \item{quiet}{logical to suppress all progress messages.} 33 \item{drop.evalFALSE}{logical; When false, as by default, all chunks with 34 option \code{eval = FALSE} are \emph{commented out} in the output; 35 otherwise (\code{drop.evalFALSE = TRUE}) they are omitted entirely.} 36 \item{\dots}{additional named arguments setting defaults for further 37 options listed in \sQuote{Supported Options}.} 38} 39\details{ 40 Unless \code{split = TRUE}, the default name of the output file is 41 \code{basename(file)} with an extension corresponding to the Sweave 42 syntax (e.g., \file{Rnw}, \file{Stex}) replaced by \file{R}. File 43 names \code{"stdout"} and \code{"stderr"} are interpreted as the 44 output and message connection respectively. 45 46 If splitting is selected (including by the options in the file), each 47 chunk is written to a separate file with extension the name of the 48 \sQuote{engine} (default \file{.R}). 49 50 Note that this driver does more than simply extract the code chunks verbatim, 51 because chunks may re-use earlier chunks. 52} 53 54\section{Chunk annotation (\code{annotate})}{ 55 By default \code{annotate = TRUE}, the annotation is of one of the forms% 56\preformatted{################################################### 57### code chunk number 3: viewport 58################################################### 59 60################################################### 61### code chunk number 18: grid.Rnw:647-648 62################################################### 63 64################################################### 65### code chunk number 19: trellisdata (eval = FALSE) 66################################################### 67} 68 using either the chunk label (if present, i.e., when specified in the 69 source) or the file name and line numbers. 70 71 \code{annotate} may be a function with formal arguments 72 \code{(options, chunk, output)}, e.g. to produce less dominant chunk 73 annotations; see \code{Rtangle()$runcode} how it is called instead of 74 the default. 75} 76 77\section{Supported Options}{ 78 \code{Rtangle} supports the following options for code chunks (the 79 values in parentheses show the default values): 80 \describe{ 81 \item{engine:}{character string (\code{"R"}). Only chunks with 82 \code{engine} equal to \code{"R"} or \code{"S"} are processed.} 83 84 \item{keep.source:}{logical (\code{TRUE}). If 85 \code{keep.source == TRUE} the original source is copied to the 86 file. Otherwise, deparsed source is output.} 87 88 \item{eval:}{logical (\code{TRUE}). If \code{FALSE}, the code chunk 89 is copied across but commented out.} 90 91 \item{prefix}{Used if \code{split = TRUE}. See \code{prefix.string}.} 92 93 \item{prefix.string:}{a character string, default is the name of the 94 source file (without extension). Used if \code{split = TRUE} as 95 the prefix for the filename if the chunk has no label, or if it 96 has a label and \code{prefix = TRUE}. Note that this is used as 97 part of filenames, so needs to be portable.} 98 99 \item{show.line.nos}{logical (\code{FALSE}). Should the output be 100 annotated with comments showing the line number of the first code line 101 of the chunk?} 102 } 103} 104 105\author{Friedrich Leisch and R-core.} 106\seealso{ 107 \sQuote{\href{../doc/Sweave.pdf}{Sweave User Manual}}, a vignette in 108 the \pkg{utils} package.%% ../vignettes/Sweave.Rnw 109 110 \code{\link{Sweave}}, \code{\link{RweaveLatex}} 111} 112\examples{ 113nmRnw <- "example-1.Rnw" 114exfile <- system.file("Sweave", nmRnw, package = "utils") 115## Create R source file 116Stangle(exfile) 117nmR <- sub("Rnw$", "R", nmRnw) # the (default) R output file name 118if(interactive()) file.show("example-1.R") 119\dontshow{file.rename("example-1.R", "example-1_def.R")} 120## Smaller R source file with custom annotation: 121my.Ann <- function(options, chunk, output) { 122 cat("### chunk #", options$chunknr, ": ", 123 if(!is.null(ol <- options$label)) ol else .RtangleCodeLabel(chunk), 124 if(!options$eval) " (eval = FALSE)", "\n", 125 file = output, sep = "") 126} 127Stangle(exfile, annotate = my.Ann) 128if(interactive()) file.show("example-1.R") 129\dontshow{file.rename("example-1.R", "example-1_myA.R")} 130Stangle(exfile, annotate = my.Ann, drop.evalFALSE=TRUE) 131if(interactive()) file.show("example-1.R") 132\dontshow{file.rename("example-1.R", "example-1_myA-noF.R")} 133} 134\keyword{utilities} 135