This commit was manufactured by cvs2svn to create tag 'FreeBSD-release/1.0'.
[unix-history] / usr.bin / lex / lex.1
index c67df0a..685d3da 100644 (file)
-.\" Copyright (c) 1990 The Regents of the University of California.
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"    This product includes software developed by the University of
-.\"    California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"    without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\"    @(#)lex.1       5.13 (Berkeley) 7/24/91
-.\"
-.Dd July 24, 1991
-.Dt LEX 1
-.Os
-.Sh NAME
-.Nm lex
-.Nd fast lexical analyzer generator
-.Sh SYNOPSIS
-.Nm lex
-.Oo
-.Op Fl bcdfinpstvFILT8
-.Fl C Ns Ns Op Cm efmF
-.Fl S Ns Ns Ar skeleton
-.Oc
-.Op Ar
-.Sh DESCRIPTION
-.Nm Lex
+.TH FLEX 1 "26 May 1990" "Version 2.3"
+.SH NAME
+flex - fast lexical analyzer generator
+.SH SYNOPSIS
+.B flex
+.B [-bcdfinpstvFILT8 -C[efmF] -Sskeleton]
+.I [filename ...]
+.SH DESCRIPTION
+.I flex
 is a tool for generating
 is a tool for generating
-.Ar scanners :
+.I scanners:
 programs which recognized lexical patterns in text.
 programs which recognized lexical patterns in text.
-.Nm Lex
+.I flex
 reads
 the given input files, or its standard input if no file names are given,
 for a description of a scanner to generate.  The description is in
 the form of pairs
 of regular expressions and C code, called
 reads
 the given input files, or its standard input if no file names are given,
 for a description of a scanner to generate.  The description is in
 the form of pairs
 of regular expressions and C code, called
-.Em rules .
-.Nm Lex
+.I rules.  flex
 generates as output a C source file,
 generates as output a C source file,
-.Pa lex.yy.c ,
+.B lex.yy.c,
 which defines a routine
 which defines a routine
-.Fn yylex .
+.B yylex().
 This file is compiled and linked with the
 This file is compiled and linked with the
-.Fl lfl
+.B -lfl
 library to produce an executable.  When the executable is run,
 it analyzes its input for occurrences
 of the regular expressions.  Whenever it finds one, it executes
 the corresponding C code.
 library to produce an executable.  When the executable is run,
 it analyzes its input for occurrences
 of the regular expressions.  Whenever it finds one, it executes
 the corresponding C code.
-.Pp
+.LP
 For full documentation, see
 For full documentation, see
-.Em Lexdoc .
+.B flexdoc(1).
 This manual entry is intended for use as a quick reference.
 This manual entry is intended for use as a quick reference.
-.Sh OPTIONS
-.Nm Lex
+.SH OPTIONS
+.I flex
 has the following options:
 has the following options:
-.Bl -tag -width Ds
-.It Fl b
+.TP
+.B -b
 Generate backtracking information to
 Generate backtracking information to
-.Va lex.backtrack .
+.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
 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
-.Fl f
+.B -f
 or
 or
-.Fl F
+.B -F
 is used, the generated scanner will run faster.
 is used, the generated scanner will run faster.
-.It Fl c
-is a do-nothing, deprecated option included for
-.Tn POSIX
-compliance.
-.Pp
-.Ar NOTE :
+.TP
+.B -c
+is a do-nothing, deprecated option included for POSIX compliance.
+.IP
+.B NOTE:
 in previous releases of
 in previous releases of
-.Nm Lex
-.Op Fl c
+.I flex
+.B -c
 specified table-compression options.  This functionality is
 now given by the
 specified table-compression options.  This functionality is
 now given by the
-.Fl C
+.B -C
 flag.  To ease the the impact of this change, when
 flag.  To ease the the impact of this change, when
-.Nm lex
+.I flex
 encounters
 encounters
-.Fl c,
+.B -c,
 it currently issues a warning message and assumes that
 it currently issues a warning message and assumes that
-.Fl C
+.B -C
 was desired instead.  In the future this "promotion" of
 was desired instead.  In the future this "promotion" of
-.Fl c
+.B -c
 to
 to
-.Fl C
-will go away in the name of full
-.Tn POSIX
-compliance (unless
-the
-.Tn POSIX
-meaning is removed first).
-.It Fl d
-Makes the generated scanner run in
-.Ar debug
+.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
 mode.  Whenever a pattern is recognized and the global
-.Va yy_Lex_debug
+.B yy_flex_debug
 is non-zero (which is the default), the scanner will
 write to
 is non-zero (which is the default), the scanner will
 write to
-.Li stderr
+.I stderr
 a line of the form:
 a line of the form:
-.Pp
-.Dl --accepting rule at line 53 ("the matched text")
-.Pp
+.nf
+
+    --accepting rule at line 53 ("the matched text")
+
+.fi
 The line number refers to the location of the rule in the file
 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
