dcf                   package:base                   R Documentation

_R_e_a_d _a_n_d _W_r_i_t_e _D_a_t_a _i_n _D_C_F _F_o_r_m_a_t

_D_e_s_c_r_i_p_t_i_o_n:

     Reads or writes an R object from/to a file in Debian Control File
     format.

_U_s_a_g_e:

     read.dcf(file, fields = NULL, all = FALSE)

     write.dcf(x, file = "", append = FALSE,
               indent = 0.1 * getOption("width"),
               width = 0.9 * getOption("width"))

_A_r_g_u_m_e_n_t_s:

    file: either a character string naming a file or a connection. '""'
          indicates output to the console.  For 'read.dcf' this can
          name a 'gzip'-compressed file.

  fields: Fields to read from the DCF file.  Default is to read all
          fields.

     all: a logical indicating whether in case of multiple occurrences
          of a field in a record, all these should be gathered. If
          'all' is false (default), only the last such occurrence is
          used.

       x: the object to be written, typically a data frame.  If not, it
          is attempted to coerce 'x' to a data frame.

  append: logical.  If 'TRUE', the output is appended to the file.  If
          'FALSE', any existing file of the name is destroyed.

  indent: a positive integer specifying the indentation for
          continuation lines in output entries.

   width: a positive integer giving the target column for wrapping
          lines in the output.

_D_e_t_a_i_l_s:

     DCF is a simple format for storing databases in plain text files
     that can easily be directly read and written by humans.  DCF is
     used in various places to store R system information, like
     descriptions and contents of packages.

     The DCF rules as implemented in R are:

        1.  A database consists of one or more records, each with one
           or more named fields.  Not every record must contain each
           field. Fields may appear more than once in a record.

        2.  Regular lines start with a non-whitespace character.

        3.  Regular lines are of form 'tag:value', i.e., have a name
           tag and a value for the field, separated by ':' (only the
           first ':' counts).  The value can be empty (=whitespace
           only).

        4.  Lines starting with whitespace are continuation lines (to
           the preceding field) if at least one character in the line
           is non-whitespace.  Continuation lines where the only
           non-whitespace character is a '.' are taken as blank lines
           (allowing for multi-paragraph field values).

        5.  Records are separated by one or more empty (=whitespace
           only) lines.

     By default, 'read.dcf' returns a character matrix with one row per
     record and one column per field.  Leading and trailing whitespace
     of field values is ignored.  If a tag name is specified, but the
     corresponding value is empty, then an empty string is returned. 
     If the tag name of a field is never used in a record, then 'NA' is
     returned.  If fields are repeated within a record, the last one
     encountered is returned.  Malformed lines lead to an error.  If
     'all' is true, a data frame is returned, again with one row per
     record and one column per field, and columns lists of character
     vectors for fields with multiple occurrences, and character
     vectors otherwise.

     'write.dcf' does not write 'NA' fields.

_S_e_e _A_l_s_o:

     'write.table'.

_E_x_a_m_p_l_e_s:

     ## Create a reduced version of the 'CONTENTS' file in package 'splines'
     x <- read.dcf(file = system.file("CONTENTS", package = "splines"),
                   fields = c("Entry", "Description"))
     write.dcf(x)