Update all the examples to use the new API elements.

Add a fully reentrant example.  And update to TODO file.

Author: eric-s-raymond

TODO

@@ -2,4 +2,8 @@ Things to be worked on:
 
 * Tests for %option user-init, %option pre-action, %option post-action.
 
+* integrate examples directory into tests so that normal testing
+  proves the examples are up to date.
 
+* Do away with any need for -lfl by generating a default yywrap
+  if the user doesn't specify one.

doc/flex.texi

@@ -354,49 +354,15 @@ Here's another simple example:
 
 @cindex counting characters and lines; reentrant
 @example
-@verbatim
-    %{
-            int num_lines = 0, num_chars = 0;
-    %}
-    %option reentrant
-    %%
-    \n      ++num_lines; ++num_chars;
-    .       ++num_chars;
-
-    %%
-
-    int main() {
-            yyscan_t scanner;
-
-            yylex_init ( &scanner );
-            yylex ( scanner );
-            yylex_destroy ( scanner );
-
-            printf( "# of lines = %d, # of chars = %d\n",
-                    num_lines, num_chars );
-    }
-@end verbatim
+@verbatiminclude ../examples/manual/example_r.lex
 @end example
 
 If you have looked at older versions of the Flex nanual, you might
 have seen a version of the above example that looked more like this:
 
 @cindex counting characters and lines; non-reentrant
 @example
-@verbatim
-            int num_lines = 0, num_chars = 0;
-    %%
-    \n      ++num_lines; ++num_chars;
-    .       ++num_chars;
-
-    %%
-
-    int main() {
-            yylex();
-            printf( "# of lines = %d, # of chars = %d\n",
-                    num_lines, num_chars );
-    }
-@end verbatim
+@verbatiminclude ../examples/manual/example_nr.lex
 @end example
 
 Both versions count the number of characters and the number of lines in
@@ -422,13 +388,24 @@ language other than the original C/C++ non-reentrancy is not even an
 option.
 
 This, it's a good idea to get used to using the reentrant interface
-from the beginning of your Flex prgramming. This is so even though the
+from the beginning of your Flex programming. This is so even though the
 reentrant example above is a rather poor one; it avoids exposing the
 scanner state in globals but creates globals of its own. There is a
 mechanism for including user-defined fields in the scanner structure
 which will be explained in detail at @xref{Extra Data}. For now,
 consider this:
 
+@example
+@verbatiminclude ../examples/manual/example_er.lex
+@end example
+
+While it requires a bit more ceremony, several instances of this
+scanner can be run concurrently without stepping on each others'
+storage.
+
+(The @code{%option noyywrap} in these examples is helpful in
+making them run standalone, but does not change the behavior of the scsnner.)
+
 A somewhat more complicated example:
 
 @cindex Pascal-like language
@@ -596,7 +573,8 @@ themselves.
 
 A @code{%top} block is similar to a @samp{%@{} ... @samp{%@}} block, except
 that the code in a @code{%top} block is relocated to the @emph{top} of the
