flexdoc.1

早期freebsd实现

.TP
.B \-b
Generate backing-up information to
.I lex.backup.
This is a list of scanner states which require backing up
and the input characters on which they do so.  By adding rules one
can remove backing-up states.  If all backing-up states
are eliminated and
.B \-Cf
or
.B \-CF
is used, the generated scanner will run faster (see the
.B \-p
flag).  Only users who wish to squeeze every last cycle out of their
scanners need worry about this option.  (See the section on Performance
Considerations below.)
.TP
.B \-c
is a do-nothing, deprecated option included for POSIX compliance.
.IP
.B NOTE:
in previous releases of
.I lex
.B \-c
specified table-compression options.  This functionality is
now given by the
.B \-C
flag.  To ease the the impact of this change, when
.I lex
encounters
.B \-c,
it currently issues a warning message and assumes that
.B \-C
was desired instead.  In the future this "promotion" of
.B \-c
to
.B \-C
will go away in the name of full POSIX compliance (unless
the POSIX meaning is removed first).
.TP
.B \-d
makes the generated scanner run in
.I debug
mode.  Whenever a pattern is recognized and the global
.B yy_flex_debug
is non-zero (which is the default),
the scanner will write to
.I stderr
a line of the form:
.nf

    --accepting rule at line 53 ("the matched text")

