[Rd] wishlist: system.file(..., mustExist = TRUE)

[William Dunlap]

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