dcf
Read and Write Data in DCF Format
Description
Reads from or writes to a file in the Debian Control File format.
Usage
read.dcf(file, fields = NULL, all = FALSE, keep.white = NULL, overrideSuffix = "TERR")
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 object.
|
| fields |
the fields to read. By default, reads all fields.
|
| all |
a logical value.
If TRUE, all occurrences of a field with the same name in a record
are returned. If FALSE (the default), only the last occurrence of
a field with a given name is returned.
|
| keep.white |
A character vector (or NULL) giving the names of fields from which
leading and trailing whitespace characters should not be removed, so the
original formatting is retained.
|
| overrideSuffix |
A character string or NULL to be used when the value of an entry
in a dcf file depends on whether you are using open source R or
TIBCO Enterprise Runtime for R, abbreviated TERR.
If not NULL, then this suffix is removed
from all tags in the DCF file that end with overrideSuffix. Hence,
tags identical except for the presence of a trailing overrideSuffix
are considered identical.
When all is FALSE the last of a set of identically
tagged lines is taken as the value of the tag so if you place the line
TagTERR: Value for use with TIBCO Enterprise Runtime for R
after Tag: value then Tag will
have the value "Value for use with TIBCO Enterprise Runtime for R" in
TIBCO Enterprise Runtime for R and "value" in R.
|
| x |
the object to write. If it is not a data.frame object, it is
coerced to be a data.frame object with
x <- data.frame(x, stringsAsFactors=FALSE).
|
| append |
a logical value. If FALSE (the default), the contents of the
existing file are deleted and the output overwrites
the file. If TRUE, the output is appended to the file.
If you want to append a new record to the file, you
must add the separating empty line with a command such as
cat(file=file, append=TRUE, "\n") between calls to
write.dcf.
|
| indent |
a nonnegative integer value. If the output for write.dcf exceeds the
line width restriction specified by width, indent
specifies the number of spaces to indent additional text on subsequent
lines. (indent is passed to strwrap).
|
| width |
a positive integer specifying the target column for wrapping lines
in the output (width is passed to strwrap).
|
Details
The DCF format stores the contents of databases as plain text files for
easy reading. We use DCF to store system information (for example,
descriptions, contents of packages, and so on).
read.dcf and
write.dcf use the following rules for DCF files:
- A database consists of one or more records, each with one or
more named fields. Not every record must contain each field. A
field should appear only once in a record, although the all=TRUE
option lets one read a file with duplicate fields. See Value for
more information.
- Regular lines are of form tag:value with no
whitespace (space or tab) before the tag. Whitespace
before or after the value is removed. The value can be empty.
- Lines starting with whitespace are read as continuation lines (of the
preceding field) if at least one character in the line is non-whitespace.
If a continuation line's only non-whitespace character is a
period (.), then this line is displayed as an empty line
in TIBCO Enterprise Runtime for R (stored as two adjacent newlines).
- Records are separated by one or more empty lines.
- The write.dcf does not write NA fields.
Value
| read.dcf |
- if all is FALSE, returns a character
matrix with one column per unique field name and one row per record.
The columns are named for the fields; the rows are unnamed. If a field in
the file contains multiple lines, such entries are read in with newlines
where line breaks in the original field were. If a field is not present
for a record in the file, an entry for a that field name is set to
NA_character_.
- if all is TRUE, returns a
data.frame with the same row and column structure as that returned
when all is FALSE. All columns are character vectors
unless a given field in a record contains a duplicate entry, in which
case that column is a list of character strings.
|
| write.dcf | always returns the value NULL. |
See Also
Examples
# Make and read a DCF file with 2 records
x <- data.frame(
Package=c("myPkg", "yourPkg"),
Version=c("1.2-3", "2.1"),
Description=c("A two 'paragraph`\n\ndescription of myPkg",
"yourPkg is useful"))
dcfFile <- file.path(tempdir(), "dcf.txt")
write.dcf(x, file=dcfFile)
cat(sep="\n", readLines(dcfFile))
read.dcf(dcfFile)
unlink(dcfFile)