error messages with ranges

[Manuel López-Ibáñez]

Hi,

This is a patch to standards.texi to specify error messages with
multiple ranges. Currently, Clang implements this [1] and GCC would
like to implement it too [2].

[1] http://clang.llvm.org/docs/UsersManual.html#cl_diagnostics (option
-f[no-]diagnostics-print-source-range-info)

[2] http://gcc.gnu.org/ml/gcc-patches/2009-08/msg00201.html


2009-10-10  Manuel López-Ibáñez <manu@...>

  * standard.texi (Error Messages): Describe error ranges.

Cheers,

  Manuel.

[ranges.patch]

---

diff -Naurp standards-orig/standards.texi standards/standards.texi
--- standards-orig/standards.texi 2009-04-17 00:46:07.000000000 +0200
+++ standards/standards.texi 2009-10-10 13:35:31.000000000 +0200
@@ -3,7 +3,7 @@
 @setfilename standards.info
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:
-@set lastupdate April 16, 2009
+@set lastupdate October 10, 2009
 @c %**end of header
 
 @dircategory GNU organization
@@ -760,6 +760,16 @@ When an error is spread over several fil
 @var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
 @end example
 
+@noindent
+When an error message mentions several ranges of positions within one
+file, you can specify each range within braces. For example, the
+following specifies one error position and two ranges within the same
+file:
+
+@example
+@var{file-1}:@var{lineno-1}:@var{column-1}:@{@var{lineno-2}:@var{column-2}-@var{lineno-3}:@var{column-3}@}@{@var{lineno-4}:@var{column-4}-@var{lineno-5}:@var{column-5}@}: @var{message}
+@end example
+
 Error messages from other noninteractive programs should look like this:
 
 @example

---

[Manuel López-Ibáñez]

Hi,

This is a patch to standards.texi to specify error messages with
multiple ranges. Currently, Clang implements this [1] and GCC would
like to implement it too [2].

Cheers,

 Manuel.


[1] http://clang.llvm.org/docs/UsersManual.html#cl_diagnostics (option
-f[no-]diagnostics-print-source-range-info)

[2] http://gcc.gnu.org/ml/gcc-patches/2009-08/msg00201.html


2009-10-10  Manuel López-Ibáñez <manu@...>

 * standard.texi (Error Messages): Describe error ranges.

[ranges.patch]

---

diff -Naurp standards-orig/standards.texi standards/standards.texi
--- standards-orig/standards.texi 2009-04-17 00:46:07.000000000 +0200
+++ standards/standards.texi 2009-10-10 13:35:31.000000000 +0200
@@ -3,7 +3,7 @@
 @setfilename standards.info
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:
-@set lastupdate April 16, 2009
+@set lastupdate October 10, 2009
 @c %**end of header
 
 @dircategory GNU organization
@@ -760,6 +760,16 @@ When an error is spread over several fil
 @var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
 @end example
 
+@noindent
+When an error message mentions several ranges of positions within one
+file, you can specify each range within braces. For example, the
+following specifies one error position and two ranges within the same
+file:
+
+@example
+@var{file-1}:@var{lineno-1}:@var{column-1}:@{@var{lineno-2}:@var{column-2}-@var{lineno-3}:@var{column-3}@}@{@var{lineno-4}:@var{column-4}-@var{lineno-5}:@var{column-5}@}: @var{message}
+@end example
+
 Error messages from other noninteractive programs should look like this:
 
 @example

---

[Karl Berry]

    This is a patch to standards.texi to specify error messages with
    multiple ranges.

Thanks, fine by me.  I have forwarded it to rms for approval.

[Karl Berry]

Hi Manuel,

    This is a patch to standards.texi to specify error messages with
    multiple ranges.

Here is rms's response:

  Date: Sun, 11 Oct 2009 23:44:45 -0400
  From: Richard Stallman <rms@...>
  To: karl@... (Karl Berry)
  Subject: Re: [lopezibanez@...: error messages with ranges]

  I think this is not a good idea.
  Putting multiple locations in one error message is not helpful
  and makes it harder to read.

  There are situations where GCC needs to mention two different
  places in the source -- for instance, two conflicting declarations
  for one symbol.  It does this by issuing two error messages, one
  with each location.  The text states how they are related.

  In practice this is perfectly clear and convenient.  Putting them in a
  single error message would make it harder to read.

  Please ask the Clang and GCC developers to state the practical
  advantages they see in this new format.

