From 3213832411d6b0c5ed15b4245ea59eae0a06ffbf Mon Sep 17 00:00:00 2001
From: Dick Hollenbeck <dick@softplc.com>
Date: Tue, 5 Oct 2010 08:38:15 -0500
Subject: [PATCH] enhance and better document PopReader()

---
 common/dsnlexer.cpp | 24 +++++++++++++++++-------
 include/dsnlexer.h  | 16 +++++++++++++---
 2 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/common/dsnlexer.cpp b/common/dsnlexer.cpp
index 49d84bf8be..1eb58e355f 100644
--- a/common/dsnlexer.cpp
+++ b/common/dsnlexer.cpp
@@ -57,9 +57,6 @@ void DSNLEXER::init()
     space_in_quoted_tokens = true;
 
     commentsAreTokens = false;
-
-    limit = start;
-    next  = start;
 }
 
 
@@ -90,15 +87,28 @@ void DSNLEXER::PushReader( LINE_READER* aLineReader )
     readerStack.push_back( aLineReader );
     reader = aLineReader;
     start = (char*) (*aLineReader);
+
+    // force a new readLine() as first thing.
+    limit = start;
+    next  = start;
 }
 
 
-void DSNLEXER::PopReader()
+bool DSNLEXER::PopReader()
 {
-    readerStack.pop_back();
-    reader = &readerStack.back();
-    if( reader )
+    // the very last reader cannot be popped, for that would screw up limit and next.
+    if( readerStack.size() >= 2 )
+    {
+        readerStack.pop_back();
+
+        reader = &readerStack.back();
+    
         start = (char*) (*reader);
+    
+        // force a new readLine() as first thing.
+        limit = start;
+        next  = start;
+    }
 }
 
 
diff --git a/include/dsnlexer.h b/include/dsnlexer.h
index 6143670174..f219474cfb 100644
--- a/include/dsnlexer.h
+++ b/include/dsnlexer.h
@@ -172,8 +172,12 @@ public:
     /**
      * Function PushReader
      * manages a stack of LINE_READERs in order to handle nested file inclusion.
-     * Pushes aLineReader onto the top of a stack of LINE_READERs and makes
+     * This function pushes aLineReader onto the top of a stack of LINE_READERs and makes
      * it the current LINE_READER with its own GetSource(), line number and line text.
+     * A grammar must be designed such that the "include" token (whatever its various names),
+     * and any of its parameters are not followed by anything on that same line,
+     * because PopReader always starts reading from a new line upon returning to
+     * the original LINE_READER.
      */
     void PushReader( LINE_READER* aLineReader );
 
@@ -183,9 +187,15 @@ public:
      * in the case of FILE_LINE_READER this means the associated FILE is closed.
      * The most recently used former LINE_READER on the stack becomes the
      * current LINE_READER and its previous position in its input stream and the
-     * its latest line number should pertain.
+     * its latest line number should pertain.  PopReader always starts reading 
+     * from a new line upon returning to the previous LINE_READER.  A pop is only
+     * possible if there are at least 2 LINE_READERs on the stack, since popping
+     * the last one is not supported.
+     *
+     * @return bool - true if there was at least two readers on the stack and 
+     *  therefore the pop succeeded, else false and the pop failed.
      */
-    void PopReader();
+    bool PopReader();
 
     // Some functions whose return value is best overloaded to return an enum
     // in a derived class.