connection               package:base               R Documentation

_F_u_n_c_t_i_o_n_s _t_o _M_a_n_i_p_u_l_a_t_e _C_o_n_n_e_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Functions to create, open, close and position connections.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

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.

_D_e_t_a_i_l_s:

     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.

     `"_r_b"' Open for reading in binary mode.

     `"_w_b"' Open for writing in binary mode.

     `"_a_b"' 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.

_V_a_l_u_e:

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

_N_o_t_e:

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

        *  Pipes are only implemented on Unix and `Rterm' on Windows.
           Fifos are not yet implemented. We also envisage having
           connections to sockets.

        *  Svr4 has separate read and write positions for files: R does
           not.

        *  Svr4 allow an empty description to `file' to indicate an
           anonymous (temporary) file.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     `textConnection', `readLines', `showConnections', `pushBack'

_E_x_a_m_p_l_e_s:

     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"))

     # remove trailing commas. Suppose
     450, 390, 467, 654,  30, 542, 334, 432, 421,
     357, 497, 493, 550, 549, 467, 575, 578, 342,
     446, 547, 534, 495, 979, 479
     # Then read this by
     scan(pipe("sed -e s/,$// data2"), sep=",")

     # 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)

