readLines                package:base                R Documentation

_R_e_a_d _T_e_x_t _L_i_n_e_s _f_r_o_m _a _C_o_n_n_e_c_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     Read some or all text lines from a connection.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

     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 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.

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 example under 'file'. 

_D_e_t_a_i_l_s:

     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.

     If the connection is open it is read from its current position. If
     it is not open, it is opened for the duration of the call and then
     closed again.

     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.

_V_a_l_u_e:

     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"',

_N_o_t_e:

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

_S_e_e _A_l_s_o:

     'connections', 'writeLines', 'readBin', 'scan'

_E_x_a_m_p_l_e_s:

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

     ## difference in blocking
     cat("123\nabc", file = "test1")
     readLines("test1") # line with a warning

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

     unlink("test1") # tidy up

