X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/9e7abd17a34f432aa6f3e59896d794b1349c846a..29993416fb4d19c1c3bb146367fc4bed74845486:/doc/misc/wisent.texi diff --git a/doc/misc/wisent.texi b/doc/misc/wisent.texi index 2567c835af..b5d7899bd5 100644 --- a/doc/misc/wisent.texi +++ b/doc/misc/wisent.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename wisent.info +@setfilename ../../info/wisent.info @set TITLE Wisent Parser Development @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim @settitle @value{TITLE} @@ -20,38 +20,38 @@ @c @footnotestyle separate @c @paragraphindent 2 @c @@smallbook +@documentencoding UTF-8 @c %**end of header @copying -This manual documents the Wisent parser generator. - -Copyright @copyright{} 2001, 2002, 2003, 2004, 2007 David Ponce +Copyright @copyright{} 1988--1993, 1995, 1998--2004, 2007, 2012--2014 +Free Software Foundation, Inc. +@c Since we are both GNU manuals, we do not need to ack each other here. +@ignore Some texts are borrowed or adapted from the manual of Bison version 1.35. The text in section entitled ``Understanding the automaton'' is adapted from the section ``Understanding Your Parser'' in the manual of Bison version 1.49. - -Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, -1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. +@end ignore @quotation Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being list their titles, with the Front-Cover Texts -being list, and with the Back-Cover Texts being list. A copy of the -license is included in the section entitled ``GNU Free Documentation -License''. +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' @end quotation @end copying -@ifinfo -@dircategory Emacs +@dircategory Emacs misc features @direntry -* Semantic Wisent parser development: (wisent). +* Wisent: (wisent). Semantic Wisent parser development. @end direntry -@end ifinfo @iftex @finalout @@ -60,29 +60,19 @@ License''. @c @setchapternewpage odd @c @setchapternewpage off -@ifinfo -This file documents Application Development with Semantic. -@emph{Infrastructure for parser based text analysis in Emacs} - -Copyright @copyright{} 2001, 2002, 2003, 2004 @value{AUTHOR} -@end ifinfo - @titlepage @sp 10 @title @value{TITLE} @author by @value{AUTHOR} -@vskip 0pt plus 1 fill -Copyright @copyright{} 2001, 2002, 2003, 2004 @value{AUTHOR} @page @vskip 0pt plus 1 fill @insertcopying @end titlepage @page -@c MACRO inclusion -@include semanticheader.texi -@paragraphindent none - +@macro semantic{} +@i{Semantic} +@end macro @c ************************************************************************* @c @ Document @@ -102,13 +92,17 @@ source in Emacs buffers. It also describes how Wisent is used with the @semantic{} tool set described in the @ref{Top, Semantic Manual, Semantic Manual, semantic}. +@ifnottex +@insertcopying +@end ifnottex + @menu -* Wisent Overview:: -* Wisent Grammar:: -* Wisent Parsing:: -* Wisent Semantic:: -* GNU Free Documentation License:: -* Index:: +* Wisent Overview:: +* Wisent Grammar:: +* Wisent Parsing:: +* Wisent Semantic:: +* GNU Free Documentation License:: +* Index:: @end menu @node Wisent Overview @@ -119,10 +113,7 @@ of the GNU Compiler Compiler Bison. Its code is a port of the C code of GNU Bison 1.28 & 1.31. For more details on the basic concepts for understanding Wisent, it is -worthwhile to read the @ref{Top, Bison Manual, bison}. -@ifhtml -@uref{http://www.gnu.org/manual/bison/html_node/index.html}. -@end ifhtml +worthwhile to read the @ref{Top, Bison Manual, , bison}. Wisent can generate compilers compatible with the @semantic{} tool set. See the @ref{Top, Semantic Manual, , semantic}. @@ -130,7 +121,7 @@ See the @ref{Top, Semantic Manual, , semantic}. It benefits from these Bison features: @itemize @bullet -@item +@item It uses a fast but not so space-efficient encoding for the parse tables, described in Corbett's PhD thesis from Berkeley: @quotation @@ -138,19 +129,20 @@ tables, described in Corbett's PhD thesis from Berkeley: June 1985, Report No. UCB/CSD 85/251. @end quotation -@item +@item For generating the lookahead sets, Wisent uses the well-known -technique of F. DeRemer and A. Pennello they described in: +technique of F. DeRemer and T. Pennello described in: @quotation -@cite{Efficient Construction of LALR(1) Lookahead Sets}@* -October 1982, ACM TOPLS Vol 4 No 4. +@cite{Efficient Computation of LALR(1) Look-Ahead Sets}@* +October 1982, ACM TOPLAS Vol 4 No 4, 615--49, +@uref{http://dx.doi.org/10.1145/69622.357187}. @end quotation -@item +@item Wisent resolves shift/reduce conflicts using operator precedence and associativity. -@item +@item Parser error recovery is accomplished using rules which match the special token @code{error}. @end itemize @@ -223,16 +215,15 @@ exp @equiv{} exp PLUS exp Says that two groupings of type @samp{exp}, with a @samp{PLUS} token in between, can be combined into a larger grouping of type @samp{exp}. - + @menu -* Grammar format:: -* Example:: -* Compiling a grammar:: -* Conflicts:: +* Grammar format:: +* Example:: +* Compiling a grammar:: +* Conflicts:: @end menu -@node Grammar format, Example, Wisent Grammar, Wisent Grammar -@comment node-name, next, previous, up +@node Grammar format @section Grammar format @cindex grammar format @@ -290,7 +281,7 @@ For example, Says that two groupings of type @samp{exp}, with a @samp{+} token in between, can be combined into a larger grouping of type @samp{exp}. - + @cindex grammar coding conventions By convention, a nonterminal symbol should be in lower case, such as @samp{exp}, @samp{stmt} or @samp{declaration}. Terminal symbols @@ -309,7 +300,7 @@ If @var{components} in a rule is @code{nil}, it means that the rule can match the empty string. For example, here is how to define a comma-separated sequence of zero or more @samp{exp} groupings: -@example +@smallexample @group (expseq (nil) ;; expseq: ;; empty ((expseq1)) ;; | expseq1 @@ -319,7 +310,7 @@ comma-separated sequence of zero or more @samp{exp} groupings: ((expseq1 ?, exp)) ;; | expseq1 ',' exp ) ;; ; @end group -@end example +@end smallexample @cindex precedence level @item precedence @@ -346,7 +337,7 @@ serves to stand for its precedence: Now the precedence of @code{UMINUS} can be used in specific rules: -@example +@smallexample @group (exp @dots{} ;; exp: @dots{} ((exp ?- exp)) ;; | exp '-' exp @@ -355,7 +346,7 @@ Now the precedence of @code{UMINUS} can be used in specific rules: @dots{} ;; @dots{} ) ;; ; @end group -@end example +@end smallexample If you forget to append @code{[UMINUS]} to the rule for unary minus, Wisent silently assumes that minus has its usual precedence. This @@ -450,8 +441,7 @@ matching the empty string, for which the default action is to return @end table @end table -@node Example, Compiling a grammar, Grammar format, Wisent Grammar -@comment node-name, next, previous, up +@node Example @section Example @cindex grammar example @@ -463,14 +453,14 @@ Here is an example to parse simple infix arithmetic expressions. See '( ;; Terminals (NUM) - + ;; Terminal associativity & precedence ((nonassoc ?=) (left ?- ?+) (left ?* ?/) (left NEG) (right ?^)) - + ;; Rules (input ((line)) @@ -566,8 +556,7 @@ exp: @end group @end example -@node Compiling a grammar, Conflicts, Example, Wisent Grammar -@comment node-name, next, previous, up +@node Compiling a grammar @section Compiling a grammar @cindex automaton @@ -625,8 +614,7 @@ an Emacs Lisp function (lambda expression). @end table @end defun -@node Conflicts, , Compiling a grammar, Wisent Grammar -@comment node-name, next, previous, up +@node Conflicts @section Conflicts Normally, a grammar should produce an automaton where at each state @@ -671,8 +659,8 @@ information. @end table @menu -* Grammar Debugging:: -* Understanding the automaton:: +* Grammar Debugging:: +* Understanding the automaton:: @end menu @node Grammar Debugging @@ -701,7 +689,7 @@ Toggle whether to report verbose information on generated parser. @end deffn The verbose report is printed in the temporary buffer -@code{*wisent-log*} when running interactively, or in file +@file{*wisent-log*} when running interactively, or in file @file{wisent.output} when running in batch mode. Different reports are separated from each other by a line like this: @@ -742,7 +730,7 @@ We will use the following example: (wisent-compile-grammar '((NUM STR) ; %token NUM STR - ((left ?+ ?-) ; %left '+' '-'; + ((left ?+ ?-) ; %left '+' '-'; (left ?*)) ; %left '*' (exp ; exp: @@ -772,7 +760,7 @@ Grammar contains 7 shift/reduce conflicts @end group @end example -The @samp{*wisent-log*} buffer details things! +The @file{*wisent-log*} buffer details things! The first section reports conflicts that were solved using precedence and/or associativity: @@ -1039,7 +1027,6 @@ state 8 $default reduce using rule 2 (exp) - state 9 exp -> exp . '+' exp (rule 1) @@ -1054,7 +1041,6 @@ state 9 $default reduce using rule 3 (exp) - state 10 exp -> exp . '+' exp (rule 1) @@ -1183,11 +1169,11 @@ Normal hook run just after the @var{LR} parser engine terminated. @end defvar @menu -* Writing a lexer:: -* Actions goodies:: -* Report errors:: -* Error recovery:: -* Debugging actions:: +* Writing a lexer:: +* Actions goodies:: +* Report errors:: +* Error recovery:: +* Debugging actions:: @end menu @node Writing a lexer @@ -1223,7 +1209,7 @@ data type. @item start @itemx end -Are the optionals beginning and end positions of @var{value} in the +Are the optional beginning and ending positions of @var{value} in the input stream. @end table @@ -1346,8 +1332,8 @@ of the current statement if an error is detected: @example @group -(stmnt (( error ?; )) ;; on error, skip until ';' is read - ) +(statement (( error ?; )) ;; on error, skip until ';' is read + ) @end group @end example @@ -1457,7 +1443,7 @@ tokens (@pxref{Useful functions}). @defun wisent-skip-token @anchor{wisent-skip-token} Skip the lookahead token in order to resume parsing. -Return nil. +Return @code{nil}. Must be used in error recovery semantic actions. It typically looks like this: @@ -1477,7 +1463,7 @@ It typically looks like this: @findex wisent-skip-block @defun wisent-skip-block Safely skip a block in order to resume parsing. -Return nil. +Return @code{nil}. Must be used in error recovery semantic actions. A block is data between an open-delimiter (syntax class @code{(}) and @@ -1593,8 +1579,8 @@ Please @inforef{top, Semantic Grammar Framework Manual, grammar-fw} for more information on @semantic{} grammars. @menu -* Grammar styles:: -* Wisent Lex:: +* Grammar styles:: +* Wisent Lex:: @end menu @node Grammar styles @@ -1608,14 +1594,14 @@ used with the @semantic{} tool set: the @dfn{Iterative style} and the it can be worth a mix of the two styles! @menu -* Iterative style:: -* Bison style:: -* Mixed style:: -* Start nonterminals:: -* Useful functions:: +* Iterative style:: +* Bison style:: +* Mixed style:: +* Start nonterminals:: +* Useful functions:: @end menu -@node Iterative style, Bison style, Grammar styles, Grammar styles +@node Iterative style @subsection Iterative style @cindex grammar iterative style @@ -1929,7 +1915,7 @@ schedules an incremental re-parse of that data, using the tag's reviewed to ensure that the incremental parser will work!} Things are a little bit different when the grammar is written in Bison -style. +style. @strong{The @code{reparse-symbol} property is set to the nonterminal symbol the rule that explicitly uses @code{EXPANDTAG} belongs to.} @@ -1996,7 +1982,7 @@ Is a symbol that identifies a lexical token class, like @code{symbol}, @itemx end Are the start and end positions of mapped data in the input buffer. @end table - + The Wisent's parser doesn't depend on the nature of analyzed input stream (buffer, string, etc.), and requires that lexical tokens have a different form (@pxref{Writing a lexer}): @@ -2036,7 +2022,7 @@ equivalent Wisent lexical tokens is straightforward: @node GNU Free Documentation License @appendix GNU Free Documentation License -@include fdl.texi +@include doclicense.texi @node Index @unnumbered Index