flexdoc.1

早期freebsd实现

describe a scanner which is independent of any of the other rules in the
.I lex
input.  Because of this,
exclusive start conditions make it easy to specify "mini-scanners"
which scan portions of the input that are syntactically different
from the rest (e.g., comments).
.PP
If the distinction between inclusive and exclusive start conditions
is still a little vague, here's a simple example illustrating the
connection between the two.  The set of rules:
.nf

    %s example
    %%
    <example>foo           /* do something */

.fi
is equivalent to
.nf

    %x example
    %%
    <INITIAL,example>foo   /* do something */

.fi
.PP
Also note that the special start-condition specifier
.B <*>
matches every start condition.  Thus, the above example could also
have been written;
.nf

    %x example
    %%
    <*>foo   /* do something */

.fi
.PP
The default rule (to
.B ECHO
any unmatched character) remains active in start conditions.
.PP
.B BEGIN(0)
returns to the original state where only the rules with
no start conditions are active.  This state can also be
referred to as the start-condition "INITIAL", so
.B BEGIN(INITIAL)
is equivalent to
.B BEGIN(0).
(The parentheses around the start condition name are not required but
are considered good style.)
.PP
.B BEGIN
actions can also be given as indented code at the beginning
of the rules section.  For example, the following will cause
the scanner to enter the "SPECIAL" start condition whenever
.I yylex()
is called and the global variable
.I enter_special
is true:
.nf

            int enter_special;

    %x SPECIAL
    %%
            if ( enter_special )
                BEGIN(SPECIAL);

    <SPECIAL>blahblahblah
    ...more rules follow...

.fi
.PP
To illustrate the uses of start conditions,
here is a scanner which provides two different interpretations
of a string like "123.456".  By default it will treat it as
as three tokens, the integer "123", a dot ('.'), and the integer "456".
But if the string is preceded earlier in the line by the string
"expect-floats"
it will treat it as a single token, the floating-point number
123.456:
.nf

    %{
    #include <math.h>
    %}
    %s expect

    %%
    expect-floats        BEGIN(expect);

    <expect>[0-9]+"."[0-9]+      {
                printf( "found a float, = %f\\n",
                        atof( yytext ) );
                }
    <expect>\\n           {
                /* that's the end of the line, so
                 * we need another "expect-number"
                 * before we'll recognize any more
                 * numbers
                 */
                BEGIN(INITIAL);
                }

    [0-9]+      {
                printf( "found an integer, = %d\\n",
                        atoi( yytext ) );
                }

    "."         printf( "found a dot\\n" );

.fi
Here is a scanner which recognizes (and discards) C comments while
maintaining a count of the current input line.
.nf

    %x comment
    %%
            int line_num = 1;

    "/*"         BEGIN(comment);

    <comment>[^*\\n]*        /* eat anything that's not a '*' */
    <comment>"*"+[^*/\\n]*   /* eat up '*'s not followed by '/'s */
    <comment>\\n             ++line_num;
    <comment>"*"+"/"        BEGIN(INITIAL);

.fi
This scanner goes to a bit of trouble to match as much
text as possible with each rule.  In general, when attempting to write
a high-speed scanner try to match as much possible in each rule, as
it's a big win.
.PP
Note that start-conditions names are really integer values and
can be stored as such.  Thus, the above could be extended in the
following fashion:
.nf

    %x comment foo
    %%
            int line_num = 1;
            int comment_caller;

    "/*"         {
                 comment_caller = INITIAL;
                 BEGIN(comment);
                 }

    ...

    <foo>"/*"    {
                 comment_caller = foo;
                 BEGIN(comment);
                 }

    <comment>[^*\\n]*        /* eat anything that's not a '*' */
    <comment>"*"+[^*/\\n]*   /* eat up '*'s not followed by '/'s */
    <comment>\\n             ++line_num;
    <comment>"*"+"/"        BEGIN(comment_caller);

.fi
Furthermore, you can access the current start condition using
the integer-valued
.B YY_START
macro.  For example, the above assignments to
.I comment_caller
could instead be written
.nf

    comment_caller = YY_START;