+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
 are also generated when the scanner backtracks, accepts the
 default rule, reaches the end of its input buffer (or encounters
-a
-.Tn NUL ;
-the two look the same as far as the scanner's concerned),
+a NUL; the two look the same as far as the scanner's concerned),
 or reaches an end-of-file.
 or reaches an end-of-file.
-.It Fl f
-Specifies (take your pick)
-.Em full table
+.TP
+.B -f
+specifies (take your pick)
+.I full table
 or
 or
-.Em fast scanner .
+.I fast scanner.
 No table compression is done.  The result is large but fast.
 This option is equivalent to
 No table compression is done.  The result is large but fast.
 This option is equivalent to
-.Fl Cf
+.B -Cf
 (see below).
 (see below).
-.It Fl i
-Instructs
-.Nm lex
+.TP
+.B -i
+instructs
+.I flex
 to generate a
 to generate a
-.Em case-insensitive
+.I case-insensitive
 scanner.  The case of letters given in the
 scanner.  The case of letters given in the
-.Nm lex
+.I flex
 input patterns will
 be ignored, and tokens in the input will be matched regardless of case.  The
 matched text given in
 input patterns will
 be ignored, and tokens in the input will be matched regardless of case.  The
 matched text given in
-.Va yytext
+.I yytext
 will have the preserved case (i.e., it will not be folded).
 will have the preserved case (i.e., it will not be folded).
-.It Fl n
-Is another do-nothing, deprecated option included only for
-.Tn POSIX
-compliance.
-.It Fl p
-Generates a performance report to stderr.  The report
+.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
 consists of comments regarding features of the
-.Nm lex
+.I flex
 input file which will cause a loss of performance in the resulting scanner.
 input file which will cause a loss of performance in the resulting scanner.
-.It Fl s
-Causes the
-.Ar default rule
+.TP
+.B -s
+causes the
+.I default rule
 (that unmatched scanner input is echoed to
 (that unmatched scanner input is echoed to
-.Ar stdout )
+.I stdout)
 to be suppressed.  If the scanner encounters input that does not
 match any of its rules, it aborts with an error.
 to be suppressed.  If the scanner encounters input that does not
 match any of its rules, it aborts with an error.
-.It Fl t
-Instructs
-.Nm lex
+.TP
+.B -t
+instructs
+.I flex
 to write the scanner it generates to standard output instead
 of
 to write the scanner it generates to standard output instead
 of
-.Pa lex.yy.c .
-.It Fl v
-Specifies that
-.Nm lex
+.B lex.yy.c.
+.TP
+.B -v
+specifies that
+.I flex
 should write to
 should write to
-.Li stderr
+.I stderr
 a summary of statistics regarding the scanner it generates.
 a summary of statistics regarding the scanner it generates.
-.It Fl F
-Specifies that the
-.Em fast
+.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
 scanner table representation should be used.  This representation is
 about as fast as the full table representation
-.Pq Fl f ,
+.ul
+(-f),
 and for some sets of patterns will be considerably smaller (and for
 others, larger).  See
 and for some sets of patterns will be considerably smaller (and for
 others, larger).  See
-.Em Lexdoc
+.B flexdoc(1)
 for details.
 for details.
-.Pp
+.IP
 This option is equivalent to
 This option is equivalent to
-.Fl CF
+.B -CF
 (see below).
 (see below).
-.It Fl I
-Instructs
-.Nm lex
+.TP
+.B -I
+instructs
+.I flex
 to generate an
 to generate an
-.Em interactive
+.I interactive
 scanner, that is, a scanner which stops immediately rather than
 looking ahead if it knows
 that the currently scanned text cannot be part of a longer rule's match.
 Again, see
 scanner, that is, a scanner which stops immediately rather than
 looking ahead if it knows
 that the currently scanned text cannot be part of a longer rule's match.
 Again, see
-.Em Lexdoc
+.B flexdoc(1)
 for details.
 for details.
-.Pp
+.IP
 Note,
 Note,
-.Fl I
+.B -I
 cannot be used in conjunction with
 cannot be used in conjunction with
-.Em full
+.I full
 or
 or
-.Em fast tables ,
+.I fast tables,
 i.e., the
 i.e., the
-.Fl f , F , Cf ,
+.B -f, -F, -Cf,
 or
 or
-.Fl CF
+.B -CF
 flags.
 flags.
-.It Fl L
-Instructs
-.Nm lex
+.TP
+.B -L
+instructs
+.I flex
 not to generate
 not to generate
-.Li #line
+.B #line
 directives in
 directives in
-.Pa lex.yy.c .
+.B lex.yy.c.
 The default is to generate such directives so error
 messages in the actions will be correctly
 located with respect to the original
 The default is to generate such directives so error
 messages in the actions will be correctly
 located with respect to the original
-.Nm lex
+.I flex
 input file, and not to
 the fairly meaningless line numbers of
 input file, and not to
 the fairly meaningless line numbers of
-.Pa lex.yy.c .
-.It Fl T
-Makes
-.Nm lex
+.B lex.yy.c.
+.TP
+.B -T
+makes
+.I flex
 run in
 run in
-.Em trace
+.I trace
 mode.  It will generate a lot of messages to
 mode.  It will generate a lot of messages to
-.Li stdout
+.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
 concerning
 the form of the input and the resultant non-deterministic and deterministic
 finite automata.  This option is mostly for use in maintaining
-.Nm lex .
-.It Fl 8
-Instructs
-.Nm lex
+.I flex.
+.TP
+.B -8
+instructs
+.I flex
 to generate an 8-bit scanner.
 On some sites, this is the default.  On others, the default
 is 7-bit characters.  To see which is the case, check the verbose
 to generate an 8-bit scanner.
 On some sites, this is the default.  On others, the default
 is 7-bit characters.  To see which is the case, check the verbose
-.Pq Fl v
+.B (-v)
 output for "equivalence classes created".  If the denominator of
 the number shown is 128, then by default
 output for "equivalence classes created".  If the denominator of
 the number shown is 128, then by default
-.Nm lex
+.I flex
 is generating 7-bit characters.  If it is 256, then the default is
 8-bit characters.
 is generating 7-bit characters.  If it is 256, then the default is
 8-bit characters.
-.It Fl C Ns Op Cm efmF
-Controls the degree of table compression. The default setting is
-.Fl Cem .
-.Pp
-.Bl -tag -width Ds
-.It Fl C
-A lone
-.Fl C
-specifies that the scanner tables should be compressed but neither
-equivalence classes nor meta-equivalence classes should be used.
-.It Fl \&Ce
-Directs
-.Nm lex
+.TP 
+.B -C[efmF]
+controls the degree of table compression.
+.IP
+.B -Ce
+directs
+.I flex
 to construct
 to construct
-.Em equivalence classes ,
+.I equivalence classes,
 i.e., sets of characters
 which have identical lexical properties.
 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).
 i.e., sets of characters
 which have identical lexical properties.
 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).
