From f9bd1cfebc0dc7ac9e879cd17feb04e1be51f3a7 Mon Sep 17 00:00:00 2001 From: Vern Paxson Date: Wed, 28 Feb 1990 16:59:42 +0000 Subject: [PATCH] Changed .so options.man to inlined version since flex.1 will have a different (shorter) options description. --- flex.1 | 347 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 346 insertions(+), 1 deletion(-) diff --git a/flex.1 b/flex.1 index 6357f27..a4808b4 100644 --- a/flex.1 +++ b/flex.1 @@ -1134,7 +1134,352 @@ automatically generates take care of virtually all the instances 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 -- 2.40.0