diff options
Diffstat (limited to 'flex.texi')
| -rw-r--r-- | flex.texi | 271 |
1 files changed, 134 insertions, 137 deletions
@@ -69,7 +69,6 @@ Reentrant C Scanners * Reentrant Overview:: * Reentrant Example:: * Reentrant Detail:: -* Bison Pure:: * Reentrant Functions:: The Reentrant API in Detail @@ -200,6 +199,7 @@ FAQ Appendices * Makefiles and Flex:: +* Bison Bridge:: Indices @@ -2370,6 +2370,21 @@ is used, the generated scanner will run faster (see the @samp{--perf-report} fla Only users who wish to squeeze every last cycle out of their scanners need worry about this option. (@pxref{Performance}). +@anchor{option-bison-bridge} +@item --bison-bridge, @code{%option bison-bridge} +instructs flex to generate a C scanner that is +meant to be called by a +@code{GNU bison} +parser. The scanner has minor API changes for +@code{bison} +compatibility. In particular, the declaration of +@code{yylex} +is modified, and support for +@code{yylval} +and +@code{yylloc} +is incorporated. @xref{Bison Bridge}. + @item -c is a do-nothing option included for POSIX compliance. @@ -2574,24 +2589,7 @@ reentrant and non-reentrant @code{flex} scanners, non-reentrant flex code must be modified before it is suitable for use with this option. This option is not compatible with the @samp{--c++} option. -@anchor{option-reentrant-bison} -@item -Rb, --reentrant-bison, @code{%option reentrant-bison} -instructs flex to generate a reentrant C scanner that is -meant to be called by a -@code{GNU bison} -pure parser. The scanner is the same as the scanner generated by the -@samp{--reentrant} -option, but with minor API changes for -@code{bison} -compatibility. In particular, the declaration of -@code{yylex} -is modified, and support for -@code{yylval} -and -@code{yylloc} -is incorporated. @xref{Bison Pure}. - -The options @samp{--reentrant} and @samp{--reentrant-bison} do not affect the performance of +The option @samp{--reentrant} does not affect the performance of the scanner. @anchor{option-trace} @@ -3558,20 +3556,17 @@ and may change considerably between major releases. @cindex reentrant, explanation @code{flex} has the ability to generate a reentrant C scanner. This is -accomplished by specifying @code{%option reentrant} (@samp{-R}) or -@code{%option reentrant-bison} (@samp{-Rb}). The generated scanner is -both portable, and safe to use in one or more separate threads of +accomplished by specifying @code{%option reentrant} (@samp{-R}) The generated +scanner is both portable, and safe to use in one or more separate threads of control. The most common use for reentrant scanners is from within -multi-threaded applications. Any thread may create and execute a -reentrant @code{flex} scanner without the need for synchronization with -other threads. +multi-threaded applications. Any thread may create and execute a reentrant +@code{flex} scanner without the need for synchronization with other threads. @menu * Reentrant Uses:: * Reentrant Overview:: * Reentrant Example:: * Reentrant Detail:: -* Bison Pure:: * Reentrant Functions:: @end menu @@ -3982,116 +3977,6 @@ an internal structure. You should never access this value directly. In particular, you should never attempt to free it (use @code{yylex_destroy()} instead.) - -@node Bison Pure -@section Reentrant C Scanners with Bison Pure Parsers - -@cindex bison, with reentrant -@vindex yylval -@vindex yylloc -@tindex YYLTYPE -@tindex YYSTYPE - -This section describes the @code{flex} features useful when integrating -@code{flex} with @code{GNU bison}@footnote{The features described here are -purely optional, and are by no means the only way to use flex with bison. -We merely provide some glue to ease development of your parser-scanner pair.}. -Skip this section if you are not using -@code{bison} with your scanner. Here we discuss only the @code{flex} -half of the @code{flex} and @code{bison} pair. We do not discuss -@code{bison} in any detail. For more information about generating pure -@code{bison} parsers, see @ref{Top, , , bison, the GNU Bison Manual}. - -A @code{bison}-compatible scanner is generated by declaring @samp{%option -reentrant-bison} or by supplying @samp{--reentrant-bison} when invoking @code{flex} -from the command line. This instructs @code{flex} that the macros -@code{yylval} and @code{yylloc} may be used. The data types for -@code{yylval} and @code{yylloc}, (@code{YYSTYPE} and @code{YYLTYPE}, -are typically defined in a header file, included in section 1 of the -@code{flex} input file. @code{%option reentrant-bison} implies -@code{%option reentrant}. If @code{%option reentrant-bison} is -specified, @code{flex} provides support for the functions -@code{yyget_lval}, @code{yyset_lval}, @code{yyget_lloc}, and -@code{yyset_lloc}, defined below, and the corresponding macros -@code{yylval} and @code{yylloc}, for use within actions. - -@deftypefun YYSTYPE* yyget_lval ( yyscan_t scanner ) -@end deftypefun -@deftypefun YYLTYPE* yyget_lloc ( yyscan_t scanner ) -@end deftypefun - -@deftypefun void yyset_lval ( YYSTYPE* lvalp, yyscan_t scanner ) -@end deftypefun -@deftypefun void yyset_lloc ( YYLTYPE* llocp, yyscan_t scanner ) -@end deftypefun - -Accordingly, the declaration of yylex becomes one of the following: - -@findex yylex (reentrant version) -@example -@verbatim - int yylex ( YYSTYPE * lvalp, yyscan_t scanner ); - int yylex ( YYSTYPE * lvalp, YYLTYPE * llocp, yyscan_t scanner ); -@end verbatim -@end example - -Note that the macros @code{yylval} and @code{yylloc} evaluate to -pointers. Support for @code{yylloc} is optional in @code{bison}, so it -is optional in @code{flex} as well. This support is automatically -handled by @code{flex}. Specifically, support for @code{yyloc} is only -present in a @code{flex} scanner if the preprocessor symbol -@code{YYLTYPE} is defined. The following is an example of a @code{flex} -scanner that is @code{bison}-compatible. - -@exindex bison, scanner to be called from bison -@example -@verbatim - /* Scanner for "C" assignment statements... sort of. */ - %{ - #include "y.tab.h" /* Generated by bison. */ - %} - - %option reentrant-bison - % - - [[:digit:]]+ { yylval->num = atoi(yytext); return NUMBER;} - [[:alnum:]]+ { yylval->str = strdup(yytext); return STRING;} - "="|";" { return yytext[0];} - . {} - % -@end verbatim -@end example - -As you can see, there really is no magic here. We just use -@code{yylval} as we would any other variable. The data type of -@code{yylval} is generated by @code{bison}, and included in the file -@file{y.tab.h}. Here is the corresponding @code{bison} parser: - -@exindex bison, parser -@example -@verbatim - /* Parser to convert "C" assignments to lisp. */ - %{ - /* Pass the argument to yyparse through to yylex. */ - #define YYPARSE_PARAM scanner - #define YYLEX_PARAM scanner - %} - %pure_parser - %union { - int num; - char* str; - } - %token <str> STRING - %token <num> NUMBER - %% - assignment: - STRING '=' NUMBER ';' { - printf( "(setf %s %d)", $1, $3 ); - } - ; -@end verbatim -@end example - @node Reentrant Functions @section Functions and Macros Available in Reentrant C Scanners @@ -4152,7 +4037,7 @@ In a reentrant C scanner, support for yylineno is always present the user to maintain the line count independently of @code{flex}. The following functions and macros are made available when @code{%option -reentrant-bison} (@samp{--reentrant-bison}) is specified: +bison-bridge} (@samp{--bison-bridge}) is specified: @example @verbatim @@ -7802,6 +7687,7 @@ then the problem is that the last rule needs to be "{whitespace}" ! @menu * Makefiles and Flex:: +* Bison Bridge:: @end menu @node Makefiles and Flex @@ -7913,6 +7799,117 @@ with your specific implementation of @command{make}. For more details on writing Makefiles, see @ref{Top, , , make, The GNU Make Manual}. +@node Bison Bridge +@section C Scanners with Bison Parsers + +@cindex bison, bridging with flex +@vindex yylval +@vindex yylloc +@tindex YYLTYPE +@tindex YYSTYPE + +This section describes the @code{flex} features useful when integrating +@code{flex} with @code{GNU bison}@footnote{The features described here are +purely optional, and are by no means the only way to use flex with bison. +We merely provide some glue to ease development of your parser-scanner pair.}. +Skip this section if you are not using +@code{bison} with your scanner. Here we discuss only the @code{flex} +half of the @code{flex} and @code{bison} pair. We do not discuss +@code{bison} in any detail. For more information about generating +@code{bison} parsers, see @ref{Top, , , bison, the GNU Bison Manual}. + +A compatible @code{bison} scanner is generated by declaring @samp{%option +bison-bridge} or by supplying @samp{--bison-bridge} when invoking @code{flex} +from the command line. This instructs @code{flex} that the macros +@code{yylval} and @code{yylloc} may be used. The data types for +@code{yylval} and @code{yylloc}, (@code{YYSTYPE} and @code{YYLTYPE}, +are typically defined in a header file, included in section 1 of the +@code{flex} input file. If @code{%option bison-bridge} is +specified, @code{flex} provides support for the functions +@code{yyget_lval}, @code{yyset_lval}, @code{yyget_lloc}, and +@code{yyset_lloc}, defined below, and the corresponding macros +@code{yylval} and @code{yylloc}, for use within actions. + +@deftypefun YYSTYPE* yyget_lval ( yyscan_t scanner ) +@end deftypefun +@deftypefun YYLTYPE* yyget_lloc ( yyscan_t scanner ) +@end deftypefun + +@deftypefun void yyset_lval ( YYSTYPE* lvalp, yyscan_t scanner ) +@end deftypefun +@deftypefun void yyset_lloc ( YYLTYPE* llocp, yyscan_t scanner ) +@end deftypefun + +Where yyscan_t is defined in the reentrant scanner @footnote{The bison bridge +works with non-reentrant scanners, too.}. Accordingly, the declaration of +yylex becomes one of the following: + +@findex yylex (reentrant version) +@example +@verbatim + int yylex ( YYSTYPE * lvalp, yyscan_t scanner ); + int yylex ( YYSTYPE * lvalp, YYLTYPE * llocp, yyscan_t scanner ); +@end verbatim +@end example + +Note that the macros @code{yylval} and @code{yylloc} evaluate to +pointers. Support for @code{yylloc} is optional in @code{bison}, so it +is optional in @code{flex} as well. This support is automatically +handled by @code{flex}. Specifically, support for @code{yyloc} is only +present in a @code{flex} scanner if the preprocessor symbol +@code{YYLTYPE} is defined. The following is an example of a @code{flex} +scanner that is compatible with @code{bison}. + +@exindex bison, scanner to be called from bison +@example +@verbatim + /* Scanner for "C" assignment statements... sort of. */ + %{ + #include "y.tab.h" /* Generated by bison. */ + %} + + %option reentrant-bison + % + + [[:digit:]]+ { yylval->num = atoi(yytext); return NUMBER;} + [[:alnum:]]+ { yylval->str = strdup(yytext); return STRING;} + "="|";" { return yytext[0];} + . {} + % +@end verbatim +@end example + +As you can see, there really is no magic here. We just use +@code{yylval} as we would any other variable. The data type of +@code{yylval} is generated by @code{bison}, and included in the file +@file{y.tab.h}. Here is the corresponding @code{bison} parser: + +@exindex bison, parser +@example +@verbatim + /* Parser to convert "C" assignments to lisp. */ + %{ + /* Pass the argument to yyparse through to yylex. */ + #define YYPARSE_PARAM scanner + #define YYLEX_PARAM scanner + %} + %pure_parser + %union { + int num; + char* str; + } + %token <str> STRING + %token <num> NUMBER + %% + assignment: + STRING '=' NUMBER ';' { + printf( "(setf %s %d)", $1, $3 ); + } + ; +@end verbatim +@end example + + @node Indices @unnumbered Indices |