-.It Fl \&Cf
-Specifies that the
-.Em full
+.IP
+.B -Cf
+specifies that the
+.I full
 scanner tables should be generated -
 scanner tables should be generated -
-.Nm lex
+.I flex
 should not compress the
 tables by taking advantages of similar transition functions for
 different states.
 should not compress the
 tables by taking advantages of similar transition functions for
 different states.
-.It Fl \&CF
-Specifies that the alternate fast scanner representation (described in
-.Em Lexdoc )
+.IP
+.B -CF
+specifies that the alternate fast scanner representation (described in
+.B flexdoc(1))
 should be used.
 should be used.
-.It Fl \&Cm
-Directs
-.Nm lex
+.IP
+.B -Cm
+directs
+.I flex
 to construct
 to construct
-.Em meta-equivalence classes ,
+.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).
 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).
-.It Fl Cem
-(Default)
-Generate both equivalence classes
-and meta-equivalence classes.  This setting provides the highest
-degree of table compression.
-.El
-.Pp
-Faster-executing scanners can be traded off at the
-cost of larger tables with
-the following generally being true:
-.Bd -ragged -offset center
-slowest & smallest
-      -Cem
-      -Cm
-      -Ce
-      -C
-      -C{f,F}e
-      -C{f,F}
-fastest & largest
-.Ed
-.Pp
-.Fl C
-options are not cumulative; whenever the flag is encountered, the
-previous -C settings are forgotten.
-.Pp
+.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
 The options
-.Fl \&Cf
+.B -Cf
 or
 or
-.Fl \&CF
+.B -CF
 and
 and
-.Fl \&Cm
+.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.
 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.
-.It Fl S Ns Ar skeleton_file
-Overrides the default skeleton file from which
-.Nm lex
-constructs its scanners.  Useful for
-.Nm lex
+.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
+.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.
 maintenance or development.
-.El
-.Sh SUMMARY OF LEX REGULAR EXPRESSIONS
+.SH SUMMARY OF FLEX REGULAR EXPRESSIONS
 The patterns in the input are written using an extended set of regular
 expressions.  These are:
 The patterns in the input are written using an extended set of regular
 expressions.  These are:
