R devel - Oct 2005 - RFC: API to allow identification of warnings and errors in the output stream

Dear R developers,

this mail is basically a summary / clarification of some previous mails I sent 
to this list last week (subject "Catching warning and error output").
Duncan
Murdoch pointed out that these were badly organized, and suggested I repost, 
collecting the main points previously spread out between several mails.

Problem statement:
In an application embedding R, I would like to identify warnings and errors in 
the output stream. That is, basically, I'm looking for a good way to find 
out, which portions of the output stream are warnings, which are error 
messages, and which are regular output. Such information could be used in a 
GUI to mark up different types of output in different colors, or to ensure 
warnings are brought to the user's attention in situations where output
would
normally be hidden.
I believe this is not currently possible in a good way. For a discussion of 
approaches using the current API, and their drawbacks, refer to 
https://stat.ethz.ch/pipermail/r-devel/2005-October/034975.html.

Suggested solution:
Here are two patches (against R-2.2.0), which I will describe in more detail 
below:
A) http://rkward.sourceforge.net/temp/classify_output_patch.diff
B) http://rkward.sourceforge.net/temp/classify_output_test.diff

Description of and rationale for patch A:
This patch does two things:
1) It adds a function R_WriteErrConsole corresponding to R_WriteConsole. Also, 
a corresponding interface pointer ptr_R_WriteErrConsole is added.
I think this change is highly consistent with output handling in R in general. 
There are different sink ()s for "output" and "message",
there is the
distinction between Rprintf/Rvprintf and REprintf/REvprintf. This basically 
just carries this distinction over to the interface pointers.
You will note that I wrote
ptr_R_WriteErrConsole = R_WriteConsole;
instead of
ptr_R_WriteErrConsole = Rstd_WriteErrConsole;
or
ptr_R_WriteErrConsole = ptr_R_WriteConsole;
This way, code that currently overrides ptr_R_WriteConsole, but does not know 
about ptr_R_WriteErrConsole, will still receive all output in 
ptr_R_WriteConsole. Hence this change is perfectly backwards compatible.
Of course, the naming may not be perfect?

2) While 1 makes it easy to split warning _and_ errors (and messages) from 
regular output, it does not suffice to differentiate _between_ warnings, 
errors, and messages on the error channel. The patch addresses this, by 
making inError, inWarning, and inPrintWarnings from errors.c accessible 
(read-only) in R_ext/Error.h.
This part of the patch may be slightly more delicate, in that inError, 
inWarning, and inPrintWarnings seem to be more internal status indications. 
So the question is: Are those potentially subject to change, if errors.c is 
redesigned some day? My feeling is that this is still relatively safe, 
however. Such indications can easily be set/unset at entry/exit points of the 
corresponding functions, as long as there are separate handlers for warnings, 
errors, and printWarnings. I guess this is not likely to ever change 
fundamentally.
As a slightly safer variation, R_inError (), R_inWarning (), and 
R_inPrintWarnings () could return a boolean indication only, instead of the 
int-code, which might be more subject to change.

Description of and rationale for patch B:
Patch B probably helps a lot to illustrate, how patch A works, and how this is 
useful. It adds an example to tests/embedding/. This example basically just 
generates a number of different types of messages, then catches the output, 
and classifies it into several categories.

I'll gladly provide more explanations or a different format of patches if 
needed.

Looking forward to your comments
Thomas Friedrichsmeier

I am strongly opposed to locking in anything from the C internals of
error handling that is not already part of the API.  This is all very
much subject to change and anything along the lines you propose will
make that change more difficult.

Condition handling was added to make this sort of thing possible.  If
there are aspects of condition handling, or your understanding of
condition handing, that need to be improved then we can work on that.

Best,

luke

On Mon, 17 Oct 2005, Thomas Friedrichsmeier wrote:
> Dear R developers,
>
> this mail is basically a summary / clarification of some previous mails I
sent
> to this list last week (subject "Catching warning and error
output"). Duncan
> Murdoch pointed out that these were badly organized, and suggested I
repost,
> collecting the main points previously spread out between several mails.
>
> Problem statement:
> In an application embedding R, I would like to identify warnings and errors
in
> the output stream. That is, basically, I'm looking for a good way to
find
> out, which portions of the output stream are warnings, which are error
> messages, and which are regular output. Such information could be used in a
> GUI to mark up different types of output in different colors, or to ensure
> warnings are brought to the user's attention in situations where output
would
> normally be hidden.
> I believe this is not currently possible in a good way. For a discussion of
> approaches using the current API, and their drawbacks, refer to
> https://stat.ethz.ch/pipermail/r-devel/2005-October/034975.html.
>
> Suggested solution:
> Here are two patches (against R-2.2.0), which I will describe in more
detail
> below:
> A) http://rkward.sourceforge.net/temp/classify_output_patch.diff
> B) http://rkward.sourceforge.net/temp/classify_output_test.diff
>
> Description of and rationale for patch A:
> This patch does two things:
> 1) It adds a function R_WriteErrConsole corresponding to R_WriteConsole.
Also,
> a corresponding interface pointer ptr_R_WriteErrConsole is added.
> I think this change is highly consistent with output handling in R in
general.
> There are different sink ()s for "output" and
"message", there is the
> distinction between Rprintf/Rvprintf and REprintf/REvprintf. This basically
> just carries this distinction over to the interface pointers.
> You will note that I wrote
> ptr_R_WriteErrConsole = R_WriteConsole;
> instead of
> ptr_R_WriteErrConsole = Rstd_WriteErrConsole;
> or
> ptr_R_WriteErrConsole = ptr_R_WriteConsole;
> This way, code that currently overrides ptr_R_WriteConsole, but does not
know
> about ptr_R_WriteErrConsole, will still receive all output in
> ptr_R_WriteConsole. Hence this change is perfectly backwards compatible.
> Of course, the naming may not be perfect?
>
> 2) While 1 makes it easy to split warning _and_ errors (and messages) from
> regular output, it does not suffice to differentiate _between_ warnings,
> errors, and messages on the error channel. The patch addresses this, by
> making inError, inWarning, and inPrintWarnings from errors.c accessible
> (read-only) in R_ext/Error.h.
> This part of the patch may be slightly more delicate, in that inError,
> inWarning, and inPrintWarnings seem to be more internal status indications.
> So the question is: Are those potentially subject to change, if errors.c is
> redesigned some day? My feeling is that this is still relatively safe,
> however. Such indications can easily be set/unset at entry/exit points of
the
> corresponding functions, as long as there are separate handlers for
warnings,
> errors, and printWarnings. I guess this is not likely to ever change
> fundamentally.
> As a slightly safer variation, R_inError (), R_inWarning (), and
> R_inPrintWarnings () could return a boolean indication only, instead of the
> int-code, which might be more subject to change.
>
> Description of and rationale for patch B:
> Patch B probably helps a lot to illustrate, how patch A works, and how this
is
> useful. It adds an example to tests/embedding/. This example basically just
> generates a number of different types of messages, then catches the output,
> and classifies it into several categories.
>
> I'll gladly provide more explanations or a different format of patches
if
> needed.
>
> Looking forward to your comments
> Thomas Friedrichsmeier
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
-- 
Luke Tierney
Chair, Statistics and Actuarial Science
Ralph E. Wareham Professor of Mathematical Sciences
University of Iowa                  Phone:             319-335-3386
Department of Statistics and        Fax:               319-335-3017
    Actuarial Science
241 Schaeffer Hall                  email:      luke at stat.uiowa.edu
Iowa City, IA 52242                 WWW:  http://www.stat.uiowa.edu