connection {base}R Documentation

Functions to Manipulate Connections

Description

Functions to create, open, close and position connections.

Usage

file(description, open = "", blocking = TRUE)
pipe(description, open = "")

open(con, open = "rt", blocking = TRUE)
close(con, type = "rw")
seek(con, where = NA, rw = "")

isOpen(con, rw = "")
isIncomplete(con)
isSeekable(con)

Arguments

description character. A description of the connection. For file this is a path to the file to be opened. For a textConnection it is an R character vector object.
open character. A description of how to open the connection (if at all). See Details for possible values.
blocking logical. Currently ignored.
type character. Currently ignored.
where integer. A file position, or NA.
rw character. Currently ignored.

Details

The first two functions create connections. By default the connection is not opened, but may be opened by setting a non-empty value of argument open.

open, close and seek are generic functions: the following applies to the methods relevant to connections.

open opens a connection. In general functions using connections will open them if they are not open, but then close them again, so to leave a connection open call open explicitly.

close closes and destroys a connection.

seek with where = NA returns the current byte offset of a connection (from the beginning), and with a positive where argument the connection is re-positioned (if possible) to the specified position. isSeekable returns whether the connection in principle supports seek: currently only file connections do.

Possible values for the mode open to open a connection are

"r"
or "rt". Open for reading in text mode.
"w"
or "wt". Open for writing in text mode.
"a"
or "at". Open for appending in text mode.
"rb"
Open for reading in binary mode.
"wb"
Open for writing in binary mode.
"ab"
Open for appending in binary mode.

These are likely to change. Some connections (e.g. text connections) can only be opened for reading or writing. For many connections there is little or no difference between text and binary modes, but there is for file-like connections on Windows, and pushBack is text-oriented and is only allowed on connections open for reading in text mode.

Value

file and pipe return a connection object which inherits from class "connection".
seek returns the current position, as a byte offset, if relevant.
isOpen returns a logical value, whether the connection is currently open.
isIncomplete returns a logical value, whether last read attempt was blocked (currently always false), ot for an output text connection whether there is unflushed output.

Note

R's connections are modelled on those in S version 4 (see Chambers, 1998), but the implementation is currently incomplete. In particular:

References

Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer.

See Also

textConnection, readLines, showConnections, pushBack

Examples

zz <- file("ex.data", "w")  # open an output file connection
cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n")
cat("One more line\n", file = zz)
close(zz)
readLines("ex.data")
unlink("ex.data")

## Unix examples of use of pipes

# read listing of current directory
readLines(pipe("ls -1"))

# convert decimal point to comma in output 
zz <- pipe(paste("sed s/\\./,/ >", "outfile"), "w")
cat(format(round(rnorm(100), 4)), sep = "\n", file = zz)
close(zz)
file.show("outfile", delete.file=TRUE)