-.Pp
-.Bl -tag -width 10n -compact
-.It Li x
-Match the character 'x'.
-.It Li \&.
-Any character except newline.
-.It Op Li xyz
-A "character class"; in this case, the pattern
-matches either an 'x', a 'y', or a 'z'.
-.It Op Li abj-oZ
-A "character class" with a range in it; matches
-an 'a', a 'b', any letter from 'j' through 'o',
-or a 'Z'.
-.It Op Li ^A-Z
-A "negated character class", i.e., any character
-but those in the class.  In this case, any
-character
-.Em except
-an uppercase letter.
-.It Op Li ^A-Z\en
-Any character
-.Em except
-an uppercase letter or
-a newline.
-.It Li r*
-Zero or more r's, where r is any regular expression.
-.It Li r+
-One or more r's.
-.It Li r?
-Zero or one r's (that is, "an optional r").
-.It Li r{2,5}
-Anywhere from two to five r's.
-.It Li r{2,}
-Two or more r's.
-.It Li r{4}
-Exactly 4 r's.
-.It Li {name}
-The expansion of the "name" definition
-(see above).
-.It Xo
-.Oo Li xyz Oc Ns Li "\e\&\*qfoo"
-.Xc
-The literal string:
-[xyz]\*qfoo.
-.It Li \&\eX
-If X is an 'a', 'b', 'f', 'n', 'r', 't', or 'v',
-then the
-.Tn ANSI-C
-interpretation of \ex.
-Otherwise, a literal 'X' (used to escape
-operators such as '*').
-.It Li \&\e123
-The character with octal value 123.
-.It Li \&\ex2a
-The character with hexadecimal value 2a.
-.It Li (r)
-Match an r; parentheses are used to override
-precedence (see below).
-.It Li rs
-The regular expression r followed by the
-regular expression s; called "concatenation".
-.It Li rs
-Either an r or an s.
-.It Li r/s
-An r but only if it is followed by an s.  The
-s is not part of the matched text.  This type
-of pattern is called as "trailing context".
-.It Li \&^r
-An r, but only at the beginning of a line.
-.It Li r$
-An r, but only at the end of a line.  Equivalent
-to "r/\en".
-.It Li <s>r
-An r, but only in start condition s (see
-below for discussion of start conditions).
-.It Li <s1,s2,s3>r
-Same, but in any of start conditions s1,
-s2, or s3.
-.It Li <<EOF>>
-An end-of-file.
-.It Li <s1,s2><<EOF>>
-An end-of-file when in start condition s1 or s2.
-.El
+.nf
+
+    x          match the character 'x'
+    .          any character except newline
+    [xyz]      a "character class"; in this case, the pattern
+                 matches either an 'x', a 'y', or a 'z'
+    [abj-oZ]   a "character class" with a range in it; matches
+                 an 'a', a 'b', any letter from 'j' through 'o',
+                 or a 'Z'
+    [^A-Z]     a "negated character class", i.e., any character
+                 but those in the class.  In this case, any
+                 character EXCEPT an uppercase letter.
+    [^A-Z\\n]   any character EXCEPT an uppercase letter or
+                 a newline
+    r*         zero or more r's, where r is any regular expression
+    r+         one or more r's
+    r?         zero or one r's (that is, "an optional r")
+    r{2,5}     anywhere from two to five r's
+    r{2,}      two or more r's
+    r{4}       exactly 4 r's
+    {name}     the expansion of the "name" definition
+               (see above)
+    "[xyz]\\"foo"
+               the literal string: [xyz]"foo
+    \\X         if X is an 'a', 'b', 'f', 'n', 'r', 't', or 'v',
+                 then the ANSI-C interpretation of \\x.
+                 Otherwise, a literal 'X' (used to escape
+                 operators such as '*')
+    \\123       the character with octal value 123
+    \\x2a       the character with hexadecimal value 2a
+    (r)        match an r; parentheses are used to override
+                 precedence (see below)
+
+
+    rs         the regular expression r followed by the
+                 regular expression s; called "concatenation"
+
+
+    r|s        either an r or an s
+
+
+    r/s        an r but only if it is followed by an s.  The
+                 s is not part of the matched text.  This type
+                 of pattern is called as "trailing context".
+    ^r         an r, but only at the beginning of a line
+    r$         an r, but only at the end of a line.  Equivalent
+                 to "r/\\n".
+
+
+    <s>r       an r, but only in start condition s (see
+               below for discussion of start conditions)
+    <s1,s2,s3>r
+               same, but in any of start conditions s1,
+               s2, or s3
+
+
+    <<EOF>>    an end-of-file
+    <s1,s2><<EOF>>
+               an end-of-file when in start condition s1 or s2
+
+.fi
 The regular expressions listed above are grouped according to
 precedence, from highest precedence at the top to lowest at the bottom.
 Those grouped together have equal precedence.
 The regular expressions listed above are grouped according to
 precedence, from highest precedence at the top to lowest at the bottom.
 Those grouped together have equal precedence.
-.Pp
+.LP
 Some notes on patterns:
 Some notes on patterns:
-.Pp
+.IP -
 Negated character classes
 Negated character classes
-.Ar match newlines
-unless "\en" (or an equivalent escape sequence) is one of the
+.I match newlines
+unless "\\n" (or an equivalent escape sequence) is one of the
 characters explicitly present in the negated character class
 characters explicitly present in the negated character class
-(e.g., " [^A-Z\en] ").
-.Pp
+(e.g., "[^A-Z\\n]").
+.IP -
 A rule can have at most one instance of trailing context (the '/' operator
 or the '$' operator).  The start condition, '^', and "<<EOF>>" patterns
 can only occur at the beginning of a pattern, and, as well as with '/' and '$',
 cannot be grouped inside parentheses.  The following are all illegal:
 A rule can have at most one instance of trailing context (the '/' operator
 or the '$' operator).  The start condition, '^', and "<<EOF>>" patterns
 can only occur at the beginning of a pattern, and, as well as with '/' and '$',
 cannot be grouped inside parentheses.  The following are all illegal:
-.Pp
-.Bd -literal -offset indent
-foo/bar$
-foo(bar$)
-foo^bar
-<sc1>foo<sc2>bar
-.Ed
-.Sh SUMMARY OF SPECIAL ACTIONS
+.nf
+
+    foo/bar$
+    foo|(bar$)
+    foo|^bar
+    <sc1>foo<sc2>bar
+
+.fi
+.SH SUMMARY OF SPECIAL ACTIONS
 In addition to arbitrary C code, the following can appear in actions:
 In addition to arbitrary C code, the following can appear in actions:
-.Bl -tag -width Fl
-.It Ic ECHO
-Copies
-.Va yytext
-to the scanner's output.
-.It Ic BEGIN
-Followed by the name of a start condition places the scanner in the
+.IP -
+.B ECHO
+copies yytext to the scanner's output.
+.IP -
+.B BEGIN
+followed by the name of a start condition places the scanner in the
 corresponding start condition.
 corresponding start condition.
-.It Ic REJECT
-Directs the scanner to proceed on to the "second best" rule which matched the
+.IP -
+.B REJECT
+directs the scanner to proceed on to the "second best" rule which matched the
 input (or a prefix of the input).
 input (or a prefix of the input).
