From: Akim Demaille Date: Sun, 4 Nov 2007 21:15:11 +0000 (+0000) Subject: Generate the long/short option cross-table. X-Git-Tag: v2.3b~65 X-Git-Url: https://git.saurik.com/bison.git/commitdiff_plain/f4101aa612b2e2783ee0a78b88fb0d5f481ba363 Generate the long/short option cross-table. * build-aux/cross-options.pl: New. * doc/Makefile.am (cross-options.texi): New. * doc/bison.texinfo: Use it. --- diff --git a/ChangeLog b/ChangeLog index e11c5879..cbba5876 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2007-11-04 Akim Demaille + + Generate the long/short option cross-table. + * build-aux/cross-options.pl: New. + * doc/Makefile.am (cross-options.texi): New. + * doc/bison.texinfo: Use it. + 2007-11-04 Akim Demaille Generate bison.1 using help2man. diff --git a/build-aux/cross-options.pl b/build-aux/cross-options.pl new file mode 100755 index 00000000..4c941b04 --- /dev/null +++ b/build-aux/cross-options.pl @@ -0,0 +1,32 @@ +#! /usr/bin/env perl + +use warnings; +use 5.005; +use strict; + +my %option; +while (<>) +{ + if (/^\s*(?:(-\w), )?(--[-\w]+)(\[?)(=[-\w]+)?\]?/) + { + my ($short, $long, $opt, $arg) = ($1, $2, $3, $4); + $short = defined $short ? '@option{' . $short . '}' : ''; + if ($arg) + { + $arg =~ s/^=//; + $arg = '@var{' . lc ($arg) . '}'; + $arg = '[' . $arg . ']' + if defined $opt; + $option{"$long=$arg"} = "$short $arg"; + } + else + { + $option{"$long"} = "$short"; + } + } +} + +foreach my $long (sort keys %option) +{ + printf "\@item %-40s \@tab %s\n", '@option{' . $long . '}', $option{$long}; +} diff --git a/doc/bison.texinfo b/doc/bison.texinfo index c0fa7f08..583f48db 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -4514,8 +4514,8 @@ The result is that the communication variables @code{yylval} and @code{yylloc} become local variables in @code{yyparse}, and a different calling convention is used for the lexical analyzer function @code{yylex}. @xref{Pure Calling, ,Calling Conventions for Pure -Parsers}, for the details of this. The variable @code{yynerrs} -becomes local in @code{yyparse} in pull mode but it becomes a member +Parsers}, for the details of this. The variable @code{yynerrs} +becomes local in @code{yyparse} in pull mode but it becomes a member of yypstate in push mode. (@pxref{Error Reporting, ,The Error Reporting Function @code{yyerror}}). The convention for calling @code{yyparse} itself is unchanged. @@ -4530,14 +4530,14 @@ valid grammar. @cindex push parser @findex %define api.push_pull -A pull parser is called once and it takes control until all its input -is completely parsed. A push parser, on the other hand, is called +A pull parser is called once and it takes control until all its input +is completely parsed. A push parser, on the other hand, is called each time a new token is made available. -A push parser is typically useful when the parser is part of a +A push parser is typically useful when the parser is part of a main event loop in the client's application. This is typically -a requirement of a GUI, when the main event loop needs to be triggered -within a certain time period. +a requirement of a GUI, when the main event loop needs to be triggered +within a certain time period. Normally, Bison generates a pull parser. The following Bison declaration says that you want the parser to be a push @@ -4549,7 +4549,7 @@ parser (@pxref{Decl Summary,,%define api.push_pull}): In almost all cases, you want to ensure that your push parser is also a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}). The only -time you should create an impure push parser is to have backwards +time you should create an impure push parser is to have backwards compatibility with the impure Yacc pull mode interface. Unless you know what you are doing, your declarations should look like this: @@ -4558,17 +4558,17 @@ what you are doing, your declarations should look like this: %define api.push_pull "push" @end example -There is a major notable functional difference between the pure push parser -and the impure push parser. It is acceptable for a pure push parser to have +There is a major notable functional difference between the pure push parser +and the impure push parser. It is acceptable for a pure push parser to have many parser instances, of the same type of parser, in memory at the same time. An impure push parser should only use one parser at a time. When a push parser is selected, Bison will generate some new symbols in -the generated parser. @code{yypstate} is a structure that the generated -parser uses to store the parser's state. @code{yypstate_new} is the +the generated parser. @code{yypstate} is a structure that the generated +parser uses to store the parser's state. @code{yypstate_new} is the function that will create a new parser instance. @code{yypstate_delete} will free the resources associated with the corresponding parser instance. -Finally, @code{yypush_parse} is the function that should be called whenever a +Finally, @code{yypush_parse} is the function that should be called whenever a token is available to provide the parser. A trivial example of using a pure push parser would look like this: @@ -4582,10 +4582,10 @@ yypstate_delete (ps); @end example If the user decided to use an impure push parser, a few things about -the generated parser will change. The @code{yychar} variable becomes +the generated parser will change. The @code{yychar} variable becomes a global variable instead of a variable in the @code{yypush_parse} function. For this reason, the signature of the @code{yypush_parse} function is -changed to remove the token as a parameter. A nonreentrant push parser +changed to remove the token as a parameter. A nonreentrant push parser example would thus look like this: @example @@ -4599,26 +4599,26 @@ do @{ yypstate_delete (ps); @end example -That's it. Notice the next token is put into the global variable @code{yychar} +That's it. Notice the next token is put into the global variable @code{yychar} for use by the next invocation of the @code{yypush_parse} function. -Bison also supports both the push parser interface along with the pull parser +Bison also supports both the push parser interface along with the pull parser interface in the same generated parser. In order to get this functionality, -you should replace the @code{%define api.push_pull "push"} declaration with the +you should replace the @code{%define api.push_pull "push"} declaration with the @code{%define api.push_pull "both"} declaration. Doing this will create all of the symbols mentioned earlier along with the two extra symbols, @code{yyparse} -and @code{yypull_parse}. @code{yyparse} can be used exactly as it normally -would be used. However, the user should note that it is implemented in the +and @code{yypull_parse}. @code{yyparse} can be used exactly as it normally +would be used. However, the user should note that it is implemented in the generated parser by calling @code{yypull_parse}. This makes the @code{yyparse} function that is generated with the @code{%define api.push_pull "both"} declaration slower than the normal @code{yyparse} function. If the user calls the @code{yypull_parse} function it will parse the rest of the input -stream. It is possible to @code{yypush_parse} tokens to select a subgrammar -and then @code{yypull_parse} the rest of the input stream. If you would like -to switch back and forth between between parsing styles, you would have to -write your own @code{yypull_parse} function that knows when to quit looking -for input. An example of using the @code{yypull_parse} function would look +stream. It is possible to @code{yypush_parse} tokens to select a subgrammar +and then @code{yypull_parse} the rest of the input stream. If you would like +to switch back and forth between between parsing styles, you would have to +write your own @code{yypull_parse} function that knows when to quit looking +for input. An example of using the @code{yypull_parse} function would look like this: @example @@ -4628,7 +4628,7 @@ yypstate_delete (ps); @end example Adding the @code{%define api.pure} declaration does exactly the same thing to -the generated parser with @code{%define api.push_pull "both"} as it did for +the generated parser with @code{%define api.push_pull "both"} as it did for @code{%define api.push_pull "push"}. @node Decl Summary @@ -5036,10 +5036,10 @@ Rename the external symbols used in the parser so that they start with in C parsers is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yychar}, @code{yydebug}, and -(if locations are used) @code{yylloc}. If you use a push parser, -@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, -@code{yypstate_new} and @code{yypstate_delete} will -also be renamed. For example, if you use @samp{%name-prefix "c_"}, the +(if locations are used) @code{yylloc}. If you use a push parser, +@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, +@code{yypstate_new} and @code{yypstate_delete} will +also be renamed. For example, if you use @samp{%name-prefix "c_"}, the names become @code{c_parse}, @code{c_lex}, and so on. For C++ parsers, see the @code{%define namespace} documentation in this section. @@ -5155,10 +5155,10 @@ names that do not conflict. The precise list of symbols renamed is @code{yyparse}, @code{yylex}, @code{yyerror}, @code{yynerrs}, @code{yylval}, @code{yylloc}, -@code{yychar} and @code{yydebug}. If you use a push parser, -@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, +@code{yychar} and @code{yydebug}. If you use a push parser, +@code{yypush_parse}, @code{yypull_parse}, @code{yypstate}, @code{yypstate_new} and @code{yypstate_delete} will also be renamed. -For example, if you use @samp{-p c}, the names become @code{cparse}, +For example, if you use @samp{-p c}, the names become @code{cparse}, @code{clex}, and so on. @strong{All the other variables and macros associated with Bison are not @@ -5190,9 +5190,9 @@ in the grammar file, you are likely to run into trouble. * Parser Function:: How to call @code{yyparse} and what it returns. * Push Parser Function:: How to call @code{yypush_parse} and what it returns. * Pull Parser Function:: How to call @code{yypull_parse} and what it returns. -* Parser Create Function:: How to call @code{yypstate_new} and what it +* Parser Create Function:: How to call @code{yypstate_new} and what it returns. -* Parser Delete Function:: How to call @code{yypstate_delete} and what it +* Parser Delete Function:: How to call @code{yypstate_delete} and what it returns. * Lexical:: You must supply a function @code{yylex} which reads tokens. @@ -5280,13 +5280,13 @@ exp: @dots{} @{ @dots{}; *randomness += 1; @dots{} @} @section The Push Parser Function @code{yypush_parse} @findex yypush_parse -You call the function @code{yypush_parse} to parse a single token. This -function is available if either the @code{%define api.push_pull "push"} or -@code{%define api.push_pull "both"} declaration is used. +You call the function @code{yypush_parse} to parse a single token. This +function is available if either the @code{%define api.push_pull "push"} or +@code{%define api.push_pull "both"} declaration is used. @xref{Push Decl, ,A Push Parser}. @deftypefun int yypush_parse (yypstate *yyps) -The value returned by @code{yypush_parse} is the same as for yyparse with the +The value returned by @code{yypush_parse} is the same as for yyparse with the following exception. @code{yypush_parse} will return YYPUSH_MORE if more input is required to finish parsing the grammar. @end deftypefun @@ -5295,9 +5295,9 @@ is required to finish parsing the grammar. @section The Pull Parser Function @code{yypull_parse} @findex yypull_parse -You call the function @code{yypull_parse} to parse the rest of the input -stream. This function is available if the @code{%define api.push_pull "both"} -declaration is used. +You call the function @code{yypull_parse} to parse the rest of the input +stream. This function is available if the @code{%define api.push_pull "both"} +declaration is used. @xref{Push Decl, ,A Push Parser}. @deftypefun int yypull_parse (yypstate *yyps) @@ -5308,9 +5308,9 @@ The value returned by @code{yypull_parse} is the same as for @code{yyparse}. @section The Parser Create Function @code{yystate_new} @findex yypstate_new -You call the function @code{yypstate_new} to create a new parser instance. -This function is available if either the @code{%define api.push_pull "push"} or -@code{%define api.push_pull "both"} declaration is used. +You call the function @code{yypstate_new} to create a new parser instance. +This function is available if either the @code{%define api.push_pull "push"} or +@code{%define api.push_pull "both"} declaration is used. @xref{Push Decl, ,A Push Parser}. @deftypefun yypstate *yypstate_new (void) @@ -5323,8 +5323,8 @@ or NULL if no memory was available. @findex yypstate_delete You call the function @code{yypstate_delete} to delete a parser instance. -function is available if either the @code{%define api.push_pull "push"} or -@code{%define api.push_pull "both"} declaration is used. +function is available if either the @code{%define api.push_pull "push"} or +@code{%define api.push_pull "both"} declaration is used. @xref{Push Decl, ,A Push Parser}. @deftypefun void yypstate_delete (yypstate *yyps) @@ -7861,20 +7861,7 @@ the corresponding short option. @multitable {@option{--defines=@var{defines-file}}} {@option{-b @var{file-prefix}XXX}} @headitem Long Option @tab Short Option -@item @option{--debug} @tab @option{-t} -@item @option{--defines=@var{defines-file}} @tab @option{-d} -@item @option{--file-prefix=@var{prefix}} @tab @option{-b @var{file-prefix}} -@item @option{--graph=@var{graph-file}} @tab @option{-d} -@item @option{--help} @tab @option{-h} -@item @option{--name-prefix=@var{prefix}} @tab @option{-p @var{name-prefix}} -@item @option{--no-lines} @tab @option{-l} -@item @option{--output=@var{outfile}} @tab @option{-o @var{outfile}} -@item @option{--print-localedir} @tab -@item @option{--print-datadir} @tab -@item @option{--token-table} @tab @option{-k} -@item @option{--verbose} @tab @option{-v} -@item @option{--version} @tab @option{-V} -@item @option{--yacc} @tab @option{-y} +@include cross-options.texi @end multitable @node Yacc Library @@ -9750,7 +9737,7 @@ Management}. @deffn {Variable} yynerrs Global variable which Bison increments each time it reports a syntax error. -(In a pure parser, it is a local variable within @code{yyparse}. In a +(In a pure parser, it is a local variable within @code{yyparse}. In a pure push parser, it is a member of yypstate.) @xref{Error Reporting, ,The Error Reporting Function @code{yyerror}}. @end deffn @@ -9761,29 +9748,29 @@ parsing. @xref{Parser Function, ,The Parser Function @code{yyparse}}. @end deffn @deffn {Function} yypstate_delete -The function to delete a parser instance, produced by Bison in push mode; +The function to delete a parser instance, produced by Bison in push mode; call this function to delete the memory associated with a parser. -@xref{Parser Delete Function, ,The Parser Delete Function +@xref{Parser Delete Function, ,The Parser Delete Function @code{yypstate_delete}}. @end deffn @deffn {Function} yypstate_new -The function to create a parser instance, produced by Bison in push mode; +The function to create a parser instance, produced by Bison in push mode; call this function to create a new parser. -@xref{Parser Create Function, ,The Parser Create Function +@xref{Parser Create Function, ,The Parser Create Function @code{yypstate_new}}. @end deffn @deffn {Function} yypull_parse -The parser function produced by Bison in push mode; call this function to -parse the rest of the input stream. -@xref{Pull Parser Function, ,The Pull Parser Function +The parser function produced by Bison in push mode; call this function to +parse the rest of the input stream. +@xref{Pull Parser Function, ,The Pull Parser Function @code{yypull_parse}}. @end deffn @deffn {Function} yypush_parse -The parser function produced by Bison in push mode; call this function to -parse a single token. @xref{Push Parser Function, ,The Push Parser Function +The parser function produced by Bison in push mode; call this function to +parse a single token. @xref{Push Parser Function, ,The Push Parser Function @code{yypush_parse}}. @end deffn