-generated file, before any flex definitions @footnote{Actually,
+generated file, before any flex definitions @footnote{Actually, in the
+C/C++ back end,
 @code{yyIN_HEADER} is defined before the @samp{%top} block.}. 
 The @code{%top} block is useful when you want definitions to be
 evaluated or certain files to be included before the generated code.
@@ -1642,7 +1620,7 @@ condition remains unchanged; it does @emph{not} revert to
 
 @cindex yywrap, default for
 @cindex noyywrap, %option
-@cindex %option noyywrapp
+@cindex %option noyywrap
 If you do not supply your own version of @code{yywrap()}, then you must
 either use @code{%option noyywrap} (in which case the scanner behaves as
 though @code{yywrap()} returned 1), or you must link with @samp{-lfl} to

examples/manual/Makefile.am

@@ -30,6 +30,7 @@ EXTRA_DIST = \
 	eof_test01.txt \
 	eof_test02.txt \
 	eof_test03.txt \
+	example_er.lex \
 	example_r.lex \
 	example_nr.lex \
 	expr.lex \

examples/manual/Makefile.examples

@@ -18,7 +18,7 @@ ALLOCA   =
 # DO NOT CHANGE ANYTHING FROM HERE ON !!!!!!!!! 
 #
 ############################################################
-PATH = ${PATH}:/usr/local/bin
+PATH := /usr/local/bin:${PATH}
 
 all: expr front myname eof wc replace user_act string1\
      string2 yymore numbers dates cat
@@ -31,6 +31,10 @@ example_nr: example_nr.lex
 	$(LEX)  example_nr.lex
 	$(CC)   lex.yy.c -o example_nr
 
+example_er: example_er.lex
+	$(LEX)  example_er.lex
+	$(CC)   lex.yy.c -o example_er
+
 expr:   expr.y expr.lex
 	$(YACC) expr.y
 	$(LEX)  expr.lex

examples/manual/dates.lex

@@ -54,13 +54,13 @@ day_ext     (st|nd|rd|th)?
   /* the default is month-day-year */
 
 <LONG>{day_of_the_week}    strcpy(dow,yytext); 
-<LONG>{month}              strcpy(month,yytext); BEGIN(DAY);
+<LONG>{month}              strcpy(month,yytext); yybegin(DAY);
 
   /* handle the form: day-month-year */
 
-<LONG>{nday}{day_ext}      strcpy(day,yytext);   BEGIN(DAY_FIRST);
-<DAY_FIRST>{month}         strcpy(month,yytext); BEGIN(LONG);
-<DAY>{nday}{day_ext}       strcpy(day,yytext);   BEGIN(LONG);  
+<LONG>{nday}{day_ext}      strcpy(day,yytext);   yybegin(DAY_FIRST);
+<DAY_FIRST>{month}         strcpy(month,yytext); yybegin(LONG);
+<DAY>{nday}{day_ext}       strcpy(day,yytext);   yybegin(LONG);  
 
 <LONG>{nyear}{year_ext}  {
                            printf("Long:\n");
@@ -75,15 +75,15 @@ day_ext     (st|nd|rd|th)?
 
   /* handle dates of the form: day-month-year */
 
-<SHORT>{nday}              strcpy(day,yytext);  BEGIN(YEAR_LAST);
-<YEAR_LAST>{nmonth}        strcpy(month,yytext);BEGIN(YLMONTH);
-<YLMONTH>{nyear}           strcpy(year,yytext); BEGIN(SHORT);
+<SHORT>{nday}              strcpy(day,yytext);  yybegin(YEAR_LAST);
+<YEAR_LAST>{nmonth}        strcpy(month,yytext);yybegin(YLMONTH);
+<YLMONTH>{nyear}           strcpy(year,yytext); yybegin(SHORT);
 
   /* handle dates of the form: year-month-day */
 
-<SHORT>{nyear}             strcpy(year,yytext); BEGIN(YEAR_FIRST);
-<YEAR_FIRST>{nmonth}       strcpy(month,yytext);BEGIN(YFMONTH);
-<YFMONTH>{nday}            strcpy(day,yytext);  BEGIN(SHORT);
+<SHORT>{nyear}             strcpy(year,yytext); yybegin(YEAR_FIRST);
+<YEAR_FIRST>{nmonth}       strcpy(month,yytext);yybegin(YFMONTH);
+<YFMONTH>{nday}            strcpy(day,yytext);  yybegin(SHORT);
 
 
 <SHORT>\n                {
@@ -96,8 +96,8 @@ day_ext     (st|nd|rd|th)?
                            strcpy(month,"");
                          }
 
-long\n                      BEGIN(LONG);
-short\n                     BEGIN(SHORT);
+long\n                      yybegin(LONG);
+short\n                     yybegin(SHORT);
 
 {skip}*
 \n

examples/manual/eof_rules.lex

@@ -17,8 +17,8 @@ int             include_count = -1;
 
 %%
 
-^"#include"[ \t]*\"  BEGIN(INCLUDE);
-<INCLUDE>\"          BEGIN(INITIAL); 
+^"#include"[ \t]*\"  yybegin(INCLUDE);
+<INCLUDE>\"          yybegin(INITIAL); 
 <INCLUDE>[^\"]+ {      /* get the include file name */
           if ( include_count >= MAX_NEST){
              fprintf( stderr, "Too many include files" );
@@ -35,7 +35,7 @@ int             include_count = -1;
 
           yy_switch_to_buffer(yy_create_buffer(yyin,YY_BUF_SIZE));
 
-          BEGIN(INITIAL);
+          yybegin(INITIAL);
         }
 <INCLUDE><<EOF>> 
         {
@@ -48,7 +48,7 @@ int             include_count = -1;
           } else {
             yy_delete_buffer(include_stack[include_count--] );
             yy_switch_to_buffer(include_stack[include_count] );
-            BEGIN(INCLUDE);
+            yybegin(INCLUDE);
           }
         }
 [a-z]+               ECHO;

examples/manual/example_er.lex

@@ -0,0 +1,35 @@
+/* basic example, fully reentrant thread-safe version */
+%{
+ struct stats {
+     int num_lines;
+     int num_chars;
+ };
+%}
+%option reentrant noyywrap
+%option extra-type="struct stats"
+%%
+\n	{
+     		struct stats ns = yyget_extra(yyscanner);
+		++ns.num_lines; ++ns.num_chars;
+		yyset_extra(ns, yyscanner);
+	}
+.       {
+     		struct stats ns = yyget_extra(yyscanner);
+		++ns.num_chars;
+		yyset_extra(ns, yyscanner);
+	}
+
+%%
+
+int main() {
+        yyscan_t scanner;
+	struct stats ns;
+
+        yylex_init ( &scanner );
+        yylex ( scanner );
+
+	ns = yyget_extra(scanner);
+        printf( "# of lines = %d, # of chars = %d\n",
+                ns.num_lines, ns.num_chars);
+        yylex_destroy ( scanner );
+}

examples/manual/example_nr.lex

@@ -1,4 +1,8 @@
-        int num_lines = 0, num_chars = 0;
+/* basic example - non-reentrant version */
+%{
+	int num_lines = 0, num_chars = 0;
+%}
+%option noyywrap
 %%
 \n      ++num_lines; ++num_chars;
 .       ++num_chars;

examples/manual/example_r.lex

@@ -1,7 +1,8 @@
+/* basic example - flawed reentrant version with global */
 %{
         int num_lines = 0, num_chars = 0;
 %}
-%option reentrant
+%option reentrant noyywrap
 %%
 \n      ++num_lines; ++num_chars;
 .       ++num_chars;

examples/manual/front.lex

@@ -3,9 +3,6 @@
 #include <string.h>
 #include "y.tab.h"                 /* this comes from bison        */
 
-#define TRUE  1
-#define FALSE 0
-
 #define copy_and_return(token_type) { strcpy(yylval.name,yytext); \
                                       return(token_type); }