.fi
.PP
Note that start conditions do not have their own name-space; %s's and %x's
declare names in the same fashion as #define's.
.PP
Finally, here's an example of how to match C-style quoted strings using
exclusive start conditions, including expanded escape sequences (but
not including checking for a string that's too long):
.nf

    %x str

    %%
            char string_buf[MAX_STR_CONST];
            char *string_buf_ptr;


    \\"      string_buf_ptr = string_buf; BEGIN(str);

    <str>\\"        { /* saw closing quote - all done */
            BEGIN(INITIAL);
            *string_buf_ptr = '\\0';
            /* return string constant token type and
             * value to parser
             */
            }

    <str>\\n        {
            /* error - unterminated string constant */
            /* generate error message */
            }

    <str>\\\\[0-7]{1,3} {
            /* octal escape sequence */
            int result;

            (void) sscanf( yytext + 1, "%o", &result );

            if ( result > 0xff )
                    /* error, constant is out-of-bounds */

            *string_buf_ptr++ = result;
            }

    <str>\\\\[0-9]+ {
            /* generate error - bad escape sequence; something
             * like '\\48' or '\\0777777'
             */
            }

    <str>\\\\n  *string_buf_ptr++ = '\\n';
    <str>\\\\t  *string_buf_ptr++ = '\\t';
    <str>\\\\r  *string_buf_ptr++ = '\\r';
    <str>\\\\b  *string_buf_ptr++ = '\\b';
    <str>\\\\f  *string_buf_ptr++ = '\\f';

    <str>\\\\(.|\\n)  *string_buf_ptr++ = yytext[1];

    <str>[^\\\\\\n\\"]+        {
            char *yytext_ptr = yytext;

            while ( *yytext_ptr )
                    *string_buf_ptr++ = *yytext_ptr++;
            }

.fi
.SH MULTIPLE INPUT BUFFERS
Some scanners (such as those which support "include" files)
require reading from several input streams.  As
.I lex
scanners do a large amount of buffering, one cannot control
where the next input will be read from by simply writing a
.B YY_INPUT
which is sensitive to the scanning context.
.B YY_INPUT
is only called when the scanner reaches the end of its buffer, which
may be a long time after scanning a statement such as an "include"
which requires switching the input source.
.PP
To negotiate these sorts of problems,
.I lex
provides a mechanism for creating and switching between multiple
input buffers.  An input buffer is created by using:
.nf

    YY_BUFFER_STATE yy_create_buffer( FILE *file, int size )

.fi
which takes a
.I FILE
pointer and a size and creates a buffer associated with the given
file and large enough to hold
.I size
characters (when in doubt, use
.B YY_BUF_SIZE
for the size).  It returns a
.B YY_BUFFER_STATE
handle, which may then be passed to other routines:
.nf

    void yy_switch_to_buffer( YY_BUFFER_STATE new_buffer )

.fi
switches the scanner's input buffer so subsequent tokens will
come from
.I new_buffer.
Note that
.B yy_switch_to_buffer()
may be used by yywrap() to set things up for continued scanning, instead
of opening a new file and pointing
.I yyin
at it.
.nf

    void yy_delete_buffer( YY_BUFFER_STATE buffer )

.fi
is used to reclaim the storage associated with a buffer.
.PP
.B yy_new_buffer()
is an alias for
.B yy_create_buffer(),
provided for compatibility with the C++ use of
.I new
and
.I delete
for creating and destroying dynamic objects.
.PP
Finally, the
.B YY_CURRENT_BUFFER
macro returns a
.B YY_BUFFER_STATE
handle to the current buffer.
.PP
Here is an example of using these features for writing a scanner
which expands include files (the
.B <<EOF>>
feature is discussed below):
.nf

    /* the "incl" state is used for picking up the name
     * of an include file
     */
    %x incl

    %{
    #define MAX_INCLUDE_DEPTH 10
    YY_BUFFER_STATE include_stack[MAX_INCLUDE_DEPTH];
    int include_stack_ptr = 0;
    %}

    %%
    include             BEGIN(incl);

    [a-z]+              ECHO;
    [^a-z\\n]*\\n?        ECHO;

    <incl>[ \\t]*      /* eat the whitespace */
    <incl>[^ \\t\\n]+   { /* got the include file name */
            if ( include_stack_ptr >= MAX_INCLUDE_DEPTH )
                {
                fprintf( stderr, "Includes nested too deeply" );
                exit( 1 );
                }

            include_stack[include_stack_ptr++] =
                YY_CURRENT_BUFFER;

            yyin = fopen( yytext, "r" );

            if ( ! yyin )
                error( ... );

            yy_switch_to_buffer(
                yy_create_buffer( yyin, YY_BUF_SIZE ) );

            BEGIN(INITIAL);
            }

    <<EOF>> {
            if ( --include_stack_ptr < 0 )
                {
                yyterminate();
                }

            else
                {
                yy_delete_buffer( YY_CURRENT_BUFFER );
                yy_switch_to_buffer(
                     include_stack[include_stack_ptr] );
                }
            }

