Re: [PATCH 4/4] doc: document carets

[Théophile Ranquet]

2012/12/4 Akim Demaille <address@hidden>:
>> +    err.y:4.5-8: error: invalid reference: '$foo'
>> +     C: {$foo{bar} };
>> +         ^^^^
>
> Poor example.

Changed to this:

input.y:3.20-23: error: ambiguous reference: '$exp'
 exp: exp '+' exp { $exp = $1 + $2; };
                    ^^^^

and installed as follows:


commit 7bada5355e10f560269825cbd658caaa473573f7
Author: Theophile Ranquet <address@hidden>
Date:   Tue Dec 4 13:12:12 2012 +0100

    doc: document carets

    * NEWS: Announce it.
    * doc/bison.texi (Bison Options):  Here.

diff --git a/NEWS b/NEWS
index 93a1ef5..0c3d025 100644
--- a/NEWS
+++ b/NEWS
@@ -7,6 +7,19 @@ GNU Bison NEWS
   The introduction of this feature, in 2.4, was four years ago. The --language
   option and the %language directive are no longer experimental.

+** New format for error reports: carets
+
+  Caret errors have been added to Bison, for example (taken from the
+  documentation):
+
+    input.y:3.20-23: error: ambiguous reference: '$exp'
+     exp: exp '+' exp { $exp = $1 + $2; };
+                        ^^^^
+
+  The default behaviour for now is still not to display these unless explictly
+  asked with -fall of -fcaret. However, in a later release, it will be made the
+  default behavior (but may still be deactivated with -fno-caret).
+
 ** New value for %define variable: api.pure full

   The %define variable api.pure requests a pure (reentrant) parser. However,
diff --git a/doc/bison.texi b/doc/bison.texi
index 5952225..06af088 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -9239,6 +9239,56 @@ Treat warnings as errors.
 A category can be turned off by prefixing its name with @samp{no-}.  For
 instance, @option{-Wno-yacc} will hide the warnings about
 POSIX Yacc incompatibilities.
+
address@hidden -f address@hidden
address@hidden address@hidden
+Activate miscellaneous @var{feature}. @var{feature} can be one of:
address@hidden @code
address@hidden caret
address@hidden diagnostics-show-caret
+Show caret errors, in a manner similar to GCC's
address@hidden, or Clang's @option{-fcaret-diagnotics}. The
+location provided with the message is used to quote the corresponding line of
+the source file, underlining the important part of it with carets (^). Here is
+an example, using the following file @file{input.y}:
+
address@hidden
+%type <ival> exp
+%%
+exp: exp '+' exp @{ $exp = $1 + $2; @};
address@hidden example
+
+When invoked with @option{-fcaret}, Bison will report:
+
address@hidden
address@hidden
+input.y:3.20-23: error: ambiguous reference: '$exp'
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+                    ^^^^
address@hidden group
address@hidden
+input.y:3.1-3:       refers to: $exp at $$
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+ ^^^
address@hidden group
address@hidden
+input.y:3.6-8:       refers to: $exp at $1
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+      ^^^
address@hidden group
address@hidden
+input.y:3.14-16:     refers to: $exp at $3
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+              ^^^
address@hidden group
address@hidden
+input.y:3.32-33: error: $2 of 'exp' has no declared type
+ exp: exp '+' exp @{ $exp = $1 + $2; @};
+                                ^^
address@hidden group
address@hidden example
+
address@hidden table
 @end table

 @noindent