R: Read Text Lines from a Connection

readLines {base} | R Documentation

## Read Text Lines from a Connection

### Description

Read some or all text lines from a connection.

### Usage

    readLines(con = stdin(), n = -1L, ok = TRUE, warn = TRUE,
              encoding = "unknown", skipNul = FALSE)

### Arguments

`con` | a connection object or a character string.
`n` | integer. The (maximal) number of lines to read. Negative values indicate that one should read up to the end of input on the connection.
`ok` | logical. Is it OK to reach the end of the connection before `n > 0` lines are read? If not, an error will be generated.
`warn` | logical. Warn if a text file is missing a final EOL or if there are embedded nuls in the file.
`encoding` | encoding to be assumed for input strings. It is used to mark character strings as known to be in Latin-1 or UTF-8: it is not used to re-encode the input. To do the latter, specify the encoding as part of the connection `con` or via `options(encoding=)`: see the examples. See also ‘Details’.
`skipNul` | logical: should nuls be skipped?

### Details

If the `con` is a character string, the function calls `file` to obtain a file connection which is opened for the duration of the function call. This can be a compressed file.

If the connection is open it is read from its current position. If it is not open, it is opened in `"rt"` mode for the duration of the call and then closed (but not destroyed; one must call `close` to do that).

If the final line is incomplete (no final EOL marker) the behaviour depends on whether the connection is blocking or not. For a non-blocking text-mode connection the incomplete line is pushed back, silently. For all other connections the line will be accepted, with a warning.

Whatever mode the connection is opened in, any of LF, CRLF or CR will be accepted as the EOL marker for a line.

Embedded nuls in the input stream will terminate the line currently being read, with a warning (unless `skipNul = TRUE` or `warn = FALSE`).

If `con` is a not-already-open connection with a non-default `encoding` argument, the text is converted to UTF-8 and declared as such (and the `encoding` argument to `readLines` is ignored). See the examples.

### Value

A character vector of length the number of lines read.

The elements of the result have a declared encoding if `encoding` is `"latin1"` or `"UTF-8"`,

### Note

The default connection, `stdin`, may be different from `con = "stdin"`: see `file`.

### See Also

`connections`, `writeLines`, `readBin`, `scan`

### Examples

    fil <- tempfile(fileext = ".data")
    cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = fil,
        sep = "\n")
    readLines(fil, n = -1)
    unlink(fil) # tidy up

    ## difference in blocking
    fil <- tempfile("test")
    cat("123\nabc", file = fil)
    readLines(fil) # line with a warning

    con <- file(fil, "r", blocking = FALSE)
    readLines(con) # empty
    cat(" def\n", file = fil, append = TRUE)
    readLines(con) # gets both
    close(con)

    unlink(fil) # tidy up

    ## Not run:
    # read a 'Windows Unicode' file
    A <- readLines(con <- file("Unicode.txt", encoding = "UCS-2LE"))
    close(con)
    unique(Encoding(A)) # will most likely be UTF-8

    ## End(Not run)

[Package base version 4.0.5 Index]