diff options
author | Akim Demaille <akim.demaille@gmail.com> | 2020-06-09 07:08:11 +0200 |
---|---|---|
committer | Akim Demaille <akim.demaille@gmail.com> | 2020-06-09 08:09:26 +0200 |
commit | a53c6026cd367c75d5594e6e649ee1cdda93d5ae (patch) | |
tree | a463d7fe1d1fc1b8027536511dc51e4bbc4a735d /doc | |
parent | ae5edcc23b785b5ff0652aec79f8ee39f13be687 (diff) | |
download | bison-a53c6026cd367c75d5594e6e649ee1cdda93d5ae.tar.gz |
api.header.include: document it, and fix its default value
While defining api.header.include worked as expected, its default
value was incorrectly defined. As a result, by default, the generated
parsers still duplicated the content of the generated header instead
of including it.
* data/skeletons/yacc.c (api.header.include): Fix its default value.
* tests/output.at: Check it.
* doc/bison.texi (%define Summary): Document api.header.include.
While at it, move the definition of api.namespace at the proper
place.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/bison.texi | 96 |
1 files changed, 75 insertions, 21 deletions
diff --git a/doc/bison.texi b/doc/bison.texi index 5a08fa92..c60897bc 100644 --- a/doc/bison.texi +++ b/doc/bison.texi @@ -5922,44 +5922,58 @@ Unaccepted @var{variable}s produce an error. Some of the accepted @var{variable}s are described below. -@c ================================================== api.namespace -@deffn Directive {%define api.namespace} @{@var{namespace}@} +@c ================================================== api.header.include +@deffn Directive {%define api.header.include} @{"header.h"@} +@deffnx Directive {%define api.header.include} @{<header.h>@} @itemize -@item Languages(s): C++ +@item Languages(s): C (@file{yacc.c}) -@item Purpose: Specify the namespace for the parser class. -For example, if you specify: +@item Purpose: Specify how the generated parser should include the generated header. -@example -%define api.namespace @{foo::bar@} -@end example +Historically, when option @option{-D}/@option{--defines} was used, +@command{bison} generated a header and pasted an exact copy of it into the +generated parser implementation file. Since Bison 3.6, it is +@code{#include}d as @samp{"@var{basename}.h"}, instead of duplicated, unless +@var{file} is @samp{y.tab}, see below. -Bison uses @code{foo::bar} verbatim in references such as: +The @code{api.header.include} variable allows to control how the generated +parser @code{#include}s the generated header. For instance: @example -foo::bar::parser::semantic_type +%define api.header.include @{"parse.h"@} @end example -However, to open a namespace, Bison removes any leading @code{::} and then -splits on any remaining occurrences: +@noindent +or @example -namespace foo @{ namespace bar @{ - class position; - class location; -@} @} +%define api.header.include @{<parser/parse.h>@} @end example +Using @code{api.header.include} does not change the name of the generated +header, only how it is included. + +To work around limitations of Automake's @command{ylwrap} (which runs +@command{bison} with @option{--yacc}), @code{api.header.include} is +@emph{not} predefined when the output file is @file{y.tab.c}. Define it to +avoid the duplication. + @item Accepted Values: -Any absolute or relative C++ namespace reference without a trailing -@code{"::"}. For example, @code{"foo"} or @code{"::foo::bar"}. +An argument for @code{#include}. @item Default Value: -@code{yy}, unless you used the obsolete @samp{%name-prefix "@var{prefix}"} -directive. +@samp{"@var{header-basename}"}, unless the header file is @file{y.tab.h}, +where @var{header-basename} is the name of the generated header, without +directory part. For instance with @command{bison -d calc/parse.y}, +@code{api.header.include} defaults to @samp{"parse.h"}, not +@samp{"calc/parse.h"}. + +@item History: +Introduced in Bison 3.4. Defaults to @samp{"@var{basename}.h"} since Bison +3.7, unless the header file is @file{y.tab.h}. @end itemize @end deffn -@c api.namespace +@c api.header.include @c ================================================== api.location.file @@ -6043,6 +6057,46 @@ Introduced in Bison 2.7 for C++ and Java, in Bison 3.4 for C. @end deffn +@c ================================================== api.namespace +@deffn Directive {%define api.namespace} @{@var{namespace}@} +@itemize +@item Languages(s): C++ + +@item Purpose: Specify the namespace for the parser class. +For example, if you specify: + +@example +%define api.namespace @{foo::bar@} +@end example + +Bison uses @code{foo::bar} verbatim in references such as: + +@example +foo::bar::parser::semantic_type +@end example + +However, to open a namespace, Bison removes any leading @code{::} and then +splits on any remaining occurrences: + +@example +namespace foo @{ namespace bar @{ + class position; + class location; +@} @} +@end example + +@item Accepted Values: +Any absolute or relative C++ namespace reference without a trailing +@code{"::"}. For example, @code{"foo"} or @code{"::foo::bar"}. + +@item Default Value: +@code{yy}, unless you used the obsolete @samp{%name-prefix "@var{prefix}"} +directive. +@end itemize +@end deffn +@c api.namespace + + @c ================================================== api.parser.class @deffn Directive {%define api.parser.class} @{@var{name}@} @itemize @bullet |