From 5b06606339fa957579a7039eb0065a51ffe3dab8 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim@epita.fr>
Date: Sat, 29 Mar 2003 13:29:41 +0000
Subject: [PATCH] * doc/bison.texinfo (How Can I Reset @code{yyparse}): New.

---
 ChangeLog         |  6 +++-
 doc/bison.texinfo | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index 22c4c4c..304afa2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2003-03-29  Akim Demaille  <akim@epita.fr>
+
+	* doc/bison.texinfo (How Can I Reset @code{yyparse}): New.
+
 2003-03-13  Paul Eggert  <eggert@twinsun.com>
 
 	* .cvsignore: Add configure.lineno.
@@ -35,7 +39,7 @@
 	Quote AC_FOREACH variable-expansions properly.
 	The 2003-01-03 obstack.h change also needs merging.
 	{end of changes requiring merging}
-	
+
 	* lib/stdbool.h.in, m4/alloca.m4, m4/dirname.m4, m4/dos.m4,
 	m4/getopt.m4, m4/hash.m4, m4/malloc.m4, m4/memchr.m4,
 	m4/memrchr.m4, m4/obstack.m4, m4/onceonly.m4, m4/quote.m4,
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 9332050..3ed6b7f 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -284,6 +284,7 @@ Invoking Bison
 Frequently Asked Questions
 
 * Parser Stack Overflow::      Breaking the Stack Limits
+* How Can I Reset @code{yyparse}::    @code{yyparse} Keeps some State
 * Strings are Destroyed::      @code{yylval} Loses Track of Strings
 
 Copying This Manual
@@ -6353,6 +6354,7 @@ are addressed.
 
 @menu
 * Parser Stack Overflow::      Breaking the Stack Limits
+* How Can I Reset @code{yyparse}::    @code{yyparse} Keeps some State
 * Strings are Destroyed::      @code{yylval} Loses Track of Strings
 @end menu
 
@@ -6367,6 +6369,89 @@ message.  What can I do?
 This question is already addressed elsewhere, @xref{Recursion,
 ,Recursive Rules}.
 
+@node How Can I Reset @code{yyparse}
+@section How Can I Reset @code{yyparse}
+
+The following phenomenon gives raise to several incarnations,
+resulting in the following typical questions:
+
+@display
+I invoke @code{yyparse} several times, and on correct input it works
+properly; but when a parse error is found, all the other calls fail
+too.  How can I reset @code{yyparse}'s error flag?
+@end display
+
+@noindent
+or
+
+@display
+My parser includes support for a @samp{#include} like feature, in
+which case I run @code{yyparse} from @code{yyparse}.  This fails
+although I did specify I needed a @code{%pure-parser}.
+@end display
+
+These problems are not related to Bison itself, but with the Lex
+generated scanners.  Because these scanners use large buffers for
+speed, they might not notice a change of input file.  As a
+demonstration, consider the following source file,
+@file{first-line.l}:
+
+@verbatim
+%{
+#include <stdio.h>
+#include <stdlib.h>
+%}
+%%
+.*\n    ECHO; return 1;
+%%
+int
+yyparse (const char *file)
+{
+  yyin = fopen (file, "r");
+  if (!yyin)
+    exit (2);
+  /* One token only. */
+  yylex ();
+  if (!fclose (yyin))
+    exit (3);
+  return 0;
+}
+
+int
+main ()
+{
+  yyparse ("input");
+  yyparse ("input");
+  return 0;
+}
+@end verbatim
+
+@noindent
+If the file @file{input} contains
+
+@verbatim
+input:1: Hello,
+input:2: World!
+@end verbatim
+
+@noindent
+then instead of getting twice the first line, you get:
+
+@example
+$ @kbd{flex -ofirst-line.c first-line.l}
+$ @kbd{gcc  -ofirst-line   first-line.c -ll}
+$ @kbd{./first-line}
+input:1: Hello,
+input:2: World!
+@end example
+
+Therefore, whenever you change @code{yyin}, you must tell the Lex
+generated scanner to discard its current buffer, and to switch to the
+new one.  This depends upon your implementation of Lex, see its
+documentation for more.  For instance, in the case of Flex, a simple
+call @samp{yyrestart (yyin)} suffices after each change to
+@code{yyin}.
+
 @node Strings are Destroyed
 @section Strings are Destroyed
 
-- 
2.7.4