-.Va yytext
+.B yytext
 and
 and
-.Va yyleng
+.B yyleng
 are set up appropriately.  Note that
 are set up appropriately.  Note that
-.Ic REJECT
+.B REJECT
 is a particularly expensive feature in terms scanner performance;
 if it is used in
 is a particularly expensive feature in terms scanner performance;
 if it is used in
-.Em any
+.I any
 of the scanner's actions it will slow down
 of the scanner's actions it will slow down
-.Em all
+.I all
 of the scanner's matching.  Furthermore,
 of the scanner's matching.  Furthermore,
-.Ic REJECT
+.B REJECT
 cannot be used with the
 cannot be used with the
-.Fl f
+.I -f
 or
 or
-.Fl F
+.I -F
 options.
 options.
-.Pp
+.IP
 Note also that unlike the other special actions,
 Note also that unlike the other special actions,
-.Ic REJECT
+.B REJECT
 is a
 is a
-.Em branch ;
+.I branch;
 code immediately following it in the action will
 code immediately following it in the action will
-.Em not
+.I not
 be executed.
 be executed.
-.It Fn yymore
+.IP -
+.B yymore()
 tells the scanner that the next time it matches a rule, the corresponding
 token should be
 tells the scanner that the next time it matches a rule, the corresponding
 token should be
-.Em appended
+.I appended
 onto the current value of
 onto the current value of
-.Va yytext
+.B yytext
 rather than replacing it.
 rather than replacing it.
-.It Fn yyless \&n
+.IP -
+.B yyless(n)
 returns all but the first
 returns all but the first
-.Ar n
+.I n
 characters of the current token back to the input stream, where they
 will be rescanned when the scanner looks for the next match.
 characters of the current token back to the input stream, where they
 will be rescanned when the scanner looks for the next match.
-.Va yytext
+.B yytext
 and
 and
-.Va yyleng
+.B yyleng
 are adjusted appropriately (e.g.,
 are adjusted appropriately (e.g.,
-.Va yyleng
+.B yyleng
 will now be equal to
 will now be equal to
-.Ar n ) .
-.It Fn unput c
+.I n
+).
+.IP -
+.B unput(c)
 puts the character
 puts the character
-.Ar c
+.I c
 back onto the input stream.  It will be the next character scanned.
 back onto the input stream.  It will be the next character scanned.
-.It Fn input
+.IP -
+.B input()
 reads the next character from the input stream (this routine is called
 reads the next character from the input stream (this routine is called
-.Fn yyinput
+.B yyinput()
 if the scanner is compiled using
 if the scanner is compiled using
-.Em C \&+\&+ ) .
-.It Fn yyterminate
+.B C++).
+.IP -
+.B yyterminate()
 can be used in lieu of a return statement in an action.  It terminates
 the scanner and returns a 0 to the scanner's caller, indicating "all done".
 can be used in lieu of a return statement in an action.  It terminates
 the scanner and returns a 0 to the scanner's caller, indicating "all done".
-.Pp
+.IP
 By default,
 By default,
-.Fn yyterminate
+.B yyterminate()
 is also called when an end-of-file is encountered.  It is a macro and
 may be redefined.
 is also called when an end-of-file is encountered.  It is a macro and
 may be redefined.
-.It Ic YY_NEW_FILE
+.IP -
+.B YY_NEW_FILE
 is an action available only in <<EOF>> rules.  It means "Okay, I've
 set up a new input file, continue scanning".
 is an action available only in <<EOF>> rules.  It means "Okay, I've
 set up a new input file, continue scanning".
-.It Fn yy_create_buffer file size
+.IP -
+.B yy_create_buffer( file, size )
 takes a
 takes a
-.Ic FILE
+.I FILE
 pointer and an integer
 pointer and an integer
-.Ar size .
+.I size.
 It returns a YY_BUFFER_STATE
 handle to a new input buffer large enough to accomodate
 It returns a YY_BUFFER_STATE
 handle to a new input buffer large enough to accomodate
-.Ar size
+.I size
 characters and associated with the given file.  When in doubt, use
 characters and associated with the given file.  When in doubt, use
-.Ar YY_BUF_SIZE
+.B YY_BUF_SIZE
 for the size.
 for the size.
-.It Fn yy_switch_to_buffer new_buffer
+.IP -
+.B yy_switch_to_buffer( new_buffer )
 switches the scanner's processing to scan for tokens from
 the given buffer, which must be a YY_BUFFER_STATE.
 switches the scanner's processing to scan for tokens from
 the given buffer, which must be a YY_BUFFER_STATE.
-.It Fn yy_delete_buffer buffer
+.IP -
+.B yy_delete_buffer( buffer )
 deletes the given buffer.
 deletes the given buffer.
-.El
-.Sh VALUES AVAILABLE TO THE USER
-.Bl -tag -width Fl
-.It Va char \&*yytext
+.SH VALUES AVAILABLE TO THE USER
+.IP -
+.B char *yytext
 holds the text of the current token.  It may not be modified.
 holds the text of the current token.  It may not be modified.
-.It Va int yyleng
+.IP -
+.B int yyleng
 holds the length of the current token.  It may not be modified.
 holds the length of the current token.  It may not be modified.
-.It Va FILE  \&*yyin
+.IP -
+.B FILE *yyin
 is the file which by default
 is the file which by default
