when one might consider using
.B %t.
But what the hell, it's there if you want it.
-.so options.man
+.SH OPTIONS
+.I flex
+has the following options:
+.TP
+.B -b
+Generate backtracking information to
+.I 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
+.B -f
+or
+.B -F
+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 flex
+.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 flex
+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 the scanner will
+write to
+.I stderr
+a line of the form:
+.nf
+
+ --accepting rule #n ("the matched text")
+
+.fi
+Rules are numbered sequentially with the first one being 1. Rule #0
+is executed when the scanner backtracks; Rule #(n+1) (where
+.I n
+is the number of rules in the
+.I flex
+input) indicates the default action; Rule #(n+2) indicates
+that the input buffer is empty and needs to be refilled and then the scan
+restarted. Rules beyond (n+2) are end-of-file actions.
+.TP
+.B -f
+specifies (take your pick)
+.I full table
+or
+.I fast scanner.
+No table compression is done. The result is large but fast.
+This option is equivalent to
+.B -Cf
+(see below).
+.TP
+.B -i
+instructs
+.I flex
+to generate a
+.I case-insensitive
+scanner. The case of letters given in the
+.I flex
+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 -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 flex
+input file which will cause a loss of performance in the resulting scanner.
+Note that the use of
+.I REJECT
+and variable trailing context (see the BUGS section below)
+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 flex
+to write the scanner it generates to standard output instead
+of
+.B lex.yy.c.
+.TP
+.B -v
+specifies that
+.I flex
+should write to
+.I stderr
+a summary of statistics regarding the scanner it generates.
+Most of the statistics are meaningless to the casual
+.I flex
+user, but the
+first line identifies the version of
+.I flex,
+which is useful for figuring
+out where you stand with respect to patches and new releases.
+.TP
+.B -F
+specifies that the
+.ul
+fast
+scanner table representation should be used. This representation is
+about as fast as the full table representation
+.ul
+(-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
+.ul
+-F.
+.IP
+This option is equivalent to
+.B -CF
+(see below).
+.TP
+.B -I
+instructs
+.I flex
+to generate an
+.I interactive
+scanner. Normally, scanners generated by
+.I flex
+always look ahead one
+character before deciding that a rule has been matched. At the cost of
+some scanning overhead,
+.I flex
+will generate a scanner which only looks ahead
+when needed. Such scanners are called
+.I 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
+.B -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.
+.IP
+If all this seems to confusing, here's the general rule: if a human will
+be typing in input to your scanner, use
+.B -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
+.B -I.
+.IP
+Note,
+.B -I
+cannot be used in conjunction with
+.I full
+or
+.I fast tables,
+i.e., the
+.B -f, -F, -Cf,
+or
+.B -CF
+flags.
+.TP
+.B -L
+instructs
+.I flex
+not to generate
+.B #line
+directives. Without this option,
+.I flex
+peppers the generated scanner
+with #line directives so error messages in the actions will be correctly
+located with respect to the original
+.I flex
+input file, and not to
+the fairly meaningless line numbers of
+.B lex.yy.c.
+(Unfortunately
+.I flex
+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 flex
+run in
+.I trace
+mode. It will generate a lot of messages to
+.I stdout
+concerning
+the form of the input and the resultant non-deterministic and deterministic
+finite automata. This option is mostly for use in maintaining
+.I flex.
+.TP
+.B -C[efmF]
+controls the degree of table compression.
+.IP
+.B -Ce
+directs
+.I flex
+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 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).
+.IP
+.B -Cf
+specifies that the
+.I full
+scanner tables should be generated -
+.I flex
+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 flex
+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
+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.
+.IP
+The default setting is
+.B -Cem,
+which specifies that
+.I 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:
+.nf
+
+ slowest & smallest
+ -Cem
+ -Cm
+ -Ce
+ -C
+ -C{f,F}e
+ -C{f,F}
+ 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.
+.IP
+.B -C
+options are not cumulative; whenever the flag is encountered, the
+previous -C settings are forgotten.
+.TP
+.B -Sskeleton_file
+overrides the default skeleton file from which
+.I flex
+constructs its scanners. You'll never need this option unless you are doing
+.I flex
+maintenance or development.
.SH PERFORMANCE CONSIDERATIONS
The main design goal of
.I flex
projects / flex / commitdiff