.fi
The line number refers to the location of the rule in the file
defining the scanner (i.e., the file that was fed to lex).  Messages
are also generated when the scanner backs up, accepts the
default rule, reaches the end of its input buffer (or encounters
a NUL; at this point, the two look the same as far as the scanner's concerned),
or reaches an end-of-file.
.TP
.B \-f
specifies
.I fast scanner.
No table compression is done and stdio is bypassed.
The result is large but fast.  This option is equivalent to
.B \-Cfr
(see below).
.TP
.B \-h
generates a "help" summary of
.I lex's
options to
.I stderr 
and then exits.
.TP
.B \-i
instructs
.I lex
to generate a
.I case-insensitive
scanner.  The case of letters given in the
.I lex
input patterns will
be ignored, and tokens in the input will be matched regardless of case.  The
matched text given in
.I yytext
will have the preserved case (i.e., it will not be folded).
.TP
.B \-l
turns on maximum compatibility with the original AT&T
.I lex
implementation.  Note that this does not mean
.I full
compatibility.  Use of this option costs a considerable amount of
performance, and it cannot be used with the
.B -f, -F, -Cf,
or
.B -CF
options.  For details on the compatibilities it provides, see the section
"Incompatibilities With AT&T Lex And POSIX" below.
.TP
.B \-n
is another do-nothing, deprecated option included only for
POSIX compliance.
.TP
.B \-p
generates a performance report to stderr.  The report
consists of comments regarding features of the
.I lex
input file which will cause a serious loss of performance in the resulting
scanner.  If you give the flag twice, you will also get comments regarding
features that lead to minor performance losses.
.IP
Note that the use of
.B REJECT
and variable trailing context (see the Bugs section in lex(1))
entails a substantial performance penalty; use of
.I yymore(),
the
.B ^
operator,
and the
.B \-I
flag entail minor performance penalties.
.TP
.B \-s
causes the
.I default rule
(that unmatched scanner input is echoed to
.I stdout)
to be suppressed.  If the scanner encounters input that does not
match any of its rules, it aborts with an error.  This option is
useful for finding holes in a scanner's rule set.
.TP
.B \-t
instructs
.I lex
to write the scanner it generates to standard output instead
of
.B lex.yy.c.
.TP
.B \-v
specifies that
.I lex
should write to
.I stderr
a summary of statistics regarding the scanner it generates.
Most of the statistics are meaningless to the casual
.I lex
user, but the first line identifies the version of
.I lex
(same as reported by
.B \-V),
and the next line the flags used when generating the scanner, including
those that are on by default.
.TP
.B \-w
suppresses warning messages.
.TP
.B \-B
instructs
.I lex
to generate a
.I batch
scanner, the opposite of
.I interactive
scanners generated by
.B \-I
(see below).  In general, you use
.B \-B
when you are
.I certain
that your scanner will never be used interactively, and you want to
squeeze a
.I little
more performance out of it.  If your goal is instead to squeeze out a
.I lot
more performance, you should  be using the
.B \-Cf
or
.B \-CF
options (discussed below), which turn on
.B \-B
automatically anyway.
.TP
.B \-F
specifies that the
.ul
fast
scanner table representation should be used (and stdio
bypassed).  This representation is
about as fast as the full table representation
.B (-f),
and for some sets of patterns will be considerably smaller (and for
others, larger).  In general, if the pattern set contains both "keywords"
and a catch-all, "identifier" rule, such as in the set:
.nf

    "case"    return TOK_CASE;
    "switch"  return TOK_SWITCH;
    ...
    "default" return TOK_DEFAULT;
    [a-z]+    return TOK_ID;

.fi
then you're better off using the full table representation.  If only
the "identifier" rule is present and you then use a hash table or some such
to detect the keywords, you're better off using
.B -F.
.IP
This option is equivalent to
.B \-CFr
(see below).
.TP
.B \-I
instructs
.I lex
to generate an
.I interactive
scanner.  An interactive scanner is one that only looks ahead to decide
what token has been matched if it absolutely must.  It turns out that
always looking one extra character ahead, even if the scanner has already
seen enough text to disambiguate the current token, is a bit faster than
only looking ahead when necessary.  But scanners that always look ahead
give dreadful interactive performance; for example, when a user types
a newline, it is not recognized as a newline token until they enter
.I another
token, which often means typing in another whole line.
.IP
.I lex
scanners default to
.I interactive
unless you use the
.B \-Cf
or
.B \-CF
table-compression options (see below).  That's because if you're looking
for high-performance you should be using one of these options, so if you
didn't,
.I lex
assumes you'd rather trade off a bit of run-time performance for intuitive
interactive behavior.  Note also that you
.I cannot
use
.B \-I
in conjunction with
.B \-Cf
or
.B \-CF.
Thus, this option is not really needed; it is on by default for all those
cases in which it is allowed.
.IP
You can force a scanner to
.I not
be interactive by using
.B \-B
(see above).
.TP
.B \-L
instructs
.I lex
not to generate
.B #line
directives.  Without this option,
.I lex
peppers the generated scanner
with #line directives so error messages in the actions will be correctly
located with respect to the original
.I lex
input file, and not to
the fairly meaningless line numbers of
.B lex.yy.c.
(Unfortunately
.I lex
does not presently generate the necessary directives
to "retarget" the line numbers for those parts of
.B lex.yy.c
which it generated.  So if there is an error in the generated code,
a meaningless line number is reported.)
.TP
.B \-T
makes
.I lex
run in
.I trace
mode.  It will generate a lot of messages to
.I stderr
concerning
the form of the input and the resultant non-deterministic and deterministic
finite automata.  This option is mostly for use in maintaining
.I lex.
.TP
.B \-V
prints the version number to
.I stderr
and exits.
.TP
.B \-7
instructs
.I lex
to generate a 7-bit scanner, i.e., one which can only recognized 7-bit
characters in its input.  The advantage of using
.B \-7
is that the scanner's tables can be up to half the size of those generated
using the
.B \-8
option (see below).  The disadvantage is that such scanners often hang
or crash if their input contains an 8-bit character.
.IP
Note, however, that unless you generate your scanner using the
.B \-Cf
or
.B \-CF
table compression options, use of
.B \-7
will save only a small amount of table space, and make your scanner
considerably less portable.
.I lex's
default behavior is to generate an 8-bit scanner unless you use the
.B \-Cf
or
.B \-CF,
in which case
.I lex
defaults to generating 7-bit scanners unless your site was always
configured to generate 8-bit scanners (as will often be the case
with non-USA sites).  You can tell whether lex generated a 7-bit
or an 8-bit scanner by inspecting the flag summary in the
.B \-v
output as described above.
.IP
Note that if you use
.B \-Cfe
or
.B \-CFe
(those table compression options, but also using equivalence classes as
discussed see below), lex still defaults to generating an 8-bit
scanner, since usually with these compression options full 8-bit tables
are not much more expensive than 7-bit tables.
.TP
.B \-8
instructs
.I lex
to generate an 8-bit scanner, i.e., one which can recognize 8-bit
characters.  This flag is only needed for scanners generated using
.B \-Cf
or
.B \-CF,
as otherwise lex defaults to generating an 8-bit scanner anyway.
.IP
See the discussion of
.B \-7
above for lex's default behavior and the tradeoffs between 7-bit
and 8-bit scanners.
.TP 
.B \-C[aefFmr]
controls the degree of table compression and, more generally, trade-offs
between small scanners and fast scanners.
.IP
.B \-Ca
("align") instructs lex to trade off larger tables in the
generated scanner for faster performance because the elements of
the tables are better aligned for memory access and computation.  On some
RISC architectures, fetching and manipulating longwords is more efficient
than with smaller-sized datums such as shortwords.  This option can
double the size of the tables used by your scanner.
.IP
.B \-Ce
directs
.I lex
to construct
.I equivalence classes,
i.e., sets of characters
which have identical lexical properties (for example, if the only
appearance of digits in the
.I lex
input is in the character class
"[0-9]" then the digits '0', '1', ..., '9' will all be put
in the same equivalence class).  Equivalence classes usually give
dramatic reductions in the final table/object file sizes (typically
a factor of 2-5) and are pretty cheap performance-wise (one array
look-up per character scanned).
.IP
.B \-Cf
specifies that the
.I full
scanner tables should be generated -
.I lex
should not compress the
tables by taking advantages of similar transition functions for
different states.
.IP
.B \-CF
specifies that the alternate fast scanner representation (described
above under the
.B \-F
flag)
should be used.
.IP
.B \-Cm
directs
.I lex
to construct
.I meta-equivalence classes,
which are sets of equivalence classes (or characters, if equivalence
classes are not being used) that are commonly used together.  Meta-equivalence
classes are often a big win when using compressed tables, but they
have a moderate performance impact (one or two "if" tests and one
array look-up per character scanned).
.IP
.B \-Cr
causes the generated scanner to
.I bypass
use of the standard I/O library (stdio) for input.  Instead of calling
.B fread()
or
.B getc(),
the scanner will use the
.B read()
system call, resulting in a performance gain which varies from system
to system, but in general is probably negligible unless you are also using
.B \-Cf
or
.B \-CF.
Using
.B \-Cr
can cause strange behavior if, for example, you read from
.I yyin
using stdio prior to calling the scanner (because the scanner will miss
whatever text your previous reads left in the stdio input buffer).
.IP
.B \-Cr
has no effect if you define
.B YY_INPUT
(see The Generated Scanner above).
.IP
A lone
.B \-C
specifies that the scanner tables should be compressed but neither
equivalence classes nor meta-equivalence classes should be used.
.IP
The options
.B \-Cf
or
.B \-CF
and
.B \-Cm
do not make sense together - there is no opportunity for meta-equivalence
classes if the table is not being compressed.  Otherwise the options
may be freely mixed, and are cumulative.
.IP
The default setting is
.B \-Cem,
which specifies that
.I lex
should generate equivalence classes
and meta-equivalence classes.  This setting provides the highest
degree of table compression.  You can trade off
faster-executing scanners at the cost of larger tables with
the following generally being true:
.nf

    slowest & smallest
          -Cem
          -Cm
          -Ce
          -C
          -C{f,F}e
          -C{f,F}
          -C{f,F}a
    fastest & largest

.fi
Note that scanners with the smallest tables are usually generated and
compiled the quickest, so
during development you will usually want to use the default, maximal
compression.
.IP
.B \-Cfe
is often a good compromise between speed and size for production
scanners.
.TP
.B \-Pprefix
changes the default
.I "yy"
prefix used by
.I lex
for all globally-visible variable and function names to instead be
.I prefix.
For example,
.B \-Pfoo
changes the name of
.B yytext
to
.B footext.
It also changes the name of the default output file from
.B lex.yy.c
to