-.Nm lex
+.I flex
 reads from.  It may be redefined but doing so only makes sense before
 scanning begins.  Changing it in the middle of scanning will have
 unexpected results since
 reads from.  It may be redefined but doing so only makes sense before
 scanning begins.  Changing it in the middle of scanning will have
 unexpected results since
-.Nm lex
+.I flex
 buffers its input.  Once scanning terminates because an end-of-file
 has been seen,
 buffers its input.  Once scanning terminates because an end-of-file
 has been seen,
-.Fn "void yyrestart" "FILE *new_file"
+.B
+void yyrestart( FILE *new_file )
 may be called to point
 may be called to point
-.Va yyin
+.I yyin
 at the new input file.
 at the new input file.
-.It Va FILE  \&*yyout
+.IP -
+.B FILE *yyout
 is the file to which
 is the file to which
-.Ar ECHO
+.B ECHO
 actions are done.  It can be reassigned by the user.
 actions are done.  It can be reassigned by the user.
-.It Va YY_CURRENT_BUFFER
+.IP -
+.B YY_CURRENT_BUFFER
 returns a
 returns a
-YY_BUFFER_STATE
+.B YY_BUFFER_STATE
 handle to the current buffer.
 handle to the current buffer.
-.El
-.Sh MACROS THE USER CAN REDEFINE
-.Bl -tag -width Fl
-.It Va YY_DECL
+.SH MACROS THE USER CAN REDEFINE
+.IP -
+.B YY_DECL
 controls how the scanning routine is declared.
 By default, it is "int yylex()", or, if prototypes are being
 used, "int yylex(void)".  This definition may be changed by redefining
 controls how the scanning routine is declared.
 By default, it is "int yylex()", or, if prototypes are being
 used, "int yylex(void)".  This definition may be changed by redefining
@@ -583,250 +547,235 @@ the "YY_DECL" macro.  Note that
 if you give arguments to the scanning routine using a
 K&R-style/non-prototyped function declaration, you must terminate
 the definition with a semi-colon (;).
 if you give arguments to the scanning routine using a
 K&R-style/non-prototyped function declaration, you must terminate
 the definition with a semi-colon (;).
-.It Va YY_INPUT
+.IP -
 The nature of how the scanner
 gets its input can be controlled by redefining the
 The nature of how the scanner
 gets its input can be controlled by redefining the
-YY_INPUT
+.B YY_INPUT
 macro.
 YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)".  Its
 action is to place up to
 macro.
 YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)".  Its
 action is to place up to
-.Ar max _size
+.I max_size
 characters in the character array
 characters in the character array
-.Ar buf
+.I buf
 and return in the integer variable
 and return in the integer variable
-.Ar result
+.I result
 either the
 number of characters read or the constant YY_NULL (0 on Unix systems)
 to indicate EOF.  The default YY_INPUT reads from the
 global file-pointer "yyin".
 A sample redefinition of YY_INPUT (in the definitions
 section of the input file):
 either the
 number of characters read or the constant YY_NULL (0 on Unix systems)
 to indicate EOF.  The default YY_INPUT reads from the
 global file-pointer "yyin".
 A sample redefinition of YY_INPUT (in the definitions
 section of the input file):
-.Bd -literal -offset indent
-%{
-#undef YY_INPUT
-#define YY_INPUT(buf,result,max_size) \e
-    result = ((buf[0] = getchar()) == EOF) ? YY_NULL : 1;
-%}
-.Ed
-.It Va YY_INPUT
+.nf
+
+    %{
+    #undef YY_INPUT
+    #define YY_INPUT(buf,result,max_size) \\
+        { \\
+        int c = getchar(); \\
+        result = (c == EOF) ? YY_NULL : (buf[0] = c, 1); \\
+        }
+    %}
+
+.fi
+.IP -
 When the scanner receives an end-of-file indication from YY_INPUT,
 it then checks the
 When the scanner receives an end-of-file indication from YY_INPUT,
 it then checks the
-.Fn yywrap
+.B yywrap()
 function.  If
 function.  If
-.Fn yywrap
+.B yywrap()
 returns false (zero), then it is assumed that the
 function has gone ahead and set up
 returns false (zero), then it is assumed that the
 function has gone ahead and set up
-.Va yyin
+.I yyin
 to point to another input file, and scanning continues.  If it returns
 true (non-zero), then the scanner terminates, returning 0 to its
 caller.
 to point to another input file, and scanning continues.  If it returns
 true (non-zero), then the scanner terminates, returning 0 to its
 caller.
-.It Va yywrap
+.IP
 The default
 The default
-.Fn yywrap
+.B yywrap()
 always returns 1.  Presently, to redefine it you must first
 "#undef yywrap", as it is currently implemented as a macro.  It is
 likely that
 always returns 1.  Presently, to redefine it you must first
 "#undef yywrap", as it is currently implemented as a macro.  It is
 likely that
-.Fn yywrap
+.B yywrap()
 will soon be defined to be a function rather than a macro.
 will soon be defined to be a function rather than a macro.
-.It Va YY_USER_ACTION
+.IP -
+YY_USER_ACTION
 can be redefined to provide an action
 which is always executed prior to the matched rule's action.
 can be redefined to provide an action
 which is always executed prior to the matched rule's action.
-.It Va YY_USER_INIT
+.IP -
 The macro
 The macro
-.Va YY _USER_INIT
+.B YY_USER_INIT
 may be redefined to provide an action which is always executed before
 the first scan.
 may be redefined to provide an action which is always executed before
 the first scan.
-.It Va YY_BREAK
+.IP -
 In the generated scanner, the actions are all gathered in one large
 switch statement and separated using
 In the generated scanner, the actions are all gathered in one large
 switch statement and separated using
-.Va YY _BREAK ,
+.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.
 which may be redefined.  By default, it is simply a "break", to separate
 each rule's action from the following rule's.
-.El
-.Sh FILES
-.Bl -tag -width lex.backtrack -compact
-.It Pa lex.skel
+.SH FILES
+.TP
+.I lex.skel
 skeleton scanner.
 skeleton scanner.
-.It Pa lex.yy.c
-generated scanner
-(called
-.Pa lexyy.c
+.TP
+.I lex.yy.c
+generated scanner (called
+.I lexyy.c
 on some systems).
 on some systems).
-.It Pa lex.backtrack
+.TP
+.I lex.backtrack
 backtracking information for
 backtracking information for
-.Fl b
-.It Pa flag
-(called
-.Pa lex.bck
+.B -b
+flag (called
+.I lex.bck
 on some systems).
 on some systems).
-.El
-.Sh SEE ALSO
-.Xr lex 1 ,
-.Xr yacc 1 ,
-.Xr sed 1 ,
-.Xr awk 1 .
-.Rs
-.%T "lexdoc"
-.Re
-.Rs
-.%A M. E. Lesk
-.%A E. Schmidt
-.%T "LEX \- Lexical Analyzer Generator"
-.Re
-.Sh DIAGNOSTICS
-.Bl -tag -width Fl
-.It Li reject_used_but_not_detected undefined
+.TP
+.B -lfl
+library with which to link the scanners.
+.SH "SEE ALSO"
+.LP
+flexdoc(1), lex(1), yacc(1), sed(1), awk(1).
+.LP
+M. E. Lesk and E. Schmidt,
+.I LEX - Lexical Analyzer Generator
+.SH DIAGNOSTICS
+.I reject_used_but_not_detected undefined
 or
 or
-.It Li yymore_used_but_not_detected undefined
-These errors can occur at compile time.
-They indicate that the
+.LP
+.I yymore_used_but_not_detected undefined -
+These errors can occur at compile time.  They indicate that the
 scanner uses
 scanner uses
-.Ic REJECT
+.B REJECT
 or
 or
-.Fn yymore
+.B yymore()
 but that
 but that
-.Nm lex
-failed to notice the fact,
-meaning that
-.Nm lex
+.I flex
+failed to notice the fact, meaning that
+.I flex
 scanned the first two sections looking for occurrences of these actions
 scanned the first two sections looking for occurrences of these actions
-and failed to find any,
-but somehow you snuck some in  via a #include
-file,
-for example .
-Make an explicit reference to the action in your
-.Nm lex
-input file.
-Note that previously
-.Nm lex
+and failed to find any, but somehow you snuck some in (via a #include
+file, for example).  Make an explicit reference to the action in your
+.I flex
+input file.  (Note that previously
+.I flex
 supported a
 supported a
-.Li %used/%unused
-mechanism for dealing with this problem;
-this feature is still supported
-but now deprecated,
-and will go away soon unless the author hears from
-people who can argue compellingly that they need it.
-.It Li lex scanner jammed
+.B %used/%unused
+mechanism for dealing with this problem; this feature is still supported
+but now deprecated, and will go away soon unless the author hears from
+people who can argue compellingly that they need it.)
+.LP
+.I flex scanner jammed -
 a scanner compiled with
 a scanner compiled with
-.Fl s
+.B -s
 has encountered an input string which wasn't matched by
 any of its rules.
 has encountered an input string which wasn't matched by
 any of its rules.
-.It Li lex input buffer overflowed
+.LP
+.I flex input buffer overflowed -
 a scanner rule matched a string long enough to overflow the
 a scanner rule matched a string long enough to overflow the
-scanner's internal input buffer  16K bytes - controlled by
-.Va YY_BUF_MAX
-in
-.Pa lex.skel .
-.It Li scanner requires  \&\-8 flag
+scanner's internal input buffer (16K bytes - controlled by
+.B YY_BUF_MAX
+in "lex.skel").
+.LP
+.I scanner requires -8 flag -
 Your scanner specification includes recognizing 8-bit characters and
 Your scanner specification includes recognizing 8-bit characters and
-you did not specify the -8 flag  and your site has not installed lex
-with -8 as the default .
-.It Li too many  \&%t classes!
+you did not specify the -8 flag (and your site has not installed flex
+with -8 as the default).
+.LP
+.I
+fatal flex scanner internal error--end of buffer missed -
+This can occur in an scanner which is reentered after a long-jump
+has jumped out (or over) the scanner's activation frame.  Before
+reentering the scanner, use:
+.nf
+
+    yyrestart( yyin );
+
+.fi
+.LP
+.I too many %t classes! -
 You managed to put every single character into its own %t class.
 You managed to put every single character into its own %t class.
-.Nm Lex
+.I flex
 requires that at least one of the classes share characters.
 requires that at least one of the classes share characters.
-.El
-.Sh HISTORY
-A
-.Nm lex
-appeared in
-.At v6 .
-The version this man page describes is
-derived from code contributed by Vern Paxson.
-.Sh AUTHOR
+.SH AUTHOR
 Vern Paxson, with the help of many ideas and much inspiration from
 Van Jacobson.  Original version by Jef Poskanzer.
 Vern Paxson, with the help of many ideas and much inspiration from
 Van Jacobson.  Original version by Jef Poskanzer.
-.Pp
-See
-.%T "Lexdoc"
-for additional credits and the address to send comments to.
-.Sh BUGS
-.Pp
+.LP
+See flexdoc(1) for additional credits and the address to send comments to.
+.SH DEFICIENCIES / BUGS
+.LP
 Some trailing context
 patterns cannot be properly matched and generate
 warning messages ("Dangerous trailing context").  These are
 patterns where the ending of the
 first part of the rule matches the beginning of the second
 part, such as "zx*/xy*", where the 'x*' matches the 'x' at
 Some trailing context
 patterns cannot be properly matched and generate
 warning messages ("Dangerous trailing context").  These are
 patterns where the ending of the
 first part of the rule matches the beginning of the second
 part, such as "zx*/xy*", where the 'x*' matches the 'x' at
-the beginning of the trailing context.  (Note that the
-.Tn POSIX
-draft
+the beginning of the trailing context.  (Note that the POSIX draft
 states that the text matched by such patterns is undefined.)
 states that the text matched by such patterns is undefined.)
-.Pp
+.LP
 For some trailing context rules, parts which are actually fixed-length are
 not recognized as such, leading to the abovementioned performance loss.
 For some trailing context rules, parts which are actually fixed-length are
 not recognized as such, leading to the abovementioned performance loss.
-In particular, parts using '\&|' or {n} (such as "foo{3}") are always
+In particular, parts using '|' or {n} (such as "foo{3}") are always
 considered variable-length.
 considered variable-length.
-.Pp
-Combining trailing context with the special '\&|' action can result in
-.Em fixed
+.LP
+Combining trailing context with the special '|' action can result in
+.I fixed
 trailing context being turned into the more expensive
 trailing context being turned into the more expensive
-.Em variable
-trailing context.  This happens in the following example:
-.Bd -literal -offset indent
-%%
-abc  \&|
-xyz/def
-.Ed
-.Pp
-Use of
-.Fn unput
-invalidates yytext and yyleng.
-.Pp
-Use of
-.Fn unput
-to push back more text than was matched can
+.I variable
+trailing context.  For example, this happens in the following example:
+.nf
+
+    %%
+    abc      |
+    xyz/def
+
+.fi
+.LP
+Use of unput() invalidates yytext and yyleng.
+.LP
+Use of unput() to push back more text than was matched can
 result in the pushed-back text matching a beginning-of-line ('^')
 rule even though it didn't come at the beginning of the line
 (though this is rare!).
 result in the pushed-back text matching a beginning-of-line ('^')
 rule even though it didn't come at the beginning of the line
 (though this is rare!).
-.Pp
-Pattern-matching of
-.Tn NUL Ns 's
-is substantially slower than matching other
+.LP
+Pattern-matching of NUL's is substantially slower than matching other
 characters.
 characters.
-.Pp
-.Nm Lex
+.LP
+.I flex
 does not generate correct #line directives for code internal
 to the scanner; thus, bugs in
 does not generate correct #line directives for code internal
 to the scanner; thus, bugs in
-.Pa lex.skel
+.I lex.skel
 yield bogus line numbers.
 yield bogus line numbers.
-.Pp
+.LP
 Due to both buffering of input and read-ahead, you cannot intermix
 Due to both buffering of input and read-ahead, you cannot intermix
-calls to
-.Aq Pa stdio.h
-routines, such as, for example,
-.Fn getchar ,
+calls to <stdio.h> routines, such as, for example,
+.B getchar(),
 with
 with
-.Nm lex
+.I flex
 rules and expect it to work.  Call
 rules and expect it to work.  Call
-.Fn input
+.B input()
 instead.
 instead.
-.Pp
+.LP
 The total table entries listed by the
 The total table entries listed by the
-.Fl v
+.B -v
 flag excludes the number of table entries needed to determine
 what rule has been matched.  The number of entries is equal
 flag excludes the number of table entries needed to determine
 what rule has been matched.  The number of entries is equal
-to the number of
-.Tn DFA
-states if the scanner does not use
-.Ic REJECT ,
+to the number of DFA states if the scanner does not use
+.B REJECT,
 and somewhat greater than the number of states if it does.
 and somewhat greater than the number of states if it does.
-.Pp
-.Ic REJECT
+.LP
+.B REJECT
 cannot be used with the
 cannot be used with the
-.Fl f
+.I -f
 or
 or
-.Fl F
+.I -F
 options.
 options.
-.Pp
+.LP
 Some of the macros, such as
 Some of the macros, such as
-.Fn yywrap ,
+.B yywrap(),
 may in the future become functions which live in the
 may in the future become functions which live in the
-.Fl lfl
+.B -lfl
 library.  This will doubtless break a lot of code, but may be
 library.  This will doubtless break a lot of code, but may be
-required for
-.Tn POSIX Ns \-compliance .
-.Pp
+required for POSIX-compliance.
+.LP
 The
 The
-.Nm lex
+.I flex
 internal algorithms need documentation.
 internal algorithms need documentation.