R: Read and Write Data in DCF Format

dcf {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, all = FALSE)

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

### 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. 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 are ignored (with a warning). 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.

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

[Package base version 2.6.2 Index]