I find system.file() handy for writing examples,
but if the user mistypes its arguments or if a
package is not up to date its return value of ""
can lead to trouble. This forces the example to
be wordier than I'd like.
E.g., the following example works
> scan(what="", sep="\n",
system.file("DESCRIPTION"))
Read 9 items
[1] "Package: base"
[2] "Version: 2.12.0"
[3] "Priority: base"
[4] "Title: The R Base Package"
[5] "Author: R Development Core Team and contributors worldwide"
[6] "Maintainer: R Core Team <R-core at r-project.org>"
[7] "Description: Base R functions"
[8] "License: Part of R 2.12.0"
[9] "Built: R 2.12.0; ; 2010-10-18 15:08:12 UTC; unix"
but if you misspell DESCRIPTION you get
> scan(what="", sep="\n",
system.file("DESCRITION"))
1:
and the user has to know how to get out of that scan() prompt.
I can write the example as
theFile <- system.file("DESCRIPTION")
if (!identical(theFile, ""))
scan(what="", sep="\n", theFile)
else
stop("Cannot find file \"DESCRIPTION\" in package
\"base\"")
but that would be pretty ugly in a help file.
What do you think of adding an argument mustExist=FALSE or
mustFind=FALSE to system.file() such that if it is TRUE and
no file is found then system.file throws an error? Then my
example could be
scan(what="", sep="\n",
system.file("DESCRIPTION", mustExist=TRUE))
and it would throw an informative error message instead of
returning "" if DESCRIPTION were misspelled.
base::parseNamespaceFile uses an argument called mustExist
for this sort of thing and several functions in package:methods
(elNamed, getGeneric, etc.) use mustFind.
Bill Dunlap
Spotfire, TIBCO Software
wdunlap tibco.com
