| sink {base} | R Documentation |
Send R Output to a File
Description
sink divertsR output to a connection (and stops such diversions).
sink.number() reports how many diversions are in use.
sink.number(type = "message") reports the number of theconnection currently being used for error messages.
Usage
sink(file = NULL, append = FALSE, type = c("output", "message"), split = FALSE)sink.number(type = c("output", "message"))Arguments
file | a writableconnection or a character string naming thefile to write to, or |
append | logical. If |
type | character string. Either the output stream or the messagesstream. The name will be partially matched so can be abbreviated. |
split | logical: if |
Details
sink divertsR output to a connection (and must be used againto finish such a diversion, see below!). Iffile is acharacter string, a file connection with that name will be establishedfor the duration of the diversion.
NormalR output (to connectionstdout) is diverted bythe defaulttype = "output". Only prompts and (most)messages continue to appear on the console. Messages sent tostderr() (including those frommessage,warning andstop) can be diverted bysink(type = "message") (see below).
sink() orsink(file = NULL) ends the last diversion (ofthe specified type). There is a stack of diversions for normaloutput, so output reverts to the previous diversion (if there wasone). The stack is of up to 21 connections (20 diversions).
Iffile is a connection it will be opened if necessary (in"wt" mode) and closed once it is removed from the stack ofdiversions.
split = TRUE only splitsR output (viaRvprintf) andthe default output fromwriteLines: it does not splitall output that might be sent tostdout().
Sink-ing the messages stream should be done only with great care.For that streamfile must be an already open connection, andthere is no stack of connections.
Iffile is a character string, the file will be opened usingthe current encoding. If you want a different encoding (e.g., torepresent strings which have been stored in UTF-8), use afile connection — but some ways to produceR outputwill already have converted such strings to the current encoding.
Value
sink returnsNULL.
Forsink.number() the number (0, 1, 2, ...) of diversions ofoutput in place.
Forsink.number("message") the connection number used formessages, 2 if no diversion has been used.
Warning
Do not use a connection that is open forsink for any otherpurpose. The software will stop you closing one such inadvertently.
Do not sink the messages stream unless you understand the source codeimplementing it and hence the pitfalls.
References
Becker RA, Chambers JM, Wilks AR (1988).The New S Language.Chapman and Hall/CRC, London.
Chambers JM (1998).Programming with Data.Springer, New York.ISBN 978-0-387-98503-9.
See Also
Examples
sink("sink-examp.txt")i <- 1:10outer(i, i)sink()## capture all the output to a file.zz <- file("all.Rout", open = "wt")sink(zz)sink(zz, type = "message")try(log("a"))## revert output back to the console -- only then access the file!sink(type = "message")sink()file.show("all.Rout", delete.file = TRUE)