dcf                   package:base                   R Documentation

Read and Write Data in DCF Format

Description:

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

Usage:

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

Arguments:

    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.

       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.

Details:

     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, a field may appear only 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.

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

     'read.dcf' returns a character matrix with one line 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 of length 0 is
     returned. If the tag name of a fields is never used in a record,
     then 'NA' is returned.  If there are multiple records with the
     same tag name, the last one encountered is returned.  Malformed
     lines are ignored (with a warning).

See Also:

     'write.table'.

Examples:

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

