\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}
@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
@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
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
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}.
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
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
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
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
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
((expseq1 ?, exp)) ;; | expseq1 ',' exp
) ;; ;
@end group
-@end example
+@end smallexample
@cindex precedence level
@item precedence
Now the precedence of @code{UMINUS} can be used in specific rules:
-@example
+@smallexample
@group
(exp @dots{} ;; exp: @dots{}
((exp ?- exp)) ;; | exp '-' exp
@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
@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
'(
;; Terminals
(NUM)
-
+
;; Terminal associativity & precedence
((nonassoc ?=)
(left ?- ?+)
(left ?* ?/)
(left NEG)
(right ?^))
-
+
;; Rules
(input
((line))
@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
@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
@end table
@menu
-* Grammar Debugging::
-* Understanding the automaton::
+* Grammar Debugging::
+* Understanding the automaton::
@end menu
@node Grammar Debugging
@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:
(wisent-compile-grammar
'((NUM STR) ; %token NUM STR
- ((left ?+ ?-) ; %left '+' '-';
+ ((left ?+ ?-) ; %left '+' '-';
(left ?*)) ; %left '*'
(exp ; exp:
@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:
$default reduce using rule 2 (exp)
-
state 9
exp -> exp . '+' exp (rule 1)
$default reduce using rule 3 (exp)
-
state 10
exp -> exp . '+' exp (rule 1)
@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
@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
@example
@group
-(stmnt (( error ?; )) ;; on error, skip until ';' is read
- )
+(statement (( error ?; )) ;; on error, skip until ';' is read
+ )
@end group
@end example
@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:
@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
for more information on @semantic{} grammars.
@menu
-* Grammar styles::
-* Wisent Lex::
+* Grammar styles::
+* Wisent Lex::
@end menu
@node Grammar styles
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
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.}
@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}):
@node GNU Free Documentation License
@appendix GNU Free Documentation License
-@include fdl.texi
+@include doclicense.texi
@node Index
@unnumbered Index
HCoop / bpt / emacs.git / blobdiff