Future/bison
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/bison.git synced 2026-03-11 13:23:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: formatting changes

Browse Source 
* doc/bison.texi: here.
This commit is contained in:
Akim Demaille
2019-01-02 13:08:12 +01:00
parent 890ee8a1fd
commit 9f81497a0c
1 changed files with 95 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
doc/bison.texi
View File

@@ -32,8 +32,8 @@
@copying
This manual (@value{UPDATED}) is for GNU Bison (version
@value{VERSION}), the GNU parser generator.
This manual (@value{UPDATED}) is for GNU Bison (version @value{VERSION}),
the GNU parser generator.
Copyright @copyright{} 1988-1993, 1995, 1998-2015, 2018 Free Software
Foundation, Inc.
@@ -436,39 +436,37 @@ This edition corresponds to version @value{VERSION} of Bison.
@node Conditions
@unnumbered Conditions for Using Bison
The distribution terms for Bison-generated parsers permit using the
parsers in nonfree programs. Before Bison version 2.2, these extra
permissions applied only when Bison was generating LALR(1)
parsers in C@. And before Bison version 1.24, Bison-generated
parsers could be used only in programs that were free software.
The distribution terms for Bison-generated parsers permit using the parsers
in nonfree programs. Before Bison version 2.2, these extra permissions
applied only when Bison was generating LALR(1) parsers in C@. And before
Bison version 1.24, Bison-generated parsers could be used only in programs
that were free software.
The other GNU programming tools, such as the GNU C
compiler, have never
had such a requirement. They could always be used for nonfree
software. The reason Bison was different was not due to a special
policy decision; it resulted from applying the usual General Public
License to all of the Bison source code.
The other GNU programming tools, such as the GNU C compiler, have never had
such a requirement. They could always be used for nonfree software. The
reason Bison was different was not due to a special policy decision; it
resulted from applying the usual General Public License to all of the Bison
source code.
The main output of the Bison utility---the Bison parser implementation
file---contains a verbatim copy of a sizable piece of Bison, which is
the code for the parser's implementation. (The actions from your
grammar are inserted into this implementation at one point, but most
of the rest of the implementation is not changed.) When we applied
the GPL terms to the skeleton code for the parser's implementation,
the effect was to restrict the use of Bison output to free software.
file---contains a verbatim copy of a sizable piece of Bison, which is the
code for the parser's implementation. (The actions from your grammar are
inserted into this implementation at one point, but most of the rest of the
implementation is not changed.) When we applied the GPL terms to the
skeleton code for the parser's implementation, the effect was to restrict
the use of Bison output to free software.
We didn't change the terms because of sympathy for people who want to
make software proprietary. @strong{Software should be free.} But we
concluded that limiting Bison's use to free software was doing little to
encourage people to make other software free. So we decided to make the
practical conditions for using Bison match the practical conditions for
using the other GNU tools.
We didn't change the terms because of sympathy for people who want to make
software proprietary. @strong{Software should be free.} But we concluded
that limiting Bison's use to free software was doing little to encourage
people to make other software free. So we decided to make the practical
conditions for using Bison match the practical conditions for using the
other GNU tools.
This exception applies when Bison is generating code for a parser.
You can tell whether the exception applies to a Bison output file by
inspecting the file for text beginning with ``As a special
exception@dots{}''. The text spells out the exact terms of the
exception.
This exception applies when Bison is generating code for a parser. You can
tell whether the exception applies to a Bison output file by inspecting the
file for text beginning with ``As a special exception@dots{}''. The text
spells out the exact terms of the exception.
@node Copying
@unnumbered GNU GENERAL PUBLIC LICENSE
@@ -477,9 +475,9 @@ exception.
@node Concepts
@chapter The Concepts of Bison
This chapter introduces many of the basic concepts without which the
details of Bison will not make sense. If you do not already know how to
use Bison or Yacc, we suggest you start by reading this chapter carefully.
This chapter introduces many of the basic concepts without which the details
of Bison will not make sense. If you do not already know how to use Bison
or Yacc, we suggest you start by reading this chapter carefully.
@menu
* Language and Grammar:: Languages and context-free grammars,
@@ -5695,36 +5693,32 @@ it, using @samp{%locations} allows for more accurate syntax error messages.
@deffn {Directive} %name-prefix "@var{prefix}"
Rename the external symbols used in the parser so that they start with
@var{prefix} instead of @samp{yy}. The precise list of symbols renamed
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
names become @code{c_parse}, @code{c_lex}, and so on.
For C++ parsers, see the @samp{%define api.namespace} documentation in this
section.
@xref{Multiple Parsers, ,Multiple Parsers in the Same Program}.
@var{prefix} instead of @samp{yy}. The precise list of symbols renamed 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 names become @code{c_parse}, @code{c_lex}, and
so on. For C++ parsers, see the @samp{%define api.namespace} documentation
in this section. @xref{Multiple Parsers, ,Multiple Parsers in the Same
Program}.
@end deffn
@ifset defaultprec
@deffn {Directive} %no-default-prec
Do not assign a precedence to rules lacking an explicit @code{%prec}
modifier (@pxref{Contextual Precedence, ,Context-Dependent
Precedence}).
modifier (@pxref{Contextual Precedence, ,Context-Dependent Precedence}).
@end deffn
@end ifset
@deffn {Directive} %no-lines
Don't generate any @code{#line} preprocessor commands in the parser
implementation file. Ordinarily Bison writes these commands in the
parser implementation file so that the C compiler and debuggers will
associate errors and object code with your source file (the grammar
file). This directive causes them to associate errors with the parser
implementation file, treating it as an independent source file in its
own right.
implementation file. Ordinarily Bison writes these commands in the parser
implementation file so that the C compiler and debuggers will associate
errors and object code with your source file (the grammar file). This
directive causes them to associate errors with the parser implementation
file, treating it as an independent source file in its own right.
@end deffn
@deffn {Directive} %output "@var{file}"
@@ -5792,15 +5786,14 @@ The number of parser states (@pxref{Parser States}).
@end deffn
@deffn {Directive} %verbose
Write an extra output file containing verbose descriptions of the
parser states and what is done for each type of lookahead token in
that state. @xref{Understanding, , Understanding Your Parser}, for more
information.
Write an extra output file containing verbose descriptions of the parser
states and what is done for each type of lookahead token in that state.
@xref{Understanding, , Understanding Your Parser}, for more information.
@end deffn
@deffn {Directive} %yacc
Pretend the option @option{--yacc} was given, i.e., imitate Yacc,
including its naming conventions. @xref{Bison Options}, for more.
Pretend the option @option{--yacc} was given, i.e., imitate Yacc, including
its naming conventions. @xref{Bison Options}, for more.
@end deffn
@@ -5808,11 +5801,10 @@ including its naming conventions. @xref{Bison Options}, for more.
@subsection %define Summary
There are many features of Bison's behavior that can be controlled by
assigning the feature a single value. For historical reasons, some
such features are assigned values by dedicated directives, such as
@code{%start}, which assigns the start symbol. However, newer such
features are associated with variables, which are assigned by the
@code{%define} directive:
assigning the feature a single value. For historical reasons, some such
features are assigned values by dedicated directives, such as @code{%start},
which assigns the start symbol. However, newer such features are associated
with variables, which are assigned by the @code{%define} directive:
@deffn {Directive} %define @var{variable}
@deffnx {Directive} %define @var{variable} @var{value}
@@ -5829,12 +5821,12 @@ It is an error if a @var{variable} is defined by @code{%define} multiple
times, but see @ref{Bison Options,,@option{-D @var{name}[=@var{value}]}}.
@end deffn
The rest of this section summarizes variables and values that
@code{%define} accepts.
The rest of this section summarizes variables and values that @code{%define}
accepts.
Some @var{variable}s take Boolean values. In this case, Bison will
complain if the variable definition does not meet one of the following
four conditions:
Some @var{variable}s take Boolean values. In this case, Bison will complain
if the variable definition does not meet one of the following four
conditions:
@enumerate
@item @code{@var{value}} is @code{true}
@@ -5849,11 +5841,11 @@ In this case, Bison selects a default value.
@end enumerate
What @var{variable}s are accepted, as well as their meanings and default
values, depend on the selected target language and/or the parser
skeleton (@pxref{Decl Summary,,%language}, @pxref{Decl
Summary,,%skeleton}).
Unaccepted @var{variable}s produce an error.
Some of the accepted @var{variable}s are described below.
values, depend on the selected target language and/or the parser skeleton
(@pxref{Decl Summary,,%language}, @pxref{Decl Summary,,%skeleton}).
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}@}
@@ -5889,12 +5881,12 @@ Any absolute or relative C++ namespace reference without a trailing
@item Default Value:
The value specified by @code{%name-prefix}, which defaults to @code{yy}.
This usage of @code{%name-prefix} is for backward compatibility and can
be confusing since @code{%name-prefix} also specifies the textual prefix
for the lexical analyzer function. Thus, if you specify
@code{%name-prefix}, it is best to also specify @samp{%define
api.namespace} so that @code{%name-prefix} @emph{only} affects the
lexical analyzer function. For example, if you specify:
This usage of @code{%name-prefix} is for backward compatibility and can be
confusing since @code{%name-prefix} also specifies the textual prefix for
the lexical analyzer function. Thus, if you specify @code{%name-prefix}, it
is best to also specify @samp{%define api.namespace} so that
@code{%name-prefix} @emph{only} affects the lexical analyzer function. For
example, if you specify:
@example
%define api.namespace @{foo@}
@@ -5907,6 +5899,7 @@ The parser namespace is @code{foo} and @code{yylex} is referenced as
@end deffn
@c api.namespace
@c ================================================== api.location.file
@deffn {Directive} {%define api.location.file} "@var{file}"
@deffnx {Directive} {%define api.location.file} @code{none}
@@ -5941,6 +5934,7 @@ Introduced in Bison 3.2.
@end itemize
@end deffn
@c ================================================== api.location.file
@deffn {Directive} {%define api.location.include} @{"@var{file}"@}
@deffnx {Directive} {%define api.location.include} @{<@var{file}>@}
@@ -5987,6 +5981,7 @@ Introduced in Bison 2.7 for C, C++ and Java. Introduced under the name
@end itemize
@end deffn
@c ================================================== api.parser.class
@deffn Directive {%define api.parser.class} @{@var{name}@}
@itemize @bullet
@@ -6027,6 +6022,7 @@ Introduced in Bison 3.3 to replace @code{parser_class_name}.
@end itemize
@end deffn
@c ================================================== api.pure
@deffn Directive {%define api.pure} @var{purity}
@@ -6374,6 +6370,7 @@ introduced as @code{lr.default-reductions} in 2.5, renamed as
@end itemize
@end deffn
@c ============================================ lr.keep-unreachable-state
@deffn Directive {%define lr.keep-unreachable-state}
@@ -6392,6 +6389,7 @@ introduced as @code{lr.keep_unreachable_states} in 2.3b, renamed as
@end deffn
@c lr.keep-unreachable-state
@c ================================================== lr.type
@deffn Directive {%define lr.type} @var{type}
@@ -6408,12 +6406,14 @@ LR(1) family. @xref{LR Table Construction}.
@end itemize
@end deffn
@c ================================================== namespace
@deffn Directive %define namespace @{@var{namespace}@}
Obsoleted by @code{api.namespace}
@end deffn
@c namespace
@c ================================================== parse.assert
@deffn Directive {%define parse.assert}
@@ -6473,6 +6473,7 @@ syntax error handling. @xref{LAC}.
@end deffn
@c parse.lac
@c ================================================== parse.trace
@deffn Directive {%define parse.trace}
@@ -6495,6 +6496,7 @@ compiled.
@end deffn
@c parse.trace
@c ================================================== parser_class_name
@deffn Directive %define parser_class_name @{@var{name}@}
Obsoleted by @code{api.parser.class}
@@ -12233,22 +12235,22 @@ The Java parser skeletons are selected using the @code{%language "Java"}
directive or the @option{-L java}/@option{--language=java} option.
@c FIXME: Documented bug.
When generating a Java parser, @code{bison @var{basename}.y} will
create a single Java source file named @file{@var{basename}.java}
containing the parser implementation. Using a grammar file without a
@file{.y} suffix is currently broken. The basename of the parser
implementation file can be changed by the @code{%file-prefix}
directive or the @option{-p}/@option{--name-prefix} option. The
entire parser implementation file name can be changed by the
@code{%output} directive or the @option{-o}/@option{--output} option.
The parser implementation file contains a single class for the parser.
When generating a Java parser, @code{bison @var{basename}.y} will create a
single Java source file named @file{@var{basename}.java} containing the
parser implementation. Using a grammar file without a @file{.y} suffix is
currently broken. The basename of the parser implementation file can be
changed by the @code{%file-prefix} directive or the
@option{-p}/@option{--name-prefix} option. The entire parser implementation
file name can be changed by the @code{%output} directive or the
@option{-o}/@option{--output} option. The parser implementation file
contains a single class for the parser.
You can create documentation for generated parsers using Javadoc.
Contrary to C parsers, Java parsers do not use global variables; the
state of the parser is always local to an instance of the parser class.
Therefore, all Java parsers are ``pure'', and the @code{%pure-parser}
and @code{%define api.pure} directives do nothing when used in Java.
Contrary to C parsers, Java parsers do not use global variables; the state
of the parser is always local to an instance of the parser class.
Therefore, all Java parsers are ``pure'', and the @code{%pure-parser} and
@code{%define api.pure} directives do nothing when used in Java.
Push parsers are currently unsupported in Java and @code{%define
api.push-pull} have no effect.