textConnection             package:base             R Documentation

_T_e_x_t _C_o_n_n_e_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Input and output text connections.

_U_s_a_g_e:

     textConnection(object, open = "r", local = FALSE)

     textConnectionValue(con)

_A_r_g_u_m_e_n_t_s:

  object: character.  A description of the connection.  For an input
          this is an R character vector object, and for an output
          connection the name for the R character vector to receive the
          output, or 'NULL' (for none). 

    open: character.  Either '"r"' (or equivalently '""') for an input
          connection or '"w"' or '"a"' for an output connection.

   local: logical.  Used only for output connections.  If 'TRUE',
          output is assigned to a variable in the calling environment. 
          Otherwise the global environment is used.

     con: An output text connection.

_D_e_t_a_i_l_s:

     An input text connection is opened and the character vector is
     copied at time the connection object is created, and 'close'
     destroys the copy.

     An output text connection is opened and creates an R character
     vector of the given name in the user's workspace or in the calling
     environment, depending on the value of the 'local' argument.  This
     object will at all times hold the completed lines of output to the
     connection, and 'isIncomplete' will indicate if there is an
     incomplete final line.  Closing the connection will output the
     final line, complete or not.  (A line is complete once it has been
     terminated by end-of-line, represented by '"\n"' in R.)   The
     output character vector has locked bindings (see 'lockBinding')
     until 'close' is called on the connection.  The character vector
     can also be retrieved _via_ 'textConnectionValue', which is the
     only way to do so if 'object = NULL'.  If the current locale is
     detected as Latin-1 or UTF-8, non-ASCII elements of the character
     vector will be marked accordingly (see 'Encoding').

     Opening a text connection with 'mode = "a"' will attempt to append
     to an existing character vector with the given name in the user's
     workspace or the calling environment.  If none is found (even if
     an object exists of the right name but the wrong type) a new
     character vector will be created, with a warning.

     You cannot 'seek' on a text connection, and 'seek' will always
     return zero as the position.

_V_a_l_u_e:

     For 'textConnection', a connection object of class
     '"textConnection"' which inherits from class '"connection"'.

     For 'textConnectionValue', a character vector.

_N_o_t_e:

     As output text connections keep the character vector up to date
     line-by-line, they are relatively expensive to use, and it is
     often better to use an anonymous 'file()' connection to collect
     output.

     On (rare) platforms where 'vsnprintf' does not return the needed
     length of output there is a 100,000 character limit on the length
     of line for output connections: longer lines will be truncated
     with a warning.

_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 has input text connections only.]

_S_e_e _A_l_s_o:

     'connections', 'showConnections', 'pushBack', 'capture.output'.

_E_x_a_m_p_l_e_s:

     zz <- textConnection(LETTERS)
     readLines(zz, 2)
     scan(zz, "", 4)
     pushBack(c("aa", "bb"), zz)
     scan(zz, "", 4)
     close(zz)

     zz <- textConnection("foo", "w")
     writeLines(c("testit1", "testit2"), zz)
     cat("testit3 ", file=zz)
     isIncomplete(zz)
     cat("testit4\n", file=zz)
     isIncomplete(zz)
     close(zz)
     foo

     ## Not run: 
     # capture R output: use part of example from help(lm)
     zz <- textConnection("foo", "w")
     ctl <- c(4.17, 5.58, 5.18, 6.11, 4.5, 4.61, 5.17, 4.53, 5.33, 5.14)
     trt <- c(4.81, 4.17, 4.41, 3.59, 5.87, 3.83, 6.03, 4.89, 4.32, 4.69)
     group <- gl(2, 10, 20, labels = c("Ctl", "Trt"))
     weight <- c(ctl, trt)
     sink(zz)
     anova(lm.D9 <- lm(weight ~ group))
     cat("\nSummary of Residuals:\n\n")
     summary(resid(lm.D9))
     sink()
     close(zz)
     cat(foo, sep = "\n")
     ## End(Not run)