[Rd] extension to missing()? {was "hist() ... helpful warning? (PR#8376)"}

[Martin Maechler]

       [taken off R-bugs as a non-bug]

>>>>> "AndrewC" == clausen  <clausen at econ.upenn.edu>
>>>>>     on Sun, 11 Dec 2005 08:40:01 +0100 (CET) writes:

    AndrewC> Hi Brian,
    AndrewC> On Sun, Dec 11, 2005 at 04:34:50AM +0000, Prof Brian Ripley wrote:
    >> Did you check the help page?  ?plot.histogram shows plot.histogram has a 
    >> 'freq' argument, and the correct usage is
    >> 
    >> plot(hist(x), freq=FALSE)

    AndrewC> Ah, thanks for the explanation.

    AndrewC> I didn't occur to me to check the plot.histogram()
    AndrewC> help page.  

[ even though it's prominently mentioned on  help(hist)  ?? ]

    AndrewC> Besides, even if I had read it, I still don't think
    AndrewC> the semantics would have been clear to me without
    AndrewC> additional experimentation.

    AndrewC> Perhaps it might be helpful to document in the
    AndrewC> hist() help page which attributes are stored in the
    AndrewC> hist() object.  
you mean the 'histogram' object.

Yes, that might be helpful; diffs against
  https://svn.R-project.org/R/trunk/src/library/graphics/man/hist.Rd
are welcome.

    AndrewC> Alternatively/additionally, hist()
    AndrewC> could emit a warning or error if plot=FALSE and
    AndrewC> irrelevant (non-stored) attributes are set.

interesting proposal.
I've looked at it for a bit, and found that it seems not to be
doable both easily and elegantly, at least not along the first
line I've tried, and so I think it raises a slightly more
general somewhat interesting problem:

Since *most* arguments of hist.default, including '...' are only
made use of when plot = TRUE, and the code with the warning would
have to look at all of them, and we want to have a nicely
maintainable solution, I had wanted to have a solution which
looks at {almost} all formals() and which of them are missing().
Since formals() is a list,
    is.miss <- lapply(formals(), missing)
was the one I've tried but failed with
 Error in lapply(fm, missing) : 2 arguments passed to 'missing' which requires 1

which might be a bit astonishing {missing is Primitive though..}
and of course
    is.miss <- lapply(formals(), function(n) missing(n))
``works'' but trivially {why ?} and hence not usefully.

I've needed to make use of eval and substitute in order to make
use of missing() here.
Hence, I'm wondering if we maybe could generalize missing()
by something like   missing(all.formals = TRUE)  {or better syntax}
which would make the following a bit easier.

Here's a context diff of my working version of hist.default()
which implements the above proposal:

--- hist.R	(Revision 36695)
+++ hist.R	(working copy)
@@ -108,7 +108,19 @@
 	     axes = axes, labels = labels, ...)
 	invisible(r)
     }
-    else r
+    else { ## plot is FALSE
+        nf <- names(formals()) ## all formals but those 4:
+        nf <- nf[match(nf, c("x", "breaks", "nclass", "plot"), nomatch=0) == 0]
+        missE <- lapply(nf, function(n)
+                        substitute(missing(.), list(. = as.name(n))))
+        not.miss <- ! sapply(missE, eval, envir = environment())
+        if(any(not.miss))
+            warning(sprintf(ngettext(sum(not.miss),
+                                     "argument %s is not made use of",
+                                     "arguments %s are not made use of"),
+                            paste(sQuote(nf[not.miss]), collapse=", ")))
+        r
+    }
 }
 
 plot.histogram <-