You might as well send your replies directly to him.  I don't need to be
in this loop (and I'll be offline the rest of this week).

[Manuel López-Ibáñez]

>  Date: Sun, 11 Oct 2009 23:44:45 -0400
>  From: Richard Stallman <rms@...>
>  To: karl@... (Karl Berry)
>  Subject: Re: [lopezibanez@...: error messages with ranges]
>
>  I think this is not a good idea.
>  Putting multiple locations in one error message is not helpful
>  and makes it harder to read.
>  There are situations where GCC needs to mention two different
>  places in the source -- for instance, two conflicting declarations
>  for one symbol.  It does this by issuing two error messages, one
>  with each location.  The text states how they are related.

This is a different situation that is orthogonal to mentioning two
different places.

First, this option will be default to off. Second, this information
will be primarily parsed by programs not humans.

The goal here is to work towards supporting caret information in GCC
(as Clang and other compilers currently support and use as a major
selling point).

An example from Clang's webpage [1]:

 $ gcc-4.2 -fsyntax-only t.c
 t.c:7: error: invalid operands to binary + (have 'int' and 'struct A')
 $ clang -fsyntax-only t.c
 t.c:7:39: error: invalid operands to binary expression ('int' and 'struct A')
   return y + func(y ? ((SomeA.X + 40) + SomeA) / 42 + SomeA.X : SomeA.X);
                         ~~~~~~~~~~~~~~ ^ ~~~~~

The caret '^' and the ranges shown by ~~~~~  are generated the
compiler (clang in this case). A fist step towards implementing this
is to have an option that prints range information in the location
line. This allows programs to parse gcc output and generate a wrapper
around gcc that provides caret diagnostics. This is already done by at
least one IDE to provide caret diagnostics using Clang. This also
allows developers to debug the range information in case the ranges
are not printed where they are expected.

In short, the goal is to implement in GCC, this option from Clang:

-f[no-]diagnostics-print-source-range-info: Print machine parsable
information about source ranges.
    This option, which defaults to off, controls whether or not Clang
prints information about source ranges in a machine parsable format
after the file/line/column number information. The information is a
simple sequence of brace enclosed ranges, where each range lists the
start and end line/column locations. For example, in this output:

    exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands
to binary expression ('int *' and '_Complex float')
       P = (P-42) + Gamma*4;
           ~~~~~~ ^ ~~~~~~~

    The {}'s are generated by -fdiagnostics-print-source-range-info.


I can certainly update the patch to mention that this format should be
avoided for output that is meant to be read mainly by humans, and in
such case a single location or multiple errors are preferred.

Cheers,

Manuel.


[1] http://clang.llvm.org/diagnostics.html
[2] http://clang.llvm.org/docs/UsersManual.html#cl_diagnostics

[Richard Stallman]

    The goal here is to work towards supporting caret information in GCC

What is "caret information"?

        exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands
    to binary expression ('int *' and '_Complex float')
           P = (P-42) + Gamma*4;
               ~~~~~~ ^ ~~~~~~~

Is that what "caret information" means?

I can see how this

           P = (P-42) + Gamma*4;
               ~~~~~~ ^ ~~~~~~~

is useful for humans, and making GCC output that information
seems like a good feature.  But why is it useful to include
the location range information for the operands?

How exactly do people propose to use that location range information?

[Manuel López-Ibáñez]

2009/10/14 Richard Stallman <rms@...>:
>    The goal here is to work towards supporting caret information in GCC
>
> What is "caret information"?

I would say that it is the ability to print, in diagnostic messages,
parts of the original source code indicating exactly which parts of
the source code the diagnostic is referring to.

>
>        exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands
>    to binary expression ('int *' and '_Complex float')
>           P = (P-42) + Gamma*4;
>               ~~~~~~ ^ ~~~~~~~
>
> Is that what "caret information" means?

The line of code with the '~~' and '^' below is the caret information.
The {47:8-47:14}{47:17-47:24} would be the "location range" information.

>
> I can see how this
>
>           P = (P-42) + Gamma*4;
>               ~~~~~~ ^ ~~~~~~~
>
> is useful for humans, and making GCC output that information
> seems like a good feature.  But why is it useful to include
> the location range information for the operands?

In principle the location range information would be only internal for
GCC. The option that enables it to be shown in the output would allow
external programs (like emacs, IDEs, a custom wrapper, or GCC's
regression tester) to parse the output of GCC. In fact, what such
programs would do is to turn OFF the caret information and turn ON the
location range information, in order to provide their own custom caret
information.

I really do not know if this format actually needs documenting in
Coding Standards, since it is not really meant for humans. I can also
update the patch to mention that this format is to be parsed by
machines, and it should not be used for output meant to be read by
humans (unless requested).

> How exactly do people propose to use that location range information?

As far as I know, at least one IDE is using it to parse the output of
Clang and provide custom caret information in the IDE interface.

Cheers,

Manuel.

[Richard Stallman]

    In principle the location range information would be only internal for
    GCC. The option that enables it to be shown in the output would allow
    external programs (like emacs, IDEs, a custom wrapper, or GCC's
    regression tester) to parse the output of GCC. In fact, what such
    programs would do is to turn OFF the caret information and turn ON the
    location range information, in order to provide their own custom caret
    information.

Given that plan, why not output the arg location information
in separate lines distinguished by some special prefix?

Standardizing its format could be useful at some point,
but it need not be part of the error message standard.

    > How exactly do people propose to use that location range information?

    As far as I know, at least one IDE is using it to parse the output of
    Clang and provide custom caret information in the IDE interface.

Are you saying that clang already outputs the argument range information
in this format?

[Manuel López-Ibáñez]

2009/10/15 Richard Stallman <rms@...>:

>    In principle the location range information would be only internal for
>    GCC. The option that enables it to be shown in the output would allow
>    external programs (like emacs, IDEs, a custom wrapper, or GCC's
>    regression tester) to parse the output of GCC. In fact, what such
>    programs would do is to turn OFF the caret information and turn ON the
>    location range information, in order to provide their own custom caret
>    information.
>
> Given that plan, why not output the arg location information
> in separate lines distinguished by some special prefix?

Could you provide an example of what you have in mind? For example, to
represent this:

exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands
  to binary expression ('int *' and '_Complex float')

Please bear in mind that the format should be easily parsable by
machines, in order to be able to associate the ranges with the
appropriate error message, and not parse it as multiple independent
messages.

>    > How exactly do people propose to use that location range information?
>
>    As far as I know, at least one IDE is using it to parse the output of
>    Clang and provide custom caret information in the IDE interface.
>
> Are you saying that clang already outputs the argument range information
> in this format?

Yes, it does if this is enabled usng the appropriate option.

Cheers,

Manuel.

[Richard Stallman]

How about something like this:

    exprs.c:47:15: error: invalid operands to binary expression ('int *' and '_Complex float')
    ::Argument locations: 47:8-47:14, 47:17-47:24

If the brace notation you've proposed becomes a de facto standard,
we may as well go along with it.  But I think this proposal
is better intrinsically, since it is less clutter and no harder to parse.

[Gabriel Dos Reis-6]

On Fri, Oct 16, 2009 at 3:47 AM, Richard Stallman <rms@...> wrote:
> How about something like this:
>
>    exprs.c:47:15: error: invalid operands to binary expression ('int *' and '_Complex float')
>    ::Argument locations: 47:8-47:14, 47:17-47:24
>
> If the brace notation you've proposed becomes a de facto standard,
> we may as well go along with it.  But I think this proposal
> is better intrinsically, since it is less clutter and no harder to parse.

I like the non-braced version.

However, I would like you clarify the '::Argument locations:' marker.
Do you intend the double colons '::' as token to introduce
some form of meta data for tools? (In this case, it is to introduce
locus, but is it an escape for more general tags?)



>
>

[Chris Lattner-2]

On Oct 16, 2009, at 9:51 AM, Gabriel Dos Reis wrote:

> On Fri, Oct 16, 2009 at 3:47 AM, Richard Stallman <rms@...> wrote:
>> How about something like this:
>>
>>    exprs.c:47:15: error: invalid operands to binary expression  
>> ('int *' and '_Complex float')
>>    ::Argument locations: 47:8-47:14, 47:17-47:24
>>
>> If the brace notation you've proposed becomes a de facto standard,
>> we may as well go along with it.  But I think this proposal
>> is better intrinsically, since it is less clutter and no harder to  
>> parse.
>
> I like the non-braced version.
>
> However, I would like you clarify the '::Argument locations:' marker.
> Do you intend the double colons '::' as token to introduce
> some form of meta data for tools? (In this case, it is to introduce
> locus, but is it an escape for more general tags?)

FWIW, clang uses ranges for a lot of things other than arguments.

Here are some other examples:

$ clang -fsyntax-only t.c
   t.c:12:8: error: called object type 'int' is not a function or  
function pointer
   (P-Q)();
   ~~~~~^
$ clang t.c
t.c:5:28: warning: use of GNU old-style field designator extension
struct point origin = { x: 0.0, y: 0.0 };
                         ~~ ^
                         .x =

This is probably mangled by my email client, but you can see examples  
as intended here:
http://clang.llvm.org/diagnostics.html

The brace sequence is not normally seen by humans, only by IDEs and  
tools.  It being terse and simple is important, but beauty is not very  
important.

-Chris

[Joseph S. Myers]

On Fri, 16 Oct 2009, Chris Lattner wrote:

> On Oct 16, 2009, at 9:51 AM, Gabriel Dos Reis wrote:
>
> > On Fri, Oct 16, 2009 at 3:47 AM, Richard Stallman <rms@...> wrote:
> > > How about something like this:
> > >
> > >   exprs.c:47:15: error: invalid operands to binary expression ('int *' and
> > > '_Complex float')
> > >   ::Argument locations: 47:8-47:14, 47:17-47:24
> > >
> > > If the brace notation you've proposed becomes a de facto standard,
> > > we may as well go along with it.  But I think this proposal
> > > is better intrinsically, since it is less clutter and no harder to parse.
> >
> > I like the non-braced version.
> >
> > However, I would like you clarify the '::Argument locations:' marker.
> > Do you intend the double colons '::' as token to introduce
> > some form of meta data for tools? (In this case, it is to introduce
> > locus, but is it an escape for more general tags?)
>
> FWIW, clang uses ranges for a lot of things other than arguments.

I was presuming that in the above the initial "::" is the signal to IDEs
or other diagnostic parsers, meaning that "Argument locations" is to be
taken as English text that should be translated to the user's language,
and so IDEs should not ascribe any significance to the specific phrase
"Argument locations" because they need to handle translations to other
languages as well.  With the specific phrase not being significant, it is
of course possible to put other phrases there if it's felt useful to
attach a natural language name to the other locations in that way.

--
Joseph S. Myers
joseph@...

[Gabriel Dos Reis]

On Fri, Oct 16, 2009 at 4:24 PM, Joseph S. Myers
<joseph@...> wrote:

> I was presuming that in the above the initial "::" is the signal to IDEs
> or other diagnostic parsers, meaning that "Argument locations" is to be
> taken as English text that should be translated to the user's language,
> and so IDEs should not ascribe any significance to the specific phrase
> "Argument locations" because they need to handle translations to other
> languages as well.  With the specific phrase not being significant, it is
> of course possible to put other phrases there if it's felt useful to
> attach a natural language name to the other locations in that way.

Thanks, this is what I was looking for.

In that case, I think I agree with the suggestion made by RMS.

-- Gaby

[Richard Stallman]

    However, I would like you clarify the '::Argument locations:' marker.
    Do you intend the double colons '::' as token to introduce
    some form of meta data for tools? (In this case, it is to introduce
    locus, but is it an escape for more general tags?)

Yes, exactly.

I don't insist on using ::.  It was the first thing that occurred to me.
If someone has a better idea, let's use it.

[Manuel López-Ibáñez]

2009/10/16 Richard Stallman <rms@...>:
> How about something like this:
>
>    exprs.c:47:15: error: invalid operands to binary expression ('int *' and '_Complex float')
>    ::Argument locations: 47:8-47:14, 47:17-47:24
>
> If the brace notation you've proposed becomes a de facto standard,
> we may as well go along with it.  But I think this proposal
> is better intrinsically, since it is less clutter and no harder to parse.

Is :: starting a new line? If so, I think emacs does not parse more
than one line of GCC's output at a time. Would that change with this
proposal?

Do numbers may appear in the message between :: and : ?

Cheers,

Manuel.

[Richard Stallman]

    "Argument locations" because they need to handle translations to other
    languages as well.  With the specific phrase not being significant, it is
    of course possible to put other phrases there if it's felt useful to
    attach a natural language name to the other locations in that way.

Yes.  However, we could also publish a list of the phrases that GCC
puts there, with a description of what the ranges mean.  Then an IDE
could optionally recognize some of these phrases and do something
special for them.

[Richard Stallman]

    FWIW, clang uses ranges for a lot of things other than arguments.

We already support ranges in error messages.  The issue here is to
include more than one range.  These two examples need only one:

    $ clang -fsyntax-only t.c
       t.c:12:8: error: called object type 'int' is not a function or function pointer
       (P-Q)();
       ~~~~~^
    $ clang t.c
    t.c:5:28: warning: use of GNU old-style field designator extension
    struct point origin = { x: 0.0, y: 0.0 };
                             ~~ ^
                             .x =

However, my proposal is not limited to indicating the arguments.
It could be used to convey multiple ranges for any purpose.

[Richard Stallman]

    Is :: starting a new line? If so, I think emacs does not parse more
    than one line of GCC's output at a time. Would that change with this
    proposal?

Parsing either of these formats will require specialized code for sure.

At the risk of complicating the decision, another idea just occurred to me:
output a separate error message for each argument, like this:

    foo.c:47:5-10: First argument of erroneous operation
    foo.c:47:14-250: Second argument of erroneous operation

The IDE could recognize these two error messages
and process them specially however it wishes.