1% File src/library/utils/man/capture.output.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2019 R Core Team
4% Distributed under GPL 2 or later
5
6\name{capture.output}
7\alias{capture.output}
8\title{Send Output to a Character String or File}
9\description{
10  Evaluates its arguments with the output being returned as a character
11  string or sent to a file.  Related to \code{\link{sink}} similarly to how
12  \code{\link{with}} is related to \code{\link{attach}}.
13}
14\usage{
15capture.output(\dots, file = NULL, append = FALSE,
16               type = c("output", "message"), split = FALSE)
17}
18\arguments{
19  \item{\dots}{Expressions to be evaluated.}
20  \item{file}{A file name or a \link{connection}, or \code{NULL} to return
21    the output as a character vector.  If the connection is not open,
22    it will be opened initially and closed on exit.}
23  \item{append}{logical.  If \code{file} a file name or unopened
24    connection, append or overwrite?}
25  \item{type, split}{are passed to \code{\link{sink}()}, see there.}
26}
27\details{
28  It works via \code{\link{sink}(<file connection>)} and hence the \R code
29  in \code{dots} must \emph{not} interfere with the connection (e.g., by
30  calling \code{\link{closeAllConnections}()}).
31
32  An attempt is made to write output as far as possible to \code{file}
33  if there is an error in evaluating the expressions, but for
34  \code{file = NULL} all output will be lost.
35
36  Messages sent to \code{\link{stderr}()} (including those from
37  \code{\link{message}}, \code{\link{warning}} and \code{\link{stop}})
38  are captured by \code{type = "message"}.  Note that this can be
39  \dQuote{unsafe} and should only be used with care.
40}
41\value{
42  A character string (if \code{file = NULL}), or invisible \code{NULL}.
43}
44
45\seealso{ \code{\link{sink}}, \code{\link{textConnection}} }
46
47\examples{
48require(stats)
49glmout <- capture.output(summary(glm(case ~ spontaneous+induced,
50                                     data = infert, family = binomial())))
51glmout[1:5]
52capture.output(1+1, 2+2)
53capture.output({1+1; 2+2})
54
55\dontrun{## on Unix-alike with a2ps available%% ?? pandoc with obeylines, obeyspaces
56op <- options(useFancyQuotes=FALSE)
57pdf <- pipe("a2ps -o - | ps2pdf - tempout.pdf", "w")
58capture.output(example(glm), file = pdf)
59close(pdf); options(op) ; system("evince tempout.pdf &")
60}% dont
61}
62\keyword{utilities}
63