diff options
Diffstat (limited to 'doc/bison.texi')
| -rw-r--r-- | doc/bison.texi | 279 |
1 files changed, 148 insertions, 131 deletions
diff --git a/doc/bison.texi b/doc/bison.texi index b3f85e16..0478d792 100644 --- a/doc/bison.texi +++ b/doc/bison.texi @@ -380,6 +380,7 @@ Invoking Bison Bison Options * Operation Modes:: Options controling the global behavior of @command{bison} +* Diagnostics:: Options controlling the diagnostics * Tuning the Parser:: Options changing the generated parsers * Output Files:: Options controling the output @@ -10292,12 +10293,12 @@ are unique. When a long option takes an argument, like @samp{--file-prefix}, connect the option name and the argument with @samp{=}. -Here is a list of options that can be used with Bison, alphabetized by -short option. It is followed by a cross key alphabetized by long -option. +Here is a list of options that can be used with Bison. It is followed by a +cross key alphabetized by long option. @menu * Operation Modes:: Options controling the global behavior of @command{bison} +* Diagnostics:: Options controlling the diagnostics * Tuning the Parser:: Options changing the generated parsers * Output Files:: Options controling the output @end menu @@ -10305,6 +10306,8 @@ option. @node Operation Modes @subsection Operation Modes +Options controling the global behavior of @command{bison}. + @c Please, keep this ordered as in 'bison --help'. @table @option @item -h @@ -10358,6 +10361,140 @@ exp:; See the documentation of @option{--feature=fixit} below for more details. +@item -f [@var{feature}] +@itemx --feature[=@var{feature}] +Activate miscellaneous @var{feature}s. @var{Feature} can be one of: +@table @code +@item caret +@itemx diagnostics-show-caret +Show caret errors, in a manner similar to GCC's +@option{-fdiagnostics-show-caret}, or Clang's +@option{-fcaret-diagnostics}. 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 (@samp{^}). Here is an example, using the +following file @file{in.y}: + +@example +%type <ival> exp +%% +exp: exp '+' exp @{ $exp = $1 + $2; @}; +@end example + +When invoked with @option{-fcaret} (or nothing), Bison will report: + +@example +@group +in.y:3.20-23: @derror{error}: ambiguous reference: '$exp' + 3 | exp: exp '+' exp @{ @derror{$exp} = $1 + $2; @}; + | @derror{^~~~} +@end group +@group +in.y:3.1-3: refers to: $exp at $$ + 3 | @dnotice{exp}: exp '+' exp @{ $exp = $1 + $2; @}; + | @dnotice{^~~} +@end group +@group +in.y:3.6-8: refers to: $exp at $1 + 3 | exp: @dnotice{exp} '+' exp @{ $exp = $1 + $2; @}; + | @dnotice{^~~} +@end group +@group +in.y:3.14-16: refers to: $exp at $3 + 3 | exp: exp '+' @dnotice{exp} @{ $exp = $1 + $2; @}; + | @dnotice{^~~} +@end group +@group +in.y:3.32-33: @derror{error}: $2 of 'exp' has no declared type + 3 | exp: exp '+' exp @{ $exp = $1 + @derror{$2}; @}; + | @derror{^~} +@end group +@end example + +Whereas, when invoked with @option{-fno-caret}, Bison will only report: + +@example +@group +in.y:3.20-23: @derror{error}: ambiguous reference: '$exp' +in.y:3.1-3: refers to: $exp at $$ +in.y:3.6-8: refers to: $exp at $1 +in.y:3.14-16: refers to: $exp at $3 +in.y:3.32-33: @derror{error}: $2 of 'exp' has no declared type +@end group +@end example + +This option is activated by default. + +@item fixit +@itemx diagnostics-parseable-fixits +Show machine-readable fixes, in a manner similar to GCC's and Clang's +@option{-fdiagnostics-parseable-fixits}. + +Fix-its are generated for duplicate directives: + +@example +@group +$ @kbd{cat foo.y} +%define api.prefix @{foo@} +%define api.prefix @{bar@} +%% +exp:; +@end group + +@group +$ @kbd{bison -ffixit foo.y} +foo.y:2.1-24: @derror{error}: %define variable 'api.prefix' redefined + 2 | @derror{%define api.prefix @{bar@}} + | @derror{^~~~~~~~~~~~~~~~~~~~~~~~} +foo.y:1.1-24: previous definition + 1 | @dnotice{%define api.prefix @{foo@}} + | @dnotice{^~~~~~~~~~~~~~~~~~~~~~~~} +fix-it:"foo.y":@{2:1-2:25@}:"" +foo.y: @dwarning{warning}: fix-its can be applied. Rerun with option '--update'. [@dwarning{-Wother}] +@end group +@end example + +They are also generated to update deprecated directives, unless +@option{-Wno-deprecated} was given: + +@example +@group +$ @kbd{cat /tmp/foo.yy} +%error-verbose +%name-prefix "foo" +%% +exp:; +@end group +@group +$ @kbd{bison foo.y} +foo.y:1.1-14: @dwarning{warning}: deprecated directive, use '%define parse.error verbose' [@dwarning{-Wdeprecated}] + 1 | @dwarning{%error-verbose} + | @dwarning{^~~~~~~~~~~~~~} +foo.y:2.1-18: @dwarning{warning}: deprecated directive, use '%define api.prefix @{foo@}' [@dwarning{-Wdeprecated}] + 2 | @dwarning{%name-prefix "foo"} + | @dwarning{^~~~~~~~~~~~~~~~~~} +foo.y: @dwarning{warning}: fix-its can be applied. Rerun with option '--update'. [@dwarning{-Wother}] +@end group +@end example + +The fix-its are applied by @command{bison} itself when given the option +@option{-u}/@option{--update}. See its documentation above. + +@item syntax-only +Do not generate the output files. The name of this feature is somewhat +misleading as more than just checking the syntax is done: every stage is run +(including checking for conflicts for instance), except the generation of +the output files. + +@end table +@end table + +@node Diagnostics +@subsection Diagnostics + +Options controlling the diagnostics. + +@c Please, keep this ordered as in 'bison --help'. +@table @code @item -W [@var{category}] @itemx --warnings[=@var{category}] Output warnings falling in @var{category}. @var{category} can be one @@ -10512,7 +10649,10 @@ they are explicitly enabled by @option{-Werror=@var{category}}. Deactivate the error treatment for this @var{category}. However, the warning itself won't be disabled, or enabled, by this option. -@item --color[=@var{when}] +@item --color +Equivalent to @option{--color=always}. + +@item --color=@var{when} Control whether diagnostics are colorized, depending on @var{when}: @table @code @item always @@ -10528,7 +10668,6 @@ Disable colorized diagnostics. Diagnostics will be colorized if the output device is a tty, i.e. when the output goes directly to a text screen or terminal emulator window. @end table -@option{--color} is equivalent to @option{--color=always}. @item --style=@var{file} Specifies the CSS style @var{file} to use when colorizing. It has an effect @@ -10536,137 +10675,13 @@ only when the @option{--color} option is effective. The @file{bison-default.css} file provide a good example from which to define your own style file. See the documentation of libtextstyle for more details. - -@item -f [@var{feature}] -@itemx --feature[=@var{feature}] -Activate miscellaneous @var{feature}s. @var{Feature} can be one of: -@table @code -@item caret -@itemx diagnostics-show-caret -Show caret errors, in a manner similar to GCC's -@option{-fdiagnostics-show-caret}, or Clang's -@option{-fcaret-diagnostics}. 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 (@samp{^}). Here is an example, using the -following file @file{in.y}: - -@example -%type <ival> exp -%% -exp: exp '+' exp @{ $exp = $1 + $2; @}; -@end example - -When invoked with @option{-fcaret} (or nothing), Bison will report: - -@example -@group -in.y:3.20-23: @derror{error}: ambiguous reference: '$exp' - 3 | exp: exp '+' exp @{ @derror{$exp} = $1 + $2; @}; - | @derror{^~~~} -@end group -@group -in.y:3.1-3: refers to: $exp at $$ - 3 | @dnotice{exp}: exp '+' exp @{ $exp = $1 + $2; @}; - | @dnotice{^~~} -@end group -@group -in.y:3.6-8: refers to: $exp at $1 - 3 | exp: @dnotice{exp} '+' exp @{ $exp = $1 + $2; @}; - | @dnotice{^~~} -@end group -@group -in.y:3.14-16: refers to: $exp at $3 - 3 | exp: exp '+' @dnotice{exp} @{ $exp = $1 + $2; @}; - | @dnotice{^~~} -@end group -@group -in.y:3.32-33: @derror{error}: $2 of 'exp' has no declared type - 3 | exp: exp '+' exp @{ $exp = $1 + @derror{$2}; @}; - | @derror{^~} -@end group -@end example - -Whereas, when invoked with @option{-fno-caret}, Bison will only report: - -@example -@group -in.y:3.20-23: @derror{error}: ambiguous reference: ‘$exp’ -in.y:3.1-3: refers to: $exp at $$ -in.y:3.6-8: refers to: $exp at $1 -in.y:3.14-16: refers to: $exp at $3 -in.y:3.32-33: @derror{error}: $2 of ‘exp’ has no declared type -@end group -@end example - -This option is activated by default. - -@item fixit -@itemx diagnostics-parseable-fixits -Show machine-readable fixes, in a manner similar to GCC's and Clang's -@option{-fdiagnostics-parseable-fixits}. - -Fix-its are generated for duplicate directives: - -@example -@group -$ @kbd{cat foo.y} -%define api.prefix @{foo@} -%define api.prefix @{bar@} -%% -exp:; -@end group - -@group -$ @kbd{bison -ffixit foo.y} -foo.y:2.1-24: @derror{error}: %define variable 'api.prefix' redefined - 2 | @derror{%define api.prefix @{bar@}} - | @derror{^~~~~~~~~~~~~~~~~~~~~~~~} -foo.y:1.1-24: previous definition - 1 | @dnotice{%define api.prefix @{foo@}} - | @dnotice{^~~~~~~~~~~~~~~~~~~~~~~~} -fix-it:"foo.y":@{2:1-2:25@}:"" -foo.y: @dwarning{warning}: fix-its can be applied. Rerun with option '--update'. [@dwarning{-Wother}] -@end group -@end example - -They are also generated to update deprecated directives, unless -@option{-Wno-deprecated} was given: - -@example -@group -$ @kbd{cat /tmp/foo.yy} -%error-verbose -%name-prefix "foo" -%% -exp:; -@end group -@group -$ @kbd{bison foo.y} -foo.y:1.1-14: @dwarning{warning}: deprecated directive, use '%define parse.error verbose' [@dwarning{-Wdeprecated}] - 1 | @dwarning{%error-verbose} - | @dwarning{^~~~~~~~~~~~~~} -foo.y:2.1-18: @dwarning{warning}: deprecated directive, use '%define api.prefix @{foo@}' [@dwarning{-Wdeprecated}] - 2 | @dwarning{%name-prefix "foo"} - | @dwarning{^~~~~~~~~~~~~~~~~~} -foo.y: @dwarning{warning}: fix-its can be applied. Rerun with option '--update'. [@dwarning{-Wother}] -@end group -@end example - -The fix-its are applied by @command{bison} itself when given the option -@option{-u}/@option{--update}. See its documentation above. - -@item syntax-only -Do not generate the output files. The name of this feature is somewhat -misleading as more than just checking the syntax is done: every stage is run -(including checking for conflicts for instance), except the generation of -the output files. - -@end table @end table @node Tuning the Parser @subsection Tuning the Parser +Options changing the generated parsers. + @c Please, keep this ordered as in 'bison --help'. @table @option @item -t @@ -10776,6 +10791,8 @@ is specified. @node Output Files @subsection Output Files +Options controling the output. + @c Please, keep this ordered as in 'bison --help'. @table @option @item --defines[=@var{file}] |