Command-line Options

You can call flex with the following command-line options:

-b

Generate backtracking information to `lex.backtrack'. This is a list of scanner states which require backtracking and the input characters on which they do so. By adding rules one can remove backtracking states. If all backtracking states are eliminated and `-f' or `-F' is used, the generated scanner will run faster (see the `-p' flag). Only users who wish to squeeze every last cycle out of their scanners need worry about this option. (See section Performance Considerations.)

-c

is a do-nothing, deprecated option included for POSIX compliance. Note: in previous releases of flex, you could use `-c' to specify table-compression options. This functionality is now given by the `-C' flag. To ease the the impact of this change, when flex encounters `-c', it currently issues a warning message and assumes that `-C' was desired instead. In the future this "promotion" of `-c' to `-C' will go away in the name of full POSIX compliance (unless the POSIX meaning is removed first).

-d

makes the generated scanner run in debug mode. Whenever a pattern is recognized and the global yy_flex_debug is non-zero (which is the default), the scanner will write to `stderr' a line of the form:

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

The line number refers to the location of the rule in the file defining the scanner (i.e., the file that was fed to flex). Messages are also generated when the scanner backtracks, 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.

-f

specifies (take your pick) full table or fast scanner. No table compression is done. The result is large but fast. This option is equivalent to `-Cf' (see below).

-i

instructs flex to generate a case-insensitive scanner. The case of letters given in the flex input patterns will be ignored, and tokens in the input will be matched regardless of case. The matched text given in yytext will have the preserved case (i.e., it will not be folded).

-n

is another do-nothing, deprecated option included only for POSIX compliance.

-p

generates a performance report to `stderr'. The report consists of comments regarding features of the flex input file which will cause a loss of performance in the resulting scanner. Note that the use of REJECT and variable trailing context (see section Deficiencies and Bugs) entails a substantial performance penalty; use of yymore, the `^' operator, and the `-I' flag entail minor performance penalties.

-s

causes the default rule (that unmatched scanner input is echoed to `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.

-t

instructs flex to write the scanner it generates to standard output instead of `lex.yy.c'.

-v

specifies that flex should write to `stderr' a summary of statistics regarding the scanner it generates. Most of the statistics are meaningless to the casual flex user, but the first line identifies the version of flex, which is useful for figuring out where you stand with respect to patches and new releases, and the next two lines give the date when the scanner was created and a summary of the flags which were in effect.

-F

specifies that the fast scanner table representation should be used. This representation is about as fast as the full table representation (`-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:

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

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 `-F'. This option is equivalent to `-CF' (see below).

-I

instructs flex to generate an interactive scanner. Normally, scanners generated by flex always look ahead one character before deciding that a rule has been matched. At the cost of some scanning overhead, flex will generate a scanner which only looks ahead when needed. Such scanners are called interactive because if you want to write a scanner for an interactive system such as a command shell, you will probably want the user's input to be terminated with a newline, and without `-I' the user will have to type a character in addition to the newline in order to have the newline recognized. This leads to dreadful interactive performance. If all this seems too confusing, here's the general rule: if a human will be typing in input to your scanner, use `-I', otherwise don't; if you don't care about squeezing the utmost performance from your scanner and you don't want to make any assumptions about the input to your scanner, use `-I'. Note: `-I' cannot be used in conjunction with full or fast tables, i.e., the `-f', `-F', `-Cf', or `-CF' flags.

-L

instructs flex not to generate #line directives. Without this option, flex peppers the generated scanner with #line directives so error messages in the actions will be correctly located with respect to the original flex input file, and not to the fairly meaningless line numbers of `lex.yy.c'. (Unfortunately flex does not presently generate the necessary directives to "retarget" the line numbers for those parts of `lex.yy.c' which it generated. So if there is an error in the generated code, a meaningless line number is reported.)

-T

makes flex run in trace mode. It will generate a lot of messages to `stdout' concerning the form of the input and the resultant non-deterministic and deterministic finite automata. This option is mostly for use in maintaining flex.

-8

instructs flex to generate an 8-bit scanner, i.e., one which can recognize 8-bit characters. On some sites, flex is installed with this option as the default. On others, the default is 7-bit characters. To see which is the case, check the verbose (`-v') output for `equivalence classes created'. If the denominator of the number shown is 128, then by default flex is generating 7-bit characters. If it is 256, then the default is 8-bit characters and the `-8' flag is not required (but may be a good idea to keep the scanner specification portable). Feeding a 7-bit scanner 8-bit characters will result in infinite loops, bus errors, or other such fireworks, so when in doubt, use the flag. Note that if equivalence classes are used, 8-bit scanners take only slightly more table space than 7-bit scanners (128 bytes, to be exact); if equivalence classes are not used, however, then the tables may grow up to twice their 7-bit size.

-C[efmF]

controls the degree of table compression. `-Ce' directs flex to construct equivalence classes, i.e., sets of characters which have identical lexical properties (for example, if the only appearance of digits in the flex 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). `-Cf' specifies that the full scanner tables should be generated; flex will not compress the tables by taking advantages of similar transition functions for different states. `-CF' specifies that the alternate fast scanner representation (described above under the `-F' flag) should be used. `-Cm' directs flex to construct 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). A lone `-C' specifies that the scanner tables should be compressed, but flex is not to use either equivalence classes nor meta-equivalence classes. The options `-Cf' or `-CF' and `-Cm' do not make sense together. There is no opportunity for meta-equivalence classes if the table is not compressed. Otherwise the options may be freely mixed. The default setting is `-Cem', which specifies that flex 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:

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

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. `-Cfe' is often a good compromise between speed and size for production scanners. `-C' options are not cumulative; whenever the flag is encountered, the previous `-C' settings are forgotten.

-Sskeleton_file

overrides the default skeleton file from which flex constructs its scanners. You'll never need this option unless you are doing flex maintenance or development.