.fi
.SH END-OF-FILE RULES
The special rule "<<EOF>>" indicates
actions which are to be taken when an end-of-file is
encountered and yywrap() returns non-zero (i.e., indicates
no further files to process).  The action must finish
by doing one of four things:
.IP -
assigning
.I yyin
to a new input file (in previous versions of lex, after doing the
assignment you had to call the special action
.B YY_NEW_FILE;
this is no longer necessary);
.IP -
executing a
.I return
statement;
.IP -
executing the special
.B yyterminate()
action;
.IP -
or, switching to a new buffer using
.B yy_switch_to_buffer()
as shown in the example above.
.PP
<<EOF>> rules may not be used with other
patterns; they may only be qualified with a list of start
conditions.  If an unqualified <<EOF>> rule is given, it
applies to
.I all
start conditions which do not already have <<EOF>> actions.  To
specify an <<EOF>> rule for only the initial start condition, use
.nf

    <INITIAL><<EOF>>

.fi
.PP
These rules are useful for catching things like unclosed comments.
An example:
.nf

    %x quote
    %%

    ...other rules for dealing with quotes...

    <quote><<EOF>>   {
             error( "unterminated quote" );
             yyterminate();
             }
    <<EOF>>  {
             if ( *++filelist )
                 yyin = fopen( *filelist, "r" );
             else
                yyterminate();
             }

.fi
.SH MISCELLANEOUS MACROS
The macro
.bd
YY_USER_ACTION
can be defined to provide an action
which is always executed prior to the matched rule's action.  For example,
it could be #define'd to call a routine to convert yytext to lower-case.
.PP
The macro
.B YY_USER_INIT
may be defined to provide an action which is always executed before
the first scan (and before the scanner's internal initializations are done).
For example, it could be used to call a routine to read
in a data table or open a logging file.
.PP
In the generated scanner, the actions are all gathered in one large
switch statement and separated using
.B YY_BREAK,
which may be redefined.  By default, it is simply a "break", to separate
each rule's action from the following rule's.
Redefining
.B YY_BREAK
allows, for example, C++ users to
#define YY_BREAK to do nothing (while being very careful that every
rule ends with a "break" or a "return"!) to avoid suffering from
unreachable statement warnings where because a rule's action ends with
"return", the
.B YY_BREAK
is inaccessible.
.SH INTERFACING WITH YACC
One of the main uses of
.I lex
is as a companion to the
.I yacc
parser-generator.
.I yacc
parsers expect to call a routine named
.B yylex()
to find the next input token.  The routine is supposed to
return the type of the next token as well as putting any associated
value in the global
.B yylval.
To use
.I lex
with
.I yacc,
one specifies the
.B \-d
option to
.I yacc
to instruct it to generate the file
.B y.tab.h
containing definitions of all the
.B %tokens
appearing in the
.I yacc
input.  This file is then included in the
.I lex
scanner.  For example, if one of the tokens is "TOK_NUMBER",
part of the scanner might look like:
.nf

    %{
    #include "y.tab.h"
    %}

    %%

    [0-9]+        yylval = atoi( yytext ); return TOK_NUMBER;

.fi
.SH OPTIONS
.I lex
has the following options: