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