.\" Man page generated from reStructuredText. . .TH RE2C 1 "" "" "" .SH NAME re2c \- compile regular expressions to code . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .sp \fBre2c [OPTIONS] INPUT [\-o OUTPUT]\fP .sp \fBre2go [OPTIONS] INPUT [\-o OUTPUT]\fP .SH DESCRIPTION .sp re2c is a tool for generating fast lexical analyzers for C, C++ and Go. .sp Note: This manual includes examples for Go, but it refers to re2c (rather than re2go) as the name of the program in general. .SH SYNTAX .sp A re2c program consists of normal code intermixed with re2c blocks and \fI\%directives\fP\&. Each re2c block may contain definitions, configurations and rules. Definitions are of the form \fBname = regexp;\fP where \fBname\fP is an identifier that consists of letters, digits and underscores, and \fBregexp\fP is a regular expression. \fI\%Regular expressions\fP may contain other definitions, but recursion is not allowed and each name should be defined before used. \fI\%Configurations\fP are of the form \fBre2c:config = value;\fP where \fBconfig\fP is the configuration descriptor and \fBvalue\fP can be a number, a string or a special word. Rules consist of a regular expression followed by a semantic action (a block of code enclosed in curly braces \fB{\fP and \fB}\fP, or a raw one line of code preceded with \fB:=\fP and ended with a newline that is not followed by a whitespace). If the input matches the regular expression, the associated semantic action is executed. If multiple rules match, the longest match takes precedence. If multiple rules match the same string, the earlier rule takes precedence. There are two special rules: default rule \fB*\fP and EOF rule \fB$\fP\&. Default rule should always be defined, it has the lowest priority regardless of its place and matches any code unit (not necessarily a valid character, see \fI\%encoding support\fP). EOF rule matches the end of input, it should be defined if the corresponding \fI\%EOF handling\fP method is used. If \fI\%start conditions\fP are used, rules have more complex syntax. All rules of a single block are compiled into a deterministic finite\-state automaton (DFA) and encoded in the form of a program in the target language. The generated code interfaces with the outer program by the means of a few user\-defined primitives (see the \fI\%program interface\fP section). \fI\%Reusable blocks\fP allow sharing rules, definitions and configurations between different blocks. .SH EXAMPLE .SS Input file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT \-i package main // // func lex(str string) int { // Go code var cursor int // /*!re2c // start of re2c block re2c:define:YYCTYPE = byte; // configuration re2c:define:YYPEEK = "str[cursor]"; // configuration re2c:define:YYSKIP = "cursor += 1"; // configuration re2c:yyfill:enable = 0; // configuration re2c:flags:nested\-ifs = 1; // configuration // number = [1\-9][0\-9]*; // named definition // number { return 0; } // normal rule * { return 1; } // default rule */ } // // func main() { // if lex("1234\ex00") != 0 { // Go code panic("failed!") // } // } // .ft P .fi .UNINDENT .UNINDENT .SS Output file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // Code generated by re2c, DO NOT EDIT. //go:generate re2go $INPUT \-o $OUTPUT \-i package main // // func lex(str string) int { // Go code var cursor int // { var yych byte yych = str[cursor] if (yych <= \(aq0\(aq) { goto yy2 } if (yych <= \(aq9\(aq) { goto yy4 } yy2: cursor += 1 { return 1; } yy4: cursor += 1 yych = str[cursor] if (yych <= \(aq/\(aq) { goto yy6 } if (yych <= \(aq9\(aq) { goto yy4 } yy6: { return 0; } } } // // func main() { // if lex("1234\ex00") != 0 { // Go code panic("failed!") // } // } // .ft P .fi .UNINDENT .UNINDENT .SH OPTIONS .INDENT 0.0 .TP .B \fB\-? \-h \-\-help\fP Show help message. .TP .B \fB\-1 \-\-single\-pass\fP Deprecated. Does nothing (single pass is the default now). .TP .B \fB\-8 \-\-utf\-8\fP Generate a lexer that reads input in UTF\-8 encoding. re2c assumes that character range is 0 \-\- 0x10FFFF and character size is 1 byte. .TP .B \fB\-b \-\-bit\-vectors\fP Optimize conditional jumps using bit masks. Implies \fB\-s\fP\&. .TP .B \fB\-c \-\-conditions \-\-start\-conditions\fP Enable support of Flex\-like "conditions": multiple interrelated lexers within one block. Option \fB\-\-start\-conditions\fP is a legacy alias; use \fB\-\-conditions\fP instead. .TP .B \fB\-\-case\-insensitive\fP Treat single\-quoted and double\-quoted strings as case\-insensitive. .TP .B \fB\-\-case\-inverted\fP Invert the meaning of single\-quoted and double\-quoted strings: treat single\-quoted strings as case\-sensitive and double\-quoted strings as case\-insensitive. .TP .B \fB\-\-case\-ranges\fP Collapse consecutive cases in a switch statements into a range of the form \fBcase low ... high:\fP\&. This syntax is an extension of the C/C++ language, supported by compilers like GCC, Clang and Tcc. The main advantage over using single cases is smaller generated C code and faster generation time, although for some compilers like Tcc it also results in smaller binary size. This option doesn\(aqt work for the Go backend. .TP .B \fB\-e \-\-ecb\fP Generate a lexer that reads input in EBCDIC encoding. re2c assumes that character range is 0 \-\- 0xFF an character size is 1 byte. .TP .B \fB\-\-empty\-class \fP Define the way re2c treats empty character classes. With \fBmatch\-empty\fP (the default) empty class matches empty input (which is illogical, but backwards\-compatible). With\(ga\(gamatch\-none\(ga\(ga empty class always fails to match. With \fBerror\fP empty class raises a compilation error. .TP .B \fB\-\-encoding\-policy \fP Define the way re2c treats Unicode surrogates. With \fBfail\fP re2c aborts with an error when a surrogate is encountered. With \fBsubstitute\fP re2c silently replaces surrogates with the error code point 0xFFFD. With \fBignore\fP (the default) re2c treats surrogates as normal code points. The Unicode standard says that standalone surrogates are invalid, but real\-world libraries and programs behave in different ways. .TP .B \fB\-f \-\-storable\-state\fP Generate a lexer which can store its inner state. This is useful in push\-model lexers which are stopped by an outer program when there is not enough input, and then resumed when more input becomes available. In this mode users should additionally define \fBYYGETSTATE()\fP and \fBYYSETSTATE(state)\fP macros and variables \fByych\fP, \fByyaccept\fP and \fBstate\fP as part of the lexer state. .TP .B \fB\-F \-\-flex\-syntax\fP Partial support for Flex syntax: in this mode named definitions don\(aqt need the equal sign and the terminating semicolon, and when used they must be surrounded by curly braces. Names without curly braces are treated as double\-quoted strings. .TP .B \fB\-g \-\-computed\-gotos\fP Optimize conditional jumps using non\-standard "computed goto" extension (which must be supported by the compiler). re2c generates jump tables only in complex cases with a lot of conditional branches. Complexity threshold can be configured with \fBcgoto:threshold\fP configuration. This option implies \fB\-b\fP\&. This option doesn\(aqt work for the Go backend. .TP .B \fB\-I PATH\fP Add \fBPATH\fP to the list of locations which are used when searching for include files. This option is useful in combination with \fB/*!include:re2c ... */\fP directive. Re2c looks for \fBFILE\fP in the directory of including file and in the list of include paths specified by \fB\-I\fP option. .TP .B \fB\-i \-\-no\-debug\-info\fP Do not output \fB#line\fP information. This is useful when the generated code is tracked by some version control system or IDE. .TP .B \fB\-\-input \fP Specify the API used by the generated code to interface with used\-defined code. Option \fBdefault\fP is the C API based on pointer arithmetic (it is the default for the C backend). Option \fBcustom\fP is the generic API (it is the default for the Go backend). .TP .B \fB\-\-input\-encoding \fP Specify the way re2c parses regular expressions. With \fBascii\fP (the default) re2c handles input as ASCII\-encoded: any sequence of code units is a sequence of standalone 1\-byte characters. With \fButf8\fP re2c handles input as UTF8\-encoded and recognizes multibyte characters. .TP .B \fB\-\-lang \fP Specify the output language. Supported languages are C and Go (the default is C). .TP .B \fB\-\-location\-format \fP Specify location format in messages. With \fBgnu\fP locations are printed as \(aqfilename:line:column: ...\(aq. With \fBmsvc\fP locations are printed as \(aqfilename(line,column) ...\(aq. Default is \fBgnu\fP\&. .TP .B \fB\-\-no\-generation\-date\fP Suppress date output in the generated file. .TP .B \fB\-\-no\-version\fP Suppress version output in the generated file. .TP .B \fB\-o OUTPUT \-\-output=OUTPUT\fP Specify the \fBOUTPUT\fP file. .TP .B \fB\-P \-\-posix\-captures\fP Enable submatch extraction with POSIX\-style capturing groups. .TP .B \fB\-r \-\-reusable\fP Allows reuse of re2c rules with \fB/*!rules:re2c */\fP and \fB/*!use:re2c */\fP blocks. Exactly one rules\-block must be present. The rules are saved and used by every use\-block that follows, which may add its own rules and configurations. .TP .B \fB\-S \-\-skeleton\fP Ignore user\-defined interface code and generate a self\-contained "skeleton" program. Additionally, generate input files with strings derived from the regular grammar and compressed match results that are used to verify "skeleton" behavior on all inputs. This option is useful for finding bugs in optimizations and code generation. This option doesn\(aqt work for the Go backend. .TP .B \fB\-s \-\-nested\-ifs\fP Use nested \fBif\fP statements instead of \fBswitch\fP statements in conditional jumps. This usually results in more efficient code with non\-optimizing compilers. .TP .B \fB\-T \-\-tags\fP Enable submatch extraction with tags. .TP .B \fB\-t HEADER \-\-type\-header=HEADER\fP Generate a \fBHEADER\fP file that contains enum with condition names. Requires \fB\-c\fP option. .TP .B \fB\-u \-\-unicode\fP Generate a lexer that reads UTF32\-encoded input. Re2c assumes that character range is 0 \-\- 0x10FFFF and character size is 4 bytes. This option implies \fB\-s\fP\&. .TP .B \fB\-V \-\-vernum\fP Show version information in \fBMMmmpp\fP format (major, minor, patch). .TP .B \fB\-\-verbose\fP Output a short message in case of success. .TP .B \fB\-v \-\-version\fP Show version information. .TP .B \fB\-w \-\-wide\-chars\fP Generate a lexer that reads UCS2\-encoded input. Re2c assumes that character range is 0 \-\- 0xFFFF and character size is 2 bytes. This option implies \fB\-s\fP\&. .TP .B \fB\-x \-\-utf\-16\fP Generate a lexer that reads UTF16\-encoded input. Re2c assumes that character range is 0 \-\- 0x10FFFF and character size is 2 bytes. This option implies \fB\-s\fP\&. .UNINDENT .SS Debug options .INDENT 0.0 .TP .B \fB\-D \-\-emit\-dot\fP Instead of normal output generate lexer graph in .dot format. The output can be converted to an image with the help of Graphviz (e.g. something like \fBdot \-Tpng \-odfa.png dfa.dot\fP). .TP .B \fB\-d \-\-debug\-output\fP Emit \fBYYDEBUG\fP in the generated code. \fBYYDEBUG\fP should be defined by the user in the form of a void function with two parameters: \fBstate\fP (lexer state or \-1) and \fBsymbol\fP (current input symbol of type \fBYYCTYPE\fP). .TP .B \fB\-\-dump\-adfa\fP Debug option: output DFA after tunneling (in .dot format). .TP .B \fB\-\-dump\-cfg\fP Debug option: output control flow graph of tag variables (in .dot format). .TP .B \fB\-\-dump\-closure\-stats\fP Debug option: output statistics on the number of states in closure. .TP .B \fB\-\-dump\-dfa\-det\fP Debug option: output DFA immediately after determinization (in .dot format). .TP .B \fB\-\-dump\-dfa\-min\fP Debug option: output DFA after minimization (in .dot format). .TP .B \fB\-\-dump\-dfa\-tagopt\fP Debug option: output DFA after tag optimizations (in .dot format). .TP .B \fB\-\-dump\-dfa\-tree\fP Debug option: output DFA under construction with states represented as tag history trees (in .dot format). .TP .B \fB\-\-dump\-dfa\-raw\fP Debug option: output DFA under construction with expanded state\-sets (in .dot format). .TP .B \fB\-\-dump\-interf\fP Debug option: output interference table produced by liveness analysis of tag variables. .TP .B \fB\-\-dump\-nfa\fP Debug option: output NFA (in .dot format). .UNINDENT .SS Internal options .INDENT 0.0 .TP .B \fB\-\-dfa\-minimization \fP Internal option: DFA minimization algorithm used by re2c. The \fBmoore\fP option is the Moore algorithm (it is the default). The \fBtable\fP option is the "table filling" algorithm. Both algorithms should produce the same DFA up to states relabeling; table filling is simpler and much slower and serves as a reference implementation. .TP .B \fB\-\-eager\-skip\fP Internal option: make the generated lexer advance the input position eagerly \-\- immediately after reading the input symbol. This changes the default behavior when the input position is advanced lazily \-\- after transition to the next state. This option is implied by \fB\-\-no\-lookahead\fP\&. .TP .B \fB\-\-no\-lookahead\fP Internal option: use TDFA(0) instead of TDFA(1). This option has effect only with \fB\-\-tags\fP or \fB\-\-posix\-captures\fP options. .TP .B \fB\-\-no\-optimize\-tags\fP Internal optionL: suppress optimization of tag variables (useful for debugging). .TP .B \fB\-\-posix\-closure \fP Internal option: specify shortest\-path algorithm used for the construction of epsilon\-closure with POSIX disambiguation semantics: \fBgor1\fP (the default) stands for Goldberg\-Radzik algorithm, and \fBgtop\fP stands for "global topological order" algorithm. .TP .B \fB\-\-posix\-prectable \fP Internal option: specify the algorithm used to compute POSIX precedence table. The \fBcomplex\fP algorithm computes precedence table in one traversal of tag history tree and has quadratic complexity in the number of TNFA states; it is the default. The \fBnaive\fP algorithm has worst\-case cubic complexity in the number of TNFA states, but it is much simpler than \fBcomplex\fP and may be slightly faster in non\-pathological cases. .TP .B \fB\-\-stadfa\fP Internal option: use staDFA algorithm for submatch extraction. The main difference with TDFA is that tag operations in staDFA are placed in states, not on transitions. .UNINDENT .SS Warnings .INDENT 0.0 .TP .B \fB\-W\fP Turn on all warnings. .TP .B \fB\-Werror\fP Turn warnings into errors. Note that this option alone doesn\(aqt turn on any warnings; it only affects those warnings that have been turned on so far or will be turned on later. .TP .B \fB\-W\fP Turn on \fBwarning\fP\&. .TP .B \fB\-Wno\-\fP Turn off \fBwarning\fP\&. .TP .B \fB\-Werror\-\fP Turn on \fBwarning\fP and treat it as an error (this implies \fB\-W\fP). .TP .B \fB\-Wno\-error\-\fP Don\(aqt treat this particular \fBwarning\fP as an error. This doesn\(aqt turn off the warning itself. .UNINDENT .INDENT 0.0 .TP .B \fB\-Wcondition\-order\fP Warn if the generated program makes implicit assumptions about condition numbering. One should use either the \fB\-t, \-\-type\-header\fP option or the \fB/*!types:re2c*/\fP directive to generate a mapping of condition names to numbers and then use the autogenerated condition names. .TP .B \fB\-Wempty\-character\-class\fP Warn if a regular expression contains an empty character class. Trying to match an empty character class makes no sense: it should always fail. However, for backwards compatibility reasons \fBre2c\fP allows empty character classes and treats them as empty strings. Use the \fB\-\-empty\-class\fP option to change the default behavior. .TP .B \fB\-Wmatch\-empty\-string\fP Warn if a rule is nullable (matches an empty string). If the lexer runs in a loop and the empty match is unintentional, the lexer may unexpectedly hang in an infinite loop. .TP .B \fB\-Wswapped\-range\fP Warn if the lower bound of a range is greater than its upper bound. The default behavior is to silently swap the range bounds. .TP .B \fB\-Wundefined\-control\-flow\fP Warn if some input strings cause undefined control flow in the lexer (the faulty patterns are reported). This is the most dangerous and most common mistake. It can be easily fixed by adding the default rule \fB*\fP which has the lowest priority, matches any code unit, and consumes exactly one code unit. .TP .B \fB\-Wunreachable\-rules\fP Warn about rules that are shadowed by other rules and will never match. .TP .B \fB\-Wuseless\-escape\fP Warn if a symbol is escaped when it shouldn\(aqt be. By default, re2c silently ignores such escapes, but this may as well indicate a typo or an error in the escape sequence. .TP .B \fB\-Wnondeterministic\-tags\fP Warn if a tag has \fBn\fP\-th degree of nondeterminism, where \fBn\fP is greater than 1. .TP .B \fB\-Wsentinel\-in\-midrule\fP Warn if the sentinel symbol occurs in the middle of a rule \-\-\- this may cause reads past the end of buffer, crashes or memory corruption in the generated lexer. This warning is only applicable if the sentinel method of checking for the end of input is used. It is set to an error if \fBre2c:sentinel\fP configuration is used. .UNINDENT .SH PROGRAM INTERFACE .sp Re2c has a flexible interface that gives the user both the freedom and the responsibility to define how the generated code interacts with the outer program. There are two major options: .INDENT 0.0 .IP \(bu 2 \fBPointer API\fP\&. It is also called "default API", since it was historically the first, and for a long time the only one. This is a more restricted API based on C pointer arithmetics. It consists of pointer\-like primitives \fBYYCURSOR\fP, \fBYYMARKER\fP, \fBYYCTXMARKER\fP and \fBYYLIMIT\fP, which are normally defined as pointers of type \fBYYCTYPE*\fP\&. Pointer API is enabled by default for the C backend, and it cannot be used with other backends that do not have pointer arithmetics. .nf .fi .sp .IP \(bu 2 \fBGeneric API\fP\&. This is a less restricted API that does not assume pointer semantics. It consists of primitives \fBYYPEEK\fP, \fBYYSKIP\fP, \fBYYBACKUP\fP, \fBYYBACKUPCTX\fP, \fBYYSTAGP\fP, \fBYYSTAGN\fP, \fBYYMTAGP\fP, \fBYYMTAGN\fP, \fBYYRESTORE\fP, \fBYYRESTORECTX\fP, \fBYYRESTORETAG\fP, \fBYYSHIFT\fP, \fBYYSHIFTSTAG\fP, \fBYYSHIFTMTAG\fP and \fBYYLESSTHAN\fP\&. For the C backend generic API is enabled with \fB\-\-input custom\fP option or \fBre2c:flags:input = custom;\fP configuration; for the Go backend it is enabled by default. Generic API was added in version 0.14. It is intentionally designed to give the user as much freedom as possible in redefining the input model and the semantics of different actions performed by the generated code. As an example, one can override \fBYYPEEK\fP to check for the end of input before reading the input character, or do some logging, etc. .UNINDENT .sp Generic API has two styles: .INDENT 0.0 .IP \(bu 2 \fBFunction\-like\fP\&. This style is enabled with \fBre2c:api:style = functions;\fP configuration, and it is the default for C backend. In this style API primitives should be defined as functions or macros with parentheses, accepting the necessary arguments. For example, in C the default pointer API can be defined in function\-like style generic API as follows: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #define YYPEEK() *YYCURSOR #define YYSKIP() ++YYCURSOR #define YYBACKUP() YYMARKER = YYCURSOR #define YYBACKUPCTX() YYCTXMARKER = YYCURSOR #define YYRESTORE() YYCURSOR = YYMARKER #define YYRESTORECTX() YYCURSOR = YYCTXMARKER #define YYRESTORETAG(tag) YYCURSOR = tag #define YYLESSTHAN(len) YYLIMIT \- YYCURSOR < len #define YYSTAGP(tag) tag = YYCURSOR #define YYSTAGN(tag) tag = NULL #define YYSHIFT(shift) YYCURSOR += shift #define YYSHIFTSTAG(tag, shift) tag += shift .ft P .fi .UNINDENT .UNINDENT .nf .fi .sp .IP \(bu 2 \fBFree\-form\fP\&. This style is enabled with \fBre2c:api:style = free\-form;\fP configuration, and it is the default for Go backend. In this style API primitives can be defined as free\-form pieces of code, and instead of arguments they have interpolated variables of the form \fB@@{name}\fP, or optionally just \fB@@\fP if there is only one argument. The \fB@@\fP text is called "sigil". It can be redefined to any other text with \fBre2c:api:sigil\fP configuration. For example, the default pointer API can be defined in free\-form style generic API as follows: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C re2c:define:YYPEEK = "*YYCURSOR"; re2c:define:YYSKIP = "++YYCURSOR"; re2c:define:YYBACKUP = "YYMARKER = YYCURSOR"; re2c:define:YYBACKUPCTX = "YYCTXMARKER = YYCURSOR"; re2c:define:YYRESTORE = "YYCURSOR = YYMARKER"; re2c:define:YYRESTORECTX = "YYCURSOR = YYCTXMARKER"; re2c:define:YYRESTORETAG = "YYCURSOR = ${tag}"; re2c:define:YYLESSTHAN = "YYLIMIT \- YYCURSOR < @@{len}"; re2c:define:YYSTAGP = "@@{tag} = YYCURSOR"; re2c:define:YYSTAGN = "@@{tag} = NULL"; re2c:define:YYSHIFT = "YYCURSOR += @@{shift}"; re2c:define:YYSHIFTSTAG = "@@{tag} += @@{shift}"; .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS API primitives .sp Here is a list of API primitives that may be used by the generated code in order to interface with the outer program. Which primitives are needed depends on multiple factors, including the complexity of regular expressions, input representation, buffering, the use of various features and so on. All the necessary primitives should be defined by the user in the form of macros, functions, variables, free\-form pieces of code or any other suitable form. Re2c does not (and cannot) check the definitions, so if anything is missing or defined incorrectly the generated code will not compile. .INDENT 0.0 .TP .B \fBYYCTYPE\fP The type of the input characters (code units). For ASCII, EBCDIC and UTF\-8 encodings it should be 1\-byte unsigned integer. For UTF\-16 or UCS\-2 it should be 2\-byte unsigned integer. For UTF\-32 it should be 4\-byte unsigned integer. .TP .B \fBYYCURSOR\fP A pointer\-like l\-value that stores the current input position (usually a pointer of type \fBYYCTYPE*\fP). Initially \fBYYCURSOR\fP should point to the first input character. It is advanced by the generated code. When a rule matches, \fBYYCURSOR\fP points to the one after the last matched character. It is used only in the default C API. .TP .B \fBYYLIMIT\fP A pointer\-like r\-value that stores the end of input position (usually a pointer of type \fBYYCTYPE*\fP). Initially \fBYYLIMIT\fP should point to the one after the last available input character. It is not changed by the generated code. Lexer compares \fBYYCURSOR\fP to \fBYYLIMIT\fP in order to determine if there is enough input characters left. \fBYYLIMIT\fP is used only in the default C API. .TP .B \fBYYMARKER\fP A pointer\-like l\-value (usually a pointer of type \fBYYCTYPE*\fP) that stores the position of the latest matched rule. It is used to restores \fBYYCURSOR\fP position if the longer match fails and lexer needs to rollback. Initialization is not needed. \fBYYMARKER\fP is used only in the default C API. .TP .B \fBYYCTXMARKER\fP A pointer\-like l\-value that stores the position of the trailing context (usually a pointer of type \fBYYCTYPE*\fP). No initialization is needed. It is used only in the default C API, and only with the lookahead operator \fB/\fP\&. .TP .B \fBYYFILL\fP API primitive with one argument \fBlen\fP\&. The meaning of \fBYYFILL\fP is to provide at least \fBlen\fP more input characters or fail. If EOF rule is used, \fBYYFILL\fP should always return to the calling function; the return value should be zero on success and non\-zero on failure. If EOF rule is not used, \fBYYFILL\fP return value is ignored and it should not return on failure. Maximal value of \fBlen\fP is \fBYYMAXFILL\fP, which can be generated with \fB/*!max:re2c*/\fP directive. The definition of \fBYYFILL\fP can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP and \fBre2c:define:YYFILL:naked\fP). .TP .B \fBYYMAXFILL\fP An integral constant equal to the maximal value of \fBYYFILL\fP argument. It can be generated with \fB/*!max:re2c*/\fP directive. .TP .B \fBYYLESSTHAN\fP A generic API primitive with one argument \fBlen\fP\&. It should be defined as an r\-value of boolean type that equals \fBtrue\fP if and only if there is less than \fBlen\fP input characters left. The definition can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYPEEK\fP A generic API primitive with no arguments. It should be defined as an r\-value of type \fBYYCTYPE\fP that is equal to the character at the current input position. The definition can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYSKIP\fP A generic API primitive with no arguments. The meaning of \fBYYSKIP\fP is to advance the current input position by one character. The definition can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYBACKUP\fP A generic API primitive with no arguments. The meaning of \fBYYBACKUP\fP is to save the current input position, which is later restored with \fBYYRESTORE\fP\&. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYRESTORE\fP A generic API primitive with no arguments. The meaning of \fBYYRESTORE\fP is to restore the current input position to the value saved by \fBYYBACKUP\fP\&. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYBACKUPCTX\fP A generic API primitive with zero arguments. The meaning of \fBYYBACKUPCTX\fP is to save the current input position as the position of the trailing context, which is later restored by \fBYYRESTORECTX\fP\&. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYRESTORECTX\fP A generic API primitive with no arguments. The meaning of \fBYYRESTORECTX\fP is to restore the trailing context position saved with \fBYYBACKUPCTX\fP\&. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYRESTORETAG\fP A generic API primitive with one argument \fBtag\fP\&. The meaning of \fBYYRESTORETAG\fP is to restore the trailing context position to the value of \fBtag\fP\&. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYSTAGP\fP A generic API primitive with one argument \fBtag\fP\&. The meaning of \fBYYSTAGP\fP is to set \fBtag\fP value to the current input position. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYSTAGN\fP A generic API primitive with one argument \fBtag\fP\&. The meaning of \fBYYSTAGP\fP is to set \fBtag\fP value to null (or some default value). The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYMTAGP\fP A generic API primitive with one argument \fBtag\fP\&. The meaning of \fBYYMTAGP\fP is to append the current position to the history of \fBtag\fP\&. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYMTAGN\fP A generic API primitive with one argument \fBtag\fP\&. The meaning of \fBYYMTAGN\fP is to append null (or some other default) value to the history of \fBtag\fP\&. The definition can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYSHIFT\fP A generic API primitive with one argument \fBshift\fP\&. The meaning of \fBYYSHIFT\fP is to shift the current input position by \fBshift\fP characters (the shift value may be negative). The definition can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYSHIFTSTAG\fP A generic API primitive with two arguments, \fBtag\fP and \fBshift\fP\&. The meaning of \fBYYSHIFTSTAG\fP is to shift \fBtag\fP by \fBshift\fP characters (the shift value may be negative). The definition can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYSHIFTMTAG\fP A generic API primitive with two arguments, \fBtag\fP and \fBshift\fP\&. The meaning of \fBYYSHIFTMTAG\fP is to shift the latest value in the history of \fBtag\fP by \fBshift\fP characters (the shift value may be negative). The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP). .TP .B \fBYYMAXNMATCH\fP An integral constant equal to the maximal number of POSIX capturing groups in a rule. It is generated with \fB/*!maxnmatch:re2c*/\fP directive. .TP .B \fBYYCONDTYPE\fP The type of the condition enum. It should be generated either with \fB/*!types:re2c*/\fP directive or \fB\-t\fP \fB\-\-type\-header\fP option. .TP .B \fBYYGETCONDITION\fP An API primitive with zero arguments. It should be defined as an r\-value of type \fBYYCONDTYPE\fP that is equal to the current condition identifier. The definition can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP and \fBre2c:define:YYGETCONDITION:naked\fP). .TP .B \fBYYSETCONDITION\fP An API primitive with one argument \fBcond\fP\&. The meaning of \fBYYSETCONDITION\fP is to set the current condition identifier to \fBcond\fP\&. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP and \fBre2c:define:YYSETCONDITION@cond\fP). .TP .B \fBYYGETSTATE\fP An API primitive with zero arguments. It should be defined as an r\-value of integer type that is equal to the current lexer state. Should be initialized to \fB\-1\fP\&. The definition can be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP and \fBre2c:define:YYGETSTATE:naked\fP). .TP .B \fBYYSETSTATE\fP An API primitive with one argument \fBstate\fP\&. The meaning of \fBYYSETSTATE\fP is to set the current lexer state to \fBstate\fP\&. The definition should be either function\-like or free\-form depending on the API style (see \fBre2c:api:style\fP and \fBre2c:define:YYSETSTATE@state\fP). .TP .B \fBYYDEBUG\fP A debug API primitive with two arguments. It can be used to debug the generated code (with \fB\-d\fP \fB\-\-debug\-output\fP option). \fBYYDEBUG\fP should return no value and accept two arguments: \fBstate\fP (either a DFA state index or \fB\-1\fP) and \fBsymbol\fP (the current input symbol). .TP .B \fByych\fP An l\-value of type \fBYYCTYPE\fP that stores the current input character. User definition is necessary only with \fB\-f\fP \fB\-\-storable\-state\fP option. .TP .B \fByyaccept\fP An l\-value of unsigned integral type that stores the number of the latest matched rule. User definition is necessary only with \fB\-f\fP \fB\-\-storable\-state\fP option. .TP .B \fByynmatch\fP An l\-value of unsigned integral type that stores the number of POSIX capturing groups in the matched rule. Used only with \fB\-P\fP \fB\-\-posix\-captures\fP option. .TP .B \fByypmatch\fP An array of l\-values that are used to hold the tag values corresponding to the capturing parentheses in the matching rule. Array length must be at least \fByynmatch * 2\fP (usually \fBYYMAXNMATCH * 2\fP is a good choice). Used only with \fB\-P\fP \fB\-\-posix\-captures\fP option. .UNINDENT .SS Directives .sp Below is the list of all directives provided by re2c (in no particular order). More information on each directive can be found in the related sections. .INDENT 0.0 .TP .B \fB/*!re2c ... */\fP A standard re2c block. .TP .B \fB%{ ... %}\fP A standard re2c block in \fB\-F \-\-flex\-support\fP mode. .TP .B \fB/*!rules:re2c ... */\fP A reusable re2c block (requires \fB\-r \-\-reuse\fP option). .TP .B \fB/*!use:re2c ... */\fP A block that reuses previous rules\-block specified with \fB/*!rules:re2c ... */\fP (requires \fB\-r \-\-reuse\fP option). .TP .B \fB/*!ignore:re2c ... */\fP A block which contents are ignored and cut off from the output file. .TP .B \fB/*!max:re2c*/\fP This directive is substituted with the macro\-definition of \fBYYMAXFILL\fP\&. .TP .B \fB/*!maxnmatch:re2c*/\fP This directive is substituted with the macro\-definition of \fBYYMAXNMATCH\fP (requires \fB\-P \-\-posix\-captures\fP option). .TP .B \fB/*!getstate:re2c*/\fP This directive is substituted with conditional dispatch on lexer state (requires \fB\-f \-\-storable\-state\fP option). .TP .B \fB/*!types:re2c ... */\fP This directive is substituted with the definition of condition \fBenum\fP (requires \fB\-c \-\-conditions\fP option). .TP .B \fB/*!stags:re2c ... */\fP, \fB/*!mtags:re2c ... */\fP These directives allow one to specify a template piece of code that is expanded for each s\-tag/m\-tag variable generated by re2c. This block has two optional configurations: \fBformat = "@@";\fP (specifies the template where \fB@@\fP is substituted with the name of each tag variable), and \fBseparator = "";\fP (specifies the piece of code used to join the generated pieces for different tag variables). .TP .B \fB/*!include:re2c FILE */\fP This directive allows one to include \fBFILE\fP (in the same sense as \fB#include\fP directive in C/C++). .TP .B \fB/*!header:re2c:on*/\fP This directive marks the start of header file. Everything after it and up to the following \fB/*!header:re2c:off*/\fP directive is processed by re2c and written to the header file specified with \fB\-t \-\-type\-header\fP option. .TP .B \fB/*!header:re2c:off*/\fP This directive marks the end of header file started with \fB/*!header:re2c:on*/\fP\&. .UNINDENT .SS Configurations .INDENT 0.0 .TP .B \fBre2c:flags:t\fP, \fBre2c:flags:type\-header\fP Specify the name of the generated header file relative to the directory of the output file. (Same as \fB\-t\fP, \fB\-\-type\-header\fP command\-line option except that the filepath is relative.) .TP .B \fBre2c:flags:input\fP Same as \fB\-\-input\fP command\-line option. .TP .B \fBre2c:api:style\fP Allows one to specify the style of generic API. Possible values are \fBfunctions\fP and \fBfree\-form\fP\&. With \fBfunctions\fP style (the default for the C backend) API primitives behave like functions, and re2c generates parentheses with an argument list after the name of each primitive. With \fBfree\-form\fP style (the default for the Go backend) re2c treats API definitions as interpolated strings and substitutes argument placeholders with the actual argument values. This option can be overridden by options for individual API primitives, e.g. \fBre2c:define:YYFILL:naked\fP for \fBYYFILL\fP\&. .TP .B \fBre2c:api:sigil\fP Allows one to specify the "sigil" symbol (or string) that is used to recognize argument placeholders in the definitions of generic API primitives. The default value is \fB@@\fP\&. Placeholders start with sigil, followed by the argument name in curly braces. For example, if sigil is set to \fB$\fP, then placeholders will have the form \fB${name}\fP\&. Single\-argument APIs may use shorthand notation without the name in braces. This option can be overridden by options for individual API primitives, e.g. \fBre2c:define:YYFILL@len\fP for \fBYYFILL\fP\&. .TP .B \fBre2c:define:YYCTYPE\fP Defines \fBYYCTYPE\fP (see the user interface section). .TP .B \fBre2c:define:YYCURSOR\fP Defines C API primitive \fBYYCURSOR\fP (see the user interface section). .TP .B \fBre2c:define:YYLIMIT\fP Defines C API primitive \fBYYLIMIT\fP (see the user interface section). .TP .B \fBre2c:define:YYMARKER\fP Defines C API primitive \fBYYMARKER\fP (see the user interface section). .TP .B \fBre2c:define:YYCTXMARKER\fP Defines C API primitive \fBYYCTXMARKER\fP (see the user interface section). .TP .B \fBre2c:define:YYFILL\fP Defines API primitive \fBYYFILL\fP (see the user interface section). .TP .B \fBre2c:define:YYFILL@len\fP Specifies the sigil used for argument substitution in \fBYYFILL\fP definition. Defaults to \fB@@\fP\&. Overrides the more generic \fBre2c:api:sigil\fP configuration. .TP .B \fBre2c:define:YYFILL:naked\fP Allows one to override \fBre2c:api:style\fP for \fBYYFILL\fP\&. Value \fB0\fP corresponds to free\-form API style. .TP .B \fBre2c:yyfill:enable\fP Defaults to \fB1\fP (\fBYYFILL\fP is enabled). Set this to zero to suppress the generation of \fBYYFILL\fP\&. Use warnings (\fB\-W\fP option) and \fBre2c:sentinel\fP configuration to verify that the generated lexer cannot read past the end of input, as this might introduce severe security issues to your programs. .TP .B \fBre2c:yyfill:parameter\fP Controls the argument in the parentheses that follow \fBYYFILL\fP\&. Defaults to \fB1\fP, which means that the argument is generated. If zero, the argument is omitted. Can be overridden with \fBre2c:define:YYFILL:naked\fP or \fBre2c:api:style\fP\&. .TP .B \fBre2c:eof\fP Specifies the sentinel symbol used with EOF rule \fB$\fP to check for the end of input in the generated lexer. The default value is \fB\-1\fP (EOF rule is not used). Other possible values include all valid code units. Only decimal numbers are recognized. .TP .B \fBre2c:sentinel\fP Specifies the sentinel symbol used with the sentinel method of checking for the end of input in the generated lexer (the case when bounds checking is disabled with \fBre2c:yyfill:enable = 0;\fP and EOF rule \fB$\fP is not used). This configuration does not affect code generation. It is used by re2c to verify that the sentinel symbol is not allowed in the middle of the rule, and prevent possible reads past the end of buffer in the generated lexer. The default value is \fB\-1\fP (re2c assumes that the sentinel symbol is \fB0\fP, which is the most common case). Other possible values include all valid code units. Only decimal numbers are recognized. .TP .B \fBre2c:define:YYLESSTHAN\fP Defines generic API primitive \fBYYLESSTHAN\fP (see the user interface section). .TP .B \fBre2c:yyfill:check\fP Setting this to zero allows one to suppress the generation of \fBYYFILL\fP check (\fBYYLESSTHAN\fP in generic API of \fBYYLIMIT\fP\-based comparison in default C API). This configuration is useful when the necessary input is always available. it defaults to \fB1\fP (the check is generated). .TP .B \fBre2c:label:yyFillLabel\fP Allows one to change the prefix of \fBYYFILL\fP labels (used with EOF rule or with storable states). .TP .B \fBre2c:define:YYPEEK\fP Defines generic API primitive \fBYYPEEK\fP (see the user interface section). .TP .B \fBre2c:define:YYSKIP\fP Defines generic API primitive \fBYYSKIP\fP (see the user interface section). .TP .B \fBre2c:define:YYBACKUP\fP Defines generic API primitive \fBYYBACKUP\fP (see the user interface section). .TP .B \fBre2c:define:YYBACKUPCTX\fP Defines generic API primitive \fBYYBACKUPCTX\fP (see the user interface section). .TP .B \fBre2c:define:YYRESTORE\fP Defines generic API primitive \fBYYRESTORE\fP (see the user interface section). .TP .B \fBre2c:define:YYRESTORECTX\fP Defines generic API primitive \fBYYRESTORECTX\fP (see the user interface section). .TP .B \fBre2c:define:YYRESTORETAG\fP Defines generic API primitive \fBYYRESTORETAG\fP (see the user interface section). .TP .B \fBre2c:define:YYSHIFT\fP Defines generic API primitive \fBYYSHIFT\fP (see the user interface section). .TP .B \fBre2c:define:YYSHIFTMTAG\fP Defines generic API primitive \fBYYSHIFTMTAG\fP (see the user interface section). .TP .B \fBre2c:define:YYSHIFTSTAG\fP Defines generic API primitive \fBYYSHIFTSTAG\fP (see the user interface section). .TP .B \fBre2c:define:YYSTAGN\fP Defines generic API primitive \fBYYSTAGN\fP (see the user interface section). .TP .B \fBre2c:define:YYSTAGP\fP Defines generic API primitive \fBYYSTAGP\fP (see the user interface section). .TP .B \fBre2c:define:YYMTAGN\fP Defines generic API primitive \fBYYMTAGN\fP (see the user interface section). .TP .B \fBre2c:define:YYMTAGP\fP Defines generic API primitive \fBYYMTAGP\fP (see the user interface section). .TP .B \fBre2c:flags:T\fP, \fBre2c:flags:tags\fP Same as \fB\-T \-\-tags\fP command\-line option. .TP .B \fBre2c:flags:P\fP, \fBre2c:flags:posix\-captures\fP Same as \fB\-P \-\-posix\-captures\fP command\-line option. .TP .B \fBre2c:tags:expression\fP Allows one to customize the way re2c addresses tag variables. By default re2c generates expressions of the form \fByyt\fP\&. This might be inconvenient, for example if tag variables are defined as fields in a struct. Re2c recognizes placeholder of the form \fB@@{tag}\fP or \fB@@\fP and replaces it with the actual tag name. Sigil \fB@@\fP can be redefined with \fBre2c:api:sigil\fP configuration. For example, setting \fBre2c:tags:expression = "p\->@@";\fP results in expressions of the form \fBp\->yyt\fP in the generated code. .TP .B \fBre2c:tags:prefix\fP Allows one to override the prefix of tag variables (defaults to \fByyt\fP). .TP .B \fBre2c:flags:lookahead\fP Same as inverted \fB\-\-no\-lookahead\fP command\-line option. .TP .B \fBre2c:flags:optimize\-tags\fP Same as inverted \fB\-\-no\-optimize\-tags\fP command\-line option. .TP .B \fBre2c:define:YYCONDTYPE\fP Defines \fBYYCONDTYPE\fP (see the user interface section). .TP .B \fBre2c:define:YYGETCONDITION\fP Defines API primitive \fBYYGETCONDITION\fP (see the user interface section). .TP .B \fBre2c:define:YYGETCONDITION:naked\fP Allows one to override \fBre2c:api:style\fP for \fBYYGETCONDITION\fP\&. Value \fB0\fP corresponds to free\-form API style. .TP .B \fBre2c:define:YYSETCONDITION\fP Defines API primitive \fBYYSETCONDITION\fP (see the user interface section). .TP .B \fBre2c:define:YYSETCONDITION@cond\fP Specifies the sigil used for argument substitution in \fBYYSETCONDITION\fP definition. The default value is \fB@@\fP\&. Overrides the more generic \fBre2c:api:sigil\fP configuration. .TP .B \fBre2c:define:YYSETCONDITION:naked\fP Allows one to override \fBre2c:api:style\fP for \fBYYSETCONDITION\fP\&. Value \fB0\fP corresponds to free\-form API style. .TP .B \fBre2c:cond:goto\fP Allows one to customize the goto statements used with the shortcut \fB:=>\fP rules in conditions. The default value is \fBgoto @@;\fP\&. Placeholders are substituted with condition name (see \fBre2c:api;sigil\fP and \fBre2c:cond:goto@cond\fP). .TP .B \fBre2c:cond:goto@cond\fP Specifies the sigil used for argument substitution in \fBre2c:cond:goto\fP definition. The default value is \fB@@\fP\&. Overrides the more generic \fBre2c:api:sigil\fP configuration. .TP .B \fBre2c:cond:divider\fP Defines the divider for condition blocks. The default value is \fB/* *********************************** */\fP\&. Placeholders are substituted with condition name (see \fBre2c:api;sigil\fP and \fBre2c:cond:divider@cond\fP). .TP .B \fBre2c:cond:divider@cond\fP Specifies the sigil used for argument substitution in \fBre2c:cond:divider\fP definition. The default value is \fB@@\fP\&. Overrides the more generic \fBre2c:api:sigil\fP configuration. .TP .B \fBre2c:condprefix\fP Specifies the prefix used for condition labels. The default value is \fByyc_\fP\&. .TP .B \fBre2c:condenumprefix\fP Specifies the prefix used for condition identifiers. The default value is \fByyc\fP\&. .TP .B \fBre2c:define:YYGETSTATE\fP Defines API primitive \fBYYGETSTATE\fP (see the user interface section). .TP .B \fBre2c:define:YYGETSTATE:naked\fP Allows one to override \fBre2c:api:style\fP for \fBYYGETSTATE\fP\&. Value \fB0\fP corresponds to free\-form API style. .TP .B \fBre2c:define:YYSETSTATE\fP Defines API primitive \fBYYSETSTATE\fP (see the user interface section). .TP .B \fBre2c:define:YYSETSTATE@state\fP Specifies the sigil used for argument substitution in \fBYYSETSTATE\fP definition. The default value is \fB@@\fP\&. Overrides the more generic \fBre2c:api:sigil\fP configuration. .TP .B \fBre2c:define:YYSETSTATE:naked\fP Allows one to override \fBre2c:api:style\fP for \fBYYSETSTATE\fP\&. Value \fB0\fP corresponds to free\-form API style. .TP .B \fBre2c:state:abort\fP If set to a positive integer value, changes the form of the \fBYYGETSTATE\fP switch: instead of using default case to jump to the beginning of the lexer block, a \fB\-1\fP case is used, and the default case aborts the program. .TP .B \fBre2c:state:nextlabel\fP With storable states, allows one to control if the \fBYYGETSTATE\fP block is followed by a \fByyNext\fP label (the default value is zero, which corresponds to no label). Instead of using \fByyNext\fP it is possible to use \fBre2c:startlabel\fP to force the generation of a specific start label. Instead of using labels it is often more convenient to generate \fBYYGETSTATE\fP code using \fB/*!getstate:re2c*/\fP\&. .TP .B \fBre2c:label:yyNext\fP Allows one to change the name of the \fByyNext\fP label. .TP .B \fBre2c:startlabel\fP Controls the generation of start label for the next lexer block. The default value is zero, which means that the start label is generated only if it is used. An integer value greater than zero forces the generation of start label even if it is unused by the lexer. A string value also forces start label generation and sets the label name to the specified string. This configuration applies only to the current block (it is reset to default for the next block). .TP .B \fBre2c:flags:s\fP, \fBre2c:flags:nested\-ifs\fP Same as \fB\-s \-\-nested\-ifs\fP command\-line option. .TP .B \fBre2c:flags:b\fP, \fBre2c:flags:bit\-vectors\fP Same as \fB\-b \-\-bit\-vectors\fP command\-line option. .TP .B \fBre2c:variable:yybm\fP Overrides the name of the \fByybm\fP variable. .TP .B \fBre2c:yybm:hex\fP Defaults to zero (a decimal bitmap table is generated). If set to nonzero, a hexadecimal table is generated. .TP .B \fBre2c:flags:g\fP, \fBre2c:flags:computed\-gotos\fP Same as \fB\-g \-\-computed\-gotos\fP command\-line option. .TP .B \fBre2c:cgoto:threshold\fP With \fB\-g\fP \fB\-\-computed\-gotos\fP option this value specifies the complexity threshold that triggers the generation of jump tables instead of nested \fBif\fP statements and bitmaps. The default value is \fB9\fP\&. .TP .B \fBre2c:flags:case\-ranges\fP Same as \fB\-\-case\-ranges\fP command\-line option. .TP .B \fBre2c:flags:e\fP, \fBre2c:flags:ecb\fP Same as \fB\-e \-\-ecb\fP command\-line option. .TP .B \fBre2c:flags:8\fP, \fBre2c:flags:utf\-8\fP Same as \fB\-8 \-\-utf\-8\fP command\-line option. .TP .B \fBre2c:flags:w\fP, \fBre2c:flags:wide\-chars\fP Same as \fB\-w \-\-wide\-chars\fP command\-line option. .TP .B \fBre2c:flags:x\fP, \fBre2c:flags:utf\-16\fP Same as \fB\-x \-\-utf\-16\fP command\-line option. .TP .B \fBre2c:flags:u\fP, \fBre2c:flags:unicode\fP Same as \fB\-u \-\-unicode\fP command\-line option. .TP .B \fBre2c:flags:encoding\-policy\fP Same as \fB\-\-encoding\-policy\fP command\-line option. .TP .B \fBre2c:flags:empty\-class\fP Same as \fB\-\-empty\-class\fP command\-line option. .TP .B \fBre2c:flags:case\-insensitive\fP Same as \fB\-\-case\-insensitive\fP command\-line option. .TP .B \fBre2c:flags:case\-inverted\fP Same as \fB\-\-case\-inverted\fP command\-line option. .TP .B \fBre2c:flags:i\fP, \fBre2c:flags:no\-debug\-info\fP Same as \fB\-i \-\-no\-debug\-info\fP command\-line option. .TP .B \fBre2c:indent:string\fP Specifies the string to use for indentation. The default value is \fB"\et"\fP\&. Indent string should contain only whitespace characters. To disable indentation entirely, set this configuration to empty string \fB""\fP\&. .TP .B \fBre2c:indent:top\fP Specifies the minimum amount of indentation to use. The default value is zero. The value should be a non\-negative integer number. .TP .B \fBre2c:labelprefix\fP Allows one to change the prefix of DFA state labels. The default value is \fByy\fP\&. .TP .B \fBre2c:yych:emit\fP Set this to zero to suppress the generation of \fByych\fP definition. Defaults to \fB1\fP (the definition is generated). .TP .B \fBre2c:variable:yych\fP Overrides the name of the \fByych\fP variable. .TP .B \fBre2c:yych:conversion\fP If set to nonzero, re2c automatically generates a cast to \fBYYCTYPE\fP every time \fByych\fP is read. Defaults to zero (no cast). .TP .B \fBre2c:variable:yyaccept\fP Overrides the name of the \fByyaccept\fP variable. .TP .B \fBre2c:variable:yytarget\fP Overrides the name of the \fByytarget\fP variable. .TP .B \fBre2c:variable:yystable\fP Deprecated. .TP .B \fBre2c:variable:yyctable\fP When both \fB\-c\fP \fB\-\-conditions\fP and \fB\-g\fP \fB\-\-computed\-gotos\fP are active, re2c will use this variable to generate a static jump table for \fBYYGETCONDITION\fP\&. .TP .B \fBre2c:define:YYDEBUG\fP Defines \fBYYDEBUG\fP (see the user interface section). .TP .B \fBre2c:flags:d\fP, \fBre2c:flags:debug\-output\fP Same as \fB\-d \-\-debug\-output\fP command\-line option. .TP .B \fBre2c:flags:dfa\-minimization\fP Same as \fB\-\-dfa\-minimization\fP command\-line option. .TP .B \fBre2c:flags:eager\-skip\fP Same as \fB\-\-eager\-skip\fP command\-line option. .UNINDENT .SH REGULAR EXPRESSIONS .sp re2c uses the following syntax for regular expressions: .INDENT 0.0 .IP \(bu 2 \fB"foo"\fP case\-sensitive string literal .IP \(bu 2 \fB\(aqfoo\(aq\fP case\-insensitive string literal .IP \(bu 2 \fB[a\-xyz]\fP, \fB[^a\-xyz]\fP character class (possibly negated) .IP \(bu 2 \fB\&.\fP any character except newline .IP \(bu 2 \fBR \e S\fP difference of character classes \fBR\fP and \fBS\fP .IP \(bu 2 \fBR*\fP zero or more occurrences of \fBR\fP .IP \(bu 2 \fBR+\fP one or more occurrences of \fBR\fP .IP \(bu 2 \fBR?\fP optional \fBR\fP .IP \(bu 2 \fBR{n}\fP repetition of \fBR\fP exactly \fBn\fP times .IP \(bu 2 \fBR{n,}\fP repetition of \fBR\fP at least \fBn\fP times .IP \(bu 2 \fBR{n,m}\fP repetition of \fBR\fP from \fBn\fP to \fBm\fP times .IP \(bu 2 \fB(R)\fP just \fBR\fP; parentheses are used to override precedence or for POSIX\-style submatch .IP \(bu 2 \fBR S\fP concatenation: \fBR\fP followed by \fBS\fP .IP \(bu 2 \fBR | S\fP alternative: \fBR or S\fP .IP \(bu 2 \fBR / S\fP lookahead: \fBR\fP followed by \fBS\fP, but \fBS\fP is not consumed .IP \(bu 2 \fBname\fP the regular expression defined as \fBname\fP (or literal string \fB"name"\fP in Flex compatibility mode) .IP \(bu 2 \fB{name}\fP the regular expression defined as \fBname\fP in Flex compatibility mode .IP \(bu 2 \fB@stag\fP an \fIs\-tag\fP: saves the last input position at which \fB@stag\fP matches in a variable named \fBstag\fP .IP \(bu 2 \fB#mtag\fP an \fIm\-tag\fP: saves all input positions at which \fB#mtag\fP matches in a variable named \fBmtag\fP .UNINDENT .sp Character classes and string literals may contain the following escape sequences: \fB\ea\fP, \fB\eb\fP, \fB\ef\fP, \fB\en\fP, \fB\er\fP, \fB\et\fP, \fB\ev\fP, \fB\e\e\fP, octal escapes \fB\eooo\fP and hexadecimal escapes \fB\exhh\fP, \fB\euhhhh\fP and \fB\eUhhhhhhhh\fP\&. .SH EOF HANDLING .sp Re2c provides a number of ways to handle end\-of\-input situation. Which way to use depends on the complexity of regular expressions, performance considerations, the need for input buffering and various other factors. EOF handling is probably the most complex part of re2c user interface \-\-\- it definitely requires a bit of understanding of how the generated lexer works. But in return is allows the user to customize lexer for a particular environment and avoid the unnecessary overhead of generic methods when a simpler method is sufficient. Roughly speaking, there are four main methods: .INDENT 0.0 .IP \(bu 2 using sentinel symbol (simple and efficient, but limited) .IP \(bu 2 bounds checking with padding (generic, but complex) .IP \(bu 2 EOF rule: a combination of sentinel symbol and bounds checking (generic and simple, can be more or less efficient than bounds checking with padding depending on the grammar) .IP \(bu 2 using generic API (user\-defined, so may be incorrect ;]) .UNINDENT .SS Using sentinel symbol .sp This is the simplest and the most efficient method. It is applicable in cases when the input is small enough to fit into a continuous memory buffer and there is a natural "sentinel" symbol \-\-\- a code unit that is not allowed by any of the regular expressions in grammar (except possibly as a terminating character). Sentinel symbol never appears in well\-formed input, therefore it can be appended at the end of input and used as a stop signal by the lexer. A good example of such input is a null\-terminated C\-string, provided that the grammar does not allow \fBNULL\fP in the middle of lexemes. Sentinel method is very efficient, because the lexer does not need to perform any additional checks for the end of input \-\-\- it comes naturally as a part of processing the next character. It is very important that the sentinel symbol is not allowed in the middle of the rule \-\-\- otherwise on some inputs the lexer may read past the end of buffer and crash or cause memory corruption. Re2c verifies this automatically. Use \fBre2c:sentinel\fP configuration to specify which sentinel symbol is used. .sp Below is an example of using sentinel method. Configuration \fBre2c:yyfill:enable = 0;\fP suppresses generation of end\-of\-input checks and \fBYYFILL\fP calls. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import "testing" // expect a null\-terminated string func lex(str string) int { var cursor int count := 0 loop: /*!re2c re2c:yyfill:enable = 0; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; * { return \-1 } [\ex00] { return count } [a\-z]+ { count += 1; goto loop } [ ]+ { goto loop } */ } func TestLex(t *testing.T) { var tests = []struct { res int str string }{ {0, "\e000"}, {3, "one two three\e000"}, {\-1, "f0ur\e000"}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res := lex(x.str) if res != x.res { t.Errorf("got %d, want %d", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .SS Bounds checking with padding .sp Bounds checking is a generic method: it can be used with any input grammar. The basic idea is simple: we need to check for the end of input before reading the next input character. However, if implemented in a straightforward way, this would be quite inefficient: checking on each input character would cause a major slowdown. Re2c avoids slowdown by generating checks only in certain key states of the lexer, and letting it run without checks in\-between the key states. More precisely, re2c computes strongly connected components (SCCs) of the underlying DFA (which roughly correspond to loops), and generates only a few checks per each SCC (usually just one, but in general enough to make the SCC acyclic). The check is of the form \fB(YYLIMIT \- YYCURSOR) < n\fP, where \fBn\fP is the maximal length of a simple path in the corresponding SCC. If this condiiton is true, the lexer calls \fBYYFILL(n)\fP, which must either supply at least \fBn\fP input characters, or do not return. When the lexer continues after the check, it is certain that the next \fBn\fP characters can be read safely without checks. .sp This approach reduces the number of checks significantly (and makes the lexer much faster as a result), but it has a downside. Since the lexer checks for multiple characters at once, it may end up in a situation when there are a few remaining input characters (less than \fBn\fP) corresponding to a short path in the SCC, but the lexer cannot proceed because of the check, and \fBYYFILL\fP cannot supply more character because it is the end of input. To solve this problem, re2c requires that additional padding consisting of fake characters is appended at the end of input. The length of padding should be \fBYYMAXFILL\fP, which equals to the maximum \fBn\fP parameter to \fBYYFILL\fP and must be generated by re2c using \fB/*!max:re2c*/\fP directive. The fake characters should not form a valid lexeme suffix, otherwise the lexer may be fooled into matching a fake lexeme. Usually it\(aqs a good idea to use \fBNULL\fP characters for padding. .sp Below is an example of using bounds checking with padding. Note that the grammar rule for single\-quoted strings allows arbitrary symbols in the middle of lexeme, so there is no natural sentinel in the grammar. Strings like \fB"aha\e0ha"\fP are perfectly valid, but ill\-formed strings like \fB"aha\e0\fP are also possible and shouldn’t crash the lexer. In this example we do not use buffer refilling, therefore \fBYYFILL\fP definition simply returns an error. Note that \fBYYFILL\fP will only be called after the lexer reaches padding, because only then will the check condition be satisfied. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import ( "strings" "testing" ) /*!max:re2c*/ // Expects YYMAXFILL\-padded string. func lex(str string) int { var cursor int limit := len(str) count := 0 loop: /*!re2c re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; re2c:define:YYLESSTHAN = "limit \- cursor < @@{len}"; re2c:define:YYFILL = "return \-1"; * { return \-1 } [\ex00] { return count } [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq] { count += 1; goto loop } [ ]+ { goto loop } */ } // Pad string with YYMAXFILL zeroes at the end. func pad(str string) string { return str + strings.Repeat("\e000", YYMAXFILL) } func TestLex(t *testing.T) { var tests = []struct { res int str string }{ {0, ""}, {3, "\(aqqu\e000tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq "}, {\-1, "\(aqunterminated\e\e\(aq"}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res := lex(pad(x.str)) if res != x.res { t.Errorf("got %d, want %d", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .SS EOF rule .sp EOF rule \fB$\fP was introduced in version 1.2. It is a hybrid approach that tries to take the best of both worlds: simplicity and efficiency of the sentinel method combined with the generality of bounds\-checking method. The idea is to appoint an arbitrary symbol to be the sentinel, and only perform further bounds checking if the sentinel symbol matches (more precisely, if the symbol class that contains it matches). The check is of the form \fBYYLIMIT <= YYCURSOR\fP\&. If this condition is not satisfied, then the sentinel is just an ordinary input character and the lexer continues. Otherwise this is a real sentinel, and the lexer calls \fBYYFILL()\fP\&. If \fBYYFILL\fP returns zero, the lexer assumes that it has more input and tries to re\-match. Otherwise \fBYYFILL\fP returns non\-zero and the lexer knows that it has reached the end of input. At this point there are three possibilities. First, it might have already matched a shorter lexeme \-\-\- in this case it just rolls back to the last accepting state. Second, it might have consumed some characters, but failed to match \-\-\- in this case it falls back to default rule \fB*\fP\&. Finally, it might be in the initial state \-\-\- in this (and only this!) case it matches EOF rule \fB$\fP\&. .sp Below is an example of using EOF rule. Configuration \fBre2c:yyfill:enable = 0;\fP suppresses generation of \fBYYFILL\fP calls (but not the bounds checks). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import "testing" // Expects a null\-terminated string. func lex(str string) int { var cursor, marker int limit := len(str) \- 1 // limit points at the terminating null count := 0 loop: /*!re2c re2c:yyfill:enable = 0; re2c:eof = 0; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; re2c:define:YYBACKUP = "marker = cursor"; re2c:define:YYRESTORE = "cursor = marker"; re2c:define:YYLESSTHAN = "limit <= cursor"; * { return \-1 } $ { return count } [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq] { count += 1; goto loop } [ ]+ { goto loop } */ } func TestLex(t *testing.T) { var tests = []struct { res int str string }{ {0, "\e000"}, {3, "\(aqqu\e000tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq \e000"}, {\-1, "\(aqunterminated\e\e\(aq\e000"}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res := lex(x.str) if res != x.res { t.Errorf("got %d, want %d", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .SS Using generic API .sp Generic API can be used with any of the above methods. It also allows one to use a user\-defined method by placing EOF checks in one of the basic primitives. Usually this is either \fBYYSKIP\fP (the check is performed when advancing to the next input character), or \fBYYPEEK\fP (the check is performed when reading the next input character). The resulting methods are inefficient, as they check on each input character. However, they can be useful in cases when the input cannot be buffered or padded and does not contain a sentinel character at the end. One should be cautious when using such ad\-hoc methods, as it is easy to overlook some corner cases and come up with a method that only partially works. Also it should be noted that not everything can be expressed via generic API: for example, it is impossible to reimplement the way EOF rule works (in particular, it is impossible to re\-match the character after successful \fBYYFILL\fP). .sp Below is an example of using \fBYYSKIP\fP to perform bounds checking without padding. \fBYYFILL\fP generation is suppressed using \fBre2c:yyfill:enable = 0;\fP configuration. Note that if the grammar was more complex, this method might not work in case when two rules overlap and EOF check fails after a shorter lexeme has already been matched (as it happens in our example, there are no overlapping rules). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import "testing" // Returns "fake" terminating null if cursor has reached limit. func peek(str string, cursor int, limit int) byte { if cursor >= limit { return 0 // fake null } else { return str[cursor] } } // Expects a string without terminating null. func lex(str string) int { var cursor, marker int limit := len(str) count := 0 loop: /*!re2c re2c:yyfill:enable = 0; re2c:eof = 0; re2c:define:YYCTYPE = byte; re2c:define:YYLESSTHAN = "cursor >= limit"; re2c:define:YYPEEK = "peek(str, cursor, limit)"; re2c:define:YYSKIP = "cursor += 1"; re2c:define:YYBACKUP = "marker = cursor"; re2c:define:YYRESTORE = "cursor = marker"; * { return \-1 } $ { return count } [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq] { count += 1; goto loop } [ ]+ { goto loop } */ } func TestLex(t *testing.T) { var tests = []struct { res int str string }{ {0, ""}, {3, "\(aqqu\e000tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq "}, {\-1, "\(aqunterminated\e\e\(aq"}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res := lex(x.str) if res != x.res { t.Errorf("got %d, want %d", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .SH BUFFER REFILLING .sp The need for buffering arises when the input cannot be mapped in memory all at once: either it is too large, or it comes in a streaming fashion (like reading from a socket). The usual technique in such cases is to allocate a fixed\-sized memory buffer and process input in chunks that fit into the buffer. When the current chunk is processed, it is moved out and new data is moved in. In practice it is somewhat more complex, because lexer state consists not of a single input position, but a set of interrelated posiitons: .INDENT 0.0 .IP \(bu 2 cursor: the next input character to be read (\fBYYCURSOR\fP in default API or \fBYYSKIP\fP/\fBYYPEEK\fP in generic API) .IP \(bu 2 limit: the position after the last available input character (\fBYYLIMIT\fP in default API, implicitly handled by \fBYYLESSTHAN\fP in generic API) .IP \(bu 2 marker: the position of the most recent match, if any (\fBYYMARKER\fP in default API or \fBYYBACKUP\fP/\fBYYRESTORE\fP in generic API) .IP \(bu 2 token: the start of the current lexeme (implicit in re2c API, as it is not needed for the normal lexer operation and can be defined and updated by the user) .IP \(bu 2 context marker: the position of the trailing context (\fBYYCTXMARKER\fP in default API or \fBYYBACKUPCTX\fP/\fBYYRESTORECTX\fP in generic API) .IP \(bu 2 tag variables: submatch positions (defined with \fB/*!stags:re2c*/\fP and \fB/*!mtags:re2c*/\fP directives and \fBYYSTAGP\fP/\fBYYSTAGN\fP/\fBYYMTAGP\fP/\fBYYMTAGN\fP in generic API) .UNINDENT .sp Not all these are used in every case, but if used, they must be updated by \fBYYFILL\fP\&. All active positions are contained in the segment between token and cursor, therefore everything between buffer start and token can be discarded, the segment from token and up to limit should be moved to the beginning of buffer, and the free space at the end of buffer should be filled with new data. In order to avoid frequent \fBYYFILL\fP calls it is best to fill in as many input characters as possible (even though fewer characters might suffice to resume the lexer). The details of \fBYYFILL\fP implementation are slightly different depending on which EOF handling method is used: the case of EOF rule is somewhat simpler than the case of bounds\-checking with padding. Also note that if \fB\-f \-\-storable\-state\fP option is used, \fBYYFILL\fP has slightly different semantics (desrbed in the section about storable state). .SS YYFILL with EOF rule .sp If EOF rule is used, \fBYYFILL\fP is a function\-like primitive that accepts no arguments and returns a value which is checked against zero. \fBYYFILL\fP invocation is triggered by condition \fBYYLIMIT <= YYCURSOR\fP in default API and \fBYYLESSTHAN()\fP in generic API. A non\-zero return value means that \fBYYFILL\fP has failed. A successful \fBYYFILL\fP call must supply at least one character and adjust input positions accordingly. Limit must always be set to one after the last input position in buffer, and the character at the limit position must be the sentinel symbol specified by \fBre2c:eof\fP configuration. The pictures below show the relative locations of input positions in buffer before and after \fBYYFILL\fP call (sentinel symbol is marked with \fB#\fP, and the second picture shows the case when there is not enough input to fill the whole buffer). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <\-\- shift \-\-> >\-A\-\-\-\-\-\-\-\-\-\-\-\-B\-\-\-\-\-\-\-\-\-C\-\-\-\-\-\-\-\-\-\-\-\-\-D#\-\-\-\-\-\-\-\-\-\-\-E\-> buffer token marker limit, cursor >\-A\-\-\-\-\-\-\-\-\-\-\-\-B\-\-\-\-\-\-\-\-\-C\-\-\-\-\-\-\-\-\-\-\-\-\-D\-\-\-\-\-\-\-\-\-\-\-\-E#\-> buffer, marker cursor limit token <\-\- shift \-\-> >\-A\-\-\-\-\-\-\-\-\-\-\-\-B\-\-\-\-\-\-\-\-\-C\-\-\-\-\-\-\-\-\-\-\-\-\-D#\-\-E (EOF) buffer token marker limit, cursor >\-A\-\-\-\-\-\-\-\-\-\-\-\-B\-\-\-\-\-\-\-\-\-C\-\-\-\-\-\-\-\-\-\-\-\-\-D\-\-\-E#........ buffer, marker cursor limit token .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of a program that reads input file \fBinput.txt\fP in chunks of 4096 bytes and uses EOF rule. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import ( "os" "testing" ) // Intentionally small to trigger buffer refill. const SIZE int = 16 type Input struct { file *os.File data []byte cursor int marker int token int limit int eof bool } func fill(in *Input) int { // If nothing can be read, fail. if in.eof { return 1 } // Check if at least some space can be freed. if in.token == 0 { // In real life can reallocate a larger buffer. panic("fill error: lexeme too long") } // Discard everything up to the start of the current lexeme, // shift buffer contents and adjust offsets. copy(in.data[0:], in.data[in.token:in.limit]) in.cursor \-= in.token in.marker \-= in.token in.limit \-= in.token in.token = 0 // Read new data (as much as possible to fill the buffer). n, _ := in.file.Read(in.data[in.limit:SIZE]) in.limit += n in.data[in.limit] = 0 // If read less than expected, this is the end of input. in.eof = in.limit < SIZE // If nothing has been read, fail. if n == 0 { return 1 } return 0 } func lex(in *Input) int { count := 0 loop: in.token = in.cursor /*!re2c re2c:eof = 0; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "in.data[in.cursor]"; re2c:define:YYSKIP = "in.cursor += 1"; re2c:define:YYBACKUP = "in.marker = in.cursor"; re2c:define:YYRESTORE = "in.cursor = in.marker"; re2c:define:YYLESSTHAN = "in.limit <= in.cursor"; re2c:define:YYFILL = "fill(in) == 0"; * { return \-1 } $ { return count } [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq] { count += 1; goto loop } [ ]+ { goto loop } */ } // Prepare a file with the input text and run the lexer. func test(data string) (result int) { tmpfile := "input.txt" f, _ := os.Create(tmpfile) f.WriteString(data) f.Seek(0, 0) defer func() { if r := recover(); r != nil { result = \-2 } f.Close() os.Remove(tmpfile) }() in := &Input{ file: f, data: make([]byte, SIZE+1), cursor: SIZE, marker: SIZE, token: SIZE, limit: SIZE, eof: false, } return lex(in) } func TestLex(t *testing.T) { var tests = []struct { res int str string }{ {0, ""}, {2, "\(aqone\(aq \(aqtwo\(aq"}, {3, "\(aqqu\e000tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq "}, {\-1, "\(aqunterminated\e\e\(aq"}, {\-2, "\(aqloooooooooooong\(aq"}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res := test(x.str) if res != x.res { t.Errorf("got %d, want %d", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .SS YYFILL with padding .sp In the default case (when EOF rule is not used) \fBYYFILL\fP is a function\-like primitive that accepts a single argument and does not return any value. \fBYYFILL\fP invocation is triggered by condition \fB(YYLIMIT \- YYCURSOR) < n\fP in default API and \fBYYLESSTHAN(n)\fP in generic API. The argument passed to \fBYYFILL\fP is the minimal number of characters that must be supplied. If it fails to do so, \fBYYFILL\fP must not return to the lexer (for that reason it is best implemented as a macro that returns from the calling function on failure). In case of a successful \fBYYFILL\fP invocation the limit position must be set either to one after the last input position in buffer, or to the end of \fBYYMAXFILL\fP padding (in case \fBYYFILL\fP has successfully read at least \fBn\fP characters, but not enough to fill the entire buffer). The pictures below show the relative locations of input positions in buffer before and after \fBYYFILL\fP invocation (\fBYYMAXFILL\fP padding on the second picture is marked with \fB#\fP symbols). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <\-\- shift \-\-> <\-\- need \-\-> >\-A\-\-\-\-\-\-\-\-\-\-\-\-B\-\-\-\-\-\-\-\-\-C\-\-\-\-\-D\-\-\-\-\-\-\-E\-\-\-F\-\-\-\-\-\-\-\-G\-> buffer token marker cursor limit >\-A\-\-\-\-\-\-\-\-\-\-\-\-B\-\-\-\-\-\-\-\-\-C\-\-\-\-\-D\-\-\-\-\-\-\-E\-\-\-F\-\-\-\-\-\-\-\-G\-> buffer, marker cursor limit token <\-\- shift \-\-> <\-\- need \-\-> >\-A\-\-\-\-\-\-\-\-\-\-\-\-B\-\-\-\-\-\-\-\-\-C\-\-\-\-\-D\-\-\-\-\-\-\-E\-F (EOF) buffer token marker cursor limit >\-A\-\-\-\-\-\-\-\-\-\-\-\-B\-\-\-\-\-\-\-\-\-C\-\-\-\-\-D\-\-\-\-\-\-\-E\-F############### buffer, marker cursor limit token <\- YYMAXFILL \-> .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of a program that reads input file \fBinput.txt\fP in chunks of 4096 bytes and uses bounds\-checking with padding. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import ( "fmt" "os" "testing" ) /*!max:re2c*/ // Intentionally small to trigger buffer refill. const SIZE int = 16 type Input struct { file *os.File data []byte cursor int marker int token int limit int eof bool } func fill(in *Input, need int) int { // End of input has already been reached, nothing to do. if in.eof { return \-1 // Error: unexpected EOF } // Check if after moving the current lexeme to the beginning // of buffer there will be enough free space. if SIZE\-(in.cursor\-in.token) < need { return \-2 // Error: lexeme too long } // Discard everything up to the start of the current lexeme, // shift buffer contents and adjust offsets. copy(in.data[0:], in.data[in.token:in.limit]) in.cursor \-= in.token in.marker \-= in.token in.limit \-= in.token in.token = 0 // Read new data (as much as possible to fill the buffer). n, _ := in.file.Read(in.data[in.limit:SIZE]) in.limit += n // If read less than expected, this is the end of input. in.eof = in.limit < SIZE // If end of input, add padding so that the lexer can read // the remaining characters at the end of buffer. if in.eof { for i := 0; i < YYMAXFILL; i += 1 { in.data[in.limit+i] = 0 } in.limit += YYMAXFILL } return 0 } func lex(in *Input) int { count := 0 loop: in.token = in.cursor /*!re2c re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "in.data[in.cursor]"; re2c:define:YYSKIP = "in.cursor += 1"; re2c:define:YYBACKUP = "in.marker = in.cursor"; re2c:define:YYRESTORE = "in.cursor = in.marker"; re2c:define:YYLESSTHAN = "in.limit\-in.cursor < @@{len}"; re2c:define:YYFILL = "if r := fill(in, @@{len}); r != 0 { return r }"; * { return \-1 } [\ex00] { return count } [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq] { count += 1; goto loop } [ ]+ { goto loop } */ } // Prepare a file with the input text and run the lexer. func test(data string) (result int) { tmpfile := "input.txt" f, _ := os.Create(tmpfile) f.WriteString(data) f.Seek(0, 0) defer func() { if r := recover(); r != nil { fmt.Println(r) result = \-2 } f.Close() os.Remove(tmpfile) }() in := &Input{ file: f, data: make([]byte, SIZE+YYMAXFILL), cursor: SIZE, marker: SIZE, token: SIZE, limit: SIZE, eof: false, } return lex(in) } func TestLex(t *testing.T) { var tests = []struct { res int str string }{ {0, ""}, {2, "\(aqone\(aq \(aqtwo\(aq"}, {3, "\(aqqu\e000tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq "}, {\-1, "\(aqunterminated\e\e\(aq"}, {\-2, "\(aqloooooooooooong\(aq"}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res := test(x.str) if res != x.res { t.Errorf("got %d, want %d", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .SH INCLUDE FILES .sp Re2c allows one to include other files using directive \fB/*!include:re2c FILE */\fP, where \fBFILE\fP is the name of file to be included. Re2c looks for included files in the directory of the including file and in include locations, which can be specified with \fB\-I\fP option. Re2c include directive works in the same way as C/C++ \fB#include\fP: the contents of \fBFILE\fP are copy\-pasted verbatim in place of the directive. Include files may have further includes of their own. Re2c provides some predefined include files that can be found in the \fBinclude/\fP subdirectory of the project. These files contain definitions that can be useful to other projects (such as Unicode categories) and form something like a standard library for re2c. Here is an example: .SS Include file (definitions.go) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C const ( ResultOk = iota ResultFail ) /*!re2c number = [1\-9][0\-9]*; */ .ft P .fi .UNINDENT .UNINDENT .SS Input file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go \-c $INPUT \-o $OUTPUT \-i package main import "testing" /*!include:re2c "definitions.go" */ func lex(str string) int { var cursor int /*!re2c re2c:yyfill:enable = 0; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; number { return ResultOk } * { return ResultFail } */ } func TestLex(t *testing.T) { if lex("123\e000") != ResultOk { t.Errorf("error") } } .ft P .fi .UNINDENT .UNINDENT .SH HEADER FILES .sp Re2c allows one to generate header file from the input \fB\&.re\fP file using option \fB\-t\fP, \fB\-\-type\-header\fP or configuration \fBre2c:flags:type\-header\fP and directives \fB/*!header:re2c:on*/\fP and \fB/*!header:re2c:off*/\fP\&. The first directive marks the beginning of header file, and the second directive marks the end of it. Everything between these directives is processed by re2c, and the generated code is written to the file specified by the \fB\-t \-\-type\-header\fP option (or \fBstdout\fP if this option was not used). Autogenerated header file may be needed in cases when re2c is used to generate definitions of constants, variables and structs that must be visible from other translation units. .sp Here is an example of generating a header file that contains definition of the lexer state with tag variables (the number variables depends on the regular grammar and is unknown to the programmer). .SS Input file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT \-i \-\-type\-header src/lexer/lexer.go package main import ( "lexer" // generated by re2c "testing" ) /*!header:re2c:on*/ package lexer type State struct { Data string Cur, Mar, /*!stags:re2c format="@@{tag}"; separator=", "; */ int } /*!header:re2c:off*/ func lex(st *lexer.State) int { /*!re2c re2c:flags:type\-header = "src/lexer/lexer.go"; re2c:yyfill:enable = 0; re2c:flags:tags = 1; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "st.Data[st.Cur]"; re2c:define:YYSKIP = "st.Cur++"; re2c:define:YYBACKUP = "st.Mar = st.Cur"; re2c:define:YYRESTORE = "st.Cur = st.Mar"; re2c:define:YYRESTORETAG = "st.Cur = @@{tag}"; re2c:define:YYSTAGP = "@@{tag} = st.Cur"; re2c:tags:expression = "st.@@{tag}"; re2c:tags:prefix = "Tag"; [x]{1,4} / [x]{3,5} { return 0 } // ambiguous trailing context * { return 1 } */ } func TestLex(t *testing.T) { st := &lexer.State{ Data: "xxxxxxxx\ex00", } if !(lex(st) == 0 && st.Cur == 4) { t.Error("failed") } } .ft P .fi .UNINDENT .UNINDENT .SS Header file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // Code generated by re2c, DO NOT EDIT. package lexer type State struct { Data string Cur, Mar, Tag1, Tag2, Tag3 int } .ft P .fi .UNINDENT .UNINDENT .SH SUBMATCH EXTRACTION .sp Re2c has two options for submatch extraction. .sp The first option is \fB\-T \-\-tags\fP\&. With this option one can use standalone tags of the form \fB@stag\fP and \fB#mtag\fP, where \fBstag\fP and \fBmtag\fP are arbitrary used\-defined names. Tags can be used anywhere inside of a regular expression; semantically they are just position markers. Tags of the form \fB@stag\fP are called s\-tags: they denote a single submatch value (the last input position where this tag matched). Tags of the form \fB#mtag\fP are called m\-tags: they denote multiple submatch values (the whole history of repetitions of this tag). All tags should be defined by the user as variables with the corresponding names. With standalone tags re2c uses leftmost greedy disambiguation: submatch positions correspond to the leftmost matching path through the regular expression. .sp The second option is \fB\-P \-\-posix\-captures\fP: it enables POSIX\-compliant capturing groups. In this mode parentheses in regular expressions denote the beginning and the end of capturing groups; the whole regular expression is group number zero. The number of groups for the matching rule is stored in a variable \fByynmatch\fP, and submatch results are stored in \fByypmatch\fP array. Both \fByynmatch\fP and \fByypmatch\fP should be defined by the user, and \fByypmatch\fP size must be at least \fB[yynmatch * 2]\fP\&. Re2c provides a directive \fB/*!maxnmatch:re2c*/\fP that defines \fBYYMAXNMATCH\fP: a constant equal to the maximal value of \fByynmatch\fP among all rules. Note that re2c implements POSIX\-compliant disambiguation: each subexpression matches as long as possible, and subexpressions that start earlier in regular expression have priority over those starting later. Capturing groups are translated into s\-tags under the hood, therefore we use the word "tag" to describe them as well. .sp With both \fB\-P \-\-posix\-captures\fP and \fBT \-\-tags\fP options re2c uses efficient submatch extraction algorithm described in the \fI\%Tagged Deterministic Finite Automata with Lookahead\fP paper. The overhead on submatch extraction in the generated lexer grows with the number of tags \-\-\- if this number is moderate, the overhead is barely noticeable. In the lexer tags are implemented using a number of tag variables generated by re2c. There is no one\-to\-one correspondence between tag variables and tags: a single variable may be reused for different tags, and one tag may require multiple variables to hold all its ambiguous values. Eventually ambiguity is resolved, and only one final variable per tag survives. When a rule matches, all its tags are set to the values of the corresponding tag variables. The exact number of tag variables is unknown to the user; this number is determined by re2c. However, tag variables should be defined by the user as a part of the lexer state and updated by \fBYYFILL\fP, therefore re2c provides directives \fB/*!stags:re2c*/\fP and \fB/*!mtags:re2c*/\fP that can be used to declare, initialize and manipulate tag variables. These directives have two optional configurations: \fBformat = "@@";\fP (specifies the template where \fB@@\fP is substituted with the name of each tag variable), and \fBseparator = "";\fP (specifies the piece of code used to join the generated pieces for different tag variables). .sp S\-tags support the following operations: .INDENT 0.0 .IP \(bu 2 save input position to an s\-tag: \fBt = YYCURSOR\fP with default API or a user\-defined operation \fBYYSTAGP(t)\fP with generic API .IP \(bu 2 save default value to an s\-tag: \fBt = NULL\fP with default API or a user\-defined operation \fBYYSTAGN(t)\fP with generic API .IP \(bu 2 copy one s\-tag to another: \fBt1 = t2\fP .UNINDENT .sp M\-tags support the following operations: .INDENT 0.0 .IP \(bu 2 append input position to an m\-tag: a user\-defined operation \fBYYMTAGP(t)\fP with both default and generic API .IP \(bu 2 append default value to an m\-tag: a user\-defined operation \fBYYMTAGN(t)\fP with both default and generic API .IP \(bu 2 copy one m\-tag to another: \fBt1 = t2\fP .UNINDENT .sp S\-tags can be implemented as scalar values (pointers or offsets). M\-tags need a more complex representation, as they need to store a sequence of tag values. The most naive and inefficient representation of an m\-tag is a list (array, vector) of tag values; a more efficient representation is to store all m\-tags in a prefix\-tree represented as array of nodes \fB(v, p)\fP, where \fBv\fP is tag value and \fBp\fP is a pointer to parent node. .sp Here is an example of using s\-tags to parse an IPv4 address. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import ( "errors" "testing" ) var eBadIP error = errors.New("bad IP") func lex(str string) (int, error) { var cursor, marker, o1, o2, o3, o4 int /*!stags:re2c format = \(aqvar @@ int\(aq; separator = "\en\et"; */ num := func(pos int, end int) int { n := 0 for ; pos < end; pos++ { n = n*10 + int(str[pos]\-\(aq0\(aq) } return n } /*!re2c re2c:flags:tags = 1; re2c:yyfill:enable = 0; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; re2c:define:YYBACKUP = "marker = cursor"; re2c:define:YYRESTORE = "cursor = marker"; re2c:define:YYSTAGP = "@@{tag} = cursor"; re2c:define:YYSTAGN = "@@{tag} = \-1"; octet = [0\-9] | [1\-9][0\-9] | [1][0\-9][0\-9] | [2][0\-4][0\-9] | [2][5][0\-5]; dot = [.]; end = [\ex00]; @o1 octet dot @o2 octet dot @o3 octet dot @o4 octet end { return num(o4, cursor\-1)+ (num(o3, o4\-1) << 8)+ (num(o2, o3\-1) << 16)+ (num(o1, o2\-1) << 24), nil } * { return 0, eBadIP } */ } func TestLex(t *testing.T) { var tests = []struct { str string res int err error }{ {"1.2.3.4\e000", 0x01020304, nil}, {"127.0.0.1\e000", 0x7f000001, nil}, {"255.255.255.255\e000", 0xffffffff, nil}, {"1.2.3.\e000", 0, eBadIP}, {"1.2.3.256\e000", 0, eBadIP}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res, err := lex(x.str) if !(res == x.res && err == x.err) { t.Errorf("got %d, want %d", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of using POSIX capturing groups to parse an IPv4 address. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import ( "errors" "testing" ) /*!maxnmatch:re2c*/ var eBadIP error = errors.New("bad IP") func lex(str string) (int, error) { var cursor, marker, yynmatch int yypmatch := make([]int, YYMAXNMATCH*2) /*!stags:re2c format = \(aqvar @@ int\(aq; separator = "\en\et"; */ num := func(pos int, end int) int { n := 0 for ; pos < end; pos++ { n = n*10 + int(str[pos]\-\(aq0\(aq) } return n } /*!re2c re2c:flags:posix\-captures = 1; re2c:yyfill:enable = 0; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; re2c:define:YYBACKUP = "marker = cursor"; re2c:define:YYRESTORE = "cursor = marker"; re2c:define:YYSTAGP = "@@{tag} = cursor"; re2c:define:YYSTAGN = "@@{tag} = \-1"; re2c:define:YYSHIFTSTAG = "@@{tag} += @@{shift}"; octet = [0\-9] | [1\-9][0\-9] | [1][0\-9][0\-9] | [2][0\-4][0\-9] | [2][5][0\-5]; dot = [.]; end = [\ex00]; (octet) dot (octet) dot (octet) dot (octet) end { if yynmatch != 5 { panic("expected 5 submatch groups") } return num(yypmatch[8], yypmatch[9])+ (num(yypmatch[6], yypmatch[7]) << 8)+ (num(yypmatch[4], yypmatch[5]) << 16)+ (num(yypmatch[2], yypmatch[3]) << 24), nil } * { return 0, eBadIP } */ } func TestLex(t *testing.T) { var tests = []struct { str string res int err error }{ {"1.2.3.4\e000", 0x01020304, nil}, {"127.0.0.1\e000", 0x7f000001, nil}, {"255.255.255.255\e000", 0xffffffff, nil}, {"1.2.3.\e000", 0, eBadIP}, {"1.2.3.256\e000", 0, eBadIP}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res, err := lex(x.str) if !(res == x.res && err == x.err) { t.Errorf("got %d, want %d", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of using m\-tags to parse a semicolon\-separated sequence of words (C++). Tag variables are stored in a tree that is packed in a vector. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT package main import ( "reflect" "testing" ) const ( mtagRoot int = \-1 mtagNil int = \-2 ) type mtagElem struct { val int pred int } type mtagTrie = []mtagElem func createTrie(capacity int) mtagTrie { return make([]mtagElem, 0, capacity) } func mtag(trie *mtagTrie, tag int, val int) int { *trie = append(*trie, mtagElem{val, tag}) return len(*trie) \- 1 } // Recursively unwind both tag histories and consruct submatches. func unwind(trie mtagTrie, x int, y int, str string) []string { if x == mtagRoot && y == mtagRoot { return []string{} } else if x == mtagRoot || y == mtagRoot { panic("tag histories have different length") } else { xval := trie[x].val yval := trie[y].val ss := unwind(trie, trie[x].pred, trie[y].pred, str) // Either both tags should be nil, or none of them. if xval == mtagNil && yval == mtagNil { return ss } else if xval == mtagNil || yval == mtagNil { panic("tag histories positive/negative tag mismatch") } else { s := str[xval:yval] return append(ss, s) } } } func lex(str string) []string { var cursor, marker int trie := createTrie(256) x := mtagRoot y := mtagRoot /*!mtags:re2c format = "@@ := mtagRoot"; separator = "\en\et"; */ /*!re2c re2c:flags:tags = 1; re2c:yyfill:enable = 0; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; re2c:define:YYBACKUP = "marker = cursor"; re2c:define:YYRESTORE = "cursor = marker"; re2c:define:YYMTAGP = "@@{tag} = mtag(&trie, @@{tag}, cursor)"; re2c:define:YYMTAGN = "@@{tag} = mtag(&trie, @@{tag}, mtagNil)"; end = [\ex00]; (#x [a\-z]+ #y [;])* end { return unwind(trie, x, y, str) } * { return nil } */ } func TestLex(t *testing.T) { var tests = []struct { str string res []string }{ {"\e000", []string{}}, {"one;two;three;\e000", []string{"one", "two", "three"}}, {"one;two\e000", nil}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { res := lex(x.str) if !reflect.DeepEqual(res, x.res) { t.Errorf("got %v, want %v", res, x.res) } }) } } .ft P .fi .UNINDENT .UNINDENT .SH STORABLE STATE .sp With \fB\-f\fP \fB\-\-storable\-state\fP option re2c generates a lexer that can store its current state, return to the caller, and later resume operations exactly where it left off. The default mode of operation in re2c is a "pull" model, in which the lexer "pulls" more input whenever it needs it. This may be unacceptable in cases when the input becomes available piece by piece (for example, if the lexer is invoked by the parser, or if the lexer program communicates via a socket protocol with some other program that must wait for a reply from the lexer before it transmits the next message). Storable state feature is intended exactly for such cases: it allows one to generate lexers that work in a "push" model. When the lexer needs more input, it stores its state and returns to the caller. Later, when more input becomes available, the caller resumes the lexer exactly where it stopped. There are a few changes necessary compared to the "pull" model: .INDENT 0.0 .IP \(bu 2 Define \fBYYSETSTATE()\fP and \fBYYGETSTATE(state)\fP promitives. .IP \(bu 2 Define \fByych\fP, \fByyaccept\fP and \fBstate\fP variables as a part of persistent lexer state. The \fBstate\fP variable should be initialized to \fB\-1\fP\&. .IP \(bu 2 \fBYYFILL\fP should return to the outer program instead of trying to supply more input. Return code should indicate that lexer needs more input. .IP \(bu 2 The outer program should recognize situations when lexer needs more input and respond appropriately. .IP \(bu 2 Use \fB/*!getstate:re2c*/\fP directive if it is necessary to execute any code before entering the lexer. .IP \(bu 2 Use configurations \fBstate:abort\fP and \fBstate:nextlabel\fP to further tweak the generated code. .UNINDENT .sp Here is an example of a "push"\-model lexer that reads input from \fBstdin\fP and expects a sequence of words separated by spaces and newlines. The lexer loops forever, waiting for more input. It can be terminated by sending a special EOF token \-\-\- a word "stop", in which case the lexer terminates successfully and prints the number of words it has seen. Abnormal termination happens in case of a syntax error, premature end of input (without the "stop" word) or in case the buffer is too small to hold a lexeme (for example, if one of the words exceeds buffer size). Premature end of input happens in case the lexer fails to read any input while being in the initial state \-\-\- this is the only case when EOF rule matches. Note that the lexer may call \fBYYFILL\fP twice before terminating (and thus require hitting \fBCtrl+D\fP a few times). First time \fBYYFILL\fP is called when the lexer expects continuation of the current greedy lexeme (either a word or a whitespace sequence). If \fBYYFILL\fP fails, the lexer knows that it has reached the end of the current lexeme and executes the corresponding semantic action. The action jumps to the beginning of the loop, the lexer enters the initial state and calls \fBYYFILL\fP once more. If it fails, the lexer matches EOF rule. (Alternatively EOF rule can be used for termination instead of a special EOF lexeme.) .SS Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go \-f $INPUT \-o $OUTPUT package main import ( "fmt" "os" "testing" ) // Intentionally small to trigger buffer refill. const SIZE int = 16 type Input struct { file *os.File data []byte cursor int marker int token int limit int state int yyaccept int } const ( lexEnd = iota lexReady lexWaitingForInput lexPacketBroken lexPacketTooBig lexCountMismatch ) func fill(in *Input) int { if in.token == 0 { // Error: no space can be freed. // In real life can reallocate a larger buffer. return lexPacketTooBig } // Discard everything up to the start of the current lexeme, // shift buffer contents and adjust offsets. copy(in.data[0:], in.data[in.token:in.limit]) in.cursor \-= in.token in.marker \-= in.token in.limit \-= in.token in.token = 0 // Read new data (as much as possible to fill the buffer). n, _ := in.file.Read(in.data[in.limit:SIZE]) in.limit += n in.data[in.limit] = 0 // append sentinel symbol return lexReady } func lex(in *Input, recv *int) int { var yych byte /*!getstate:re2c*/ loop: in.token = in.cursor /*!re2c re2c:eof = 0; re2c:define:YYPEEK = "in.data[in.cursor]"; re2c:define:YYSKIP = "in.cursor += 1"; re2c:define:YYBACKUP = "in.marker = in.cursor"; re2c:define:YYRESTORE = "in.cursor = in.marker"; re2c:define:YYLESSTHAN = "in.limit <= in.cursor"; re2c:define:YYFILL = "return lexWaitingForInput"; re2c:define:YYGETSTATE = "in.state"; re2c:define:YYSETSTATE = "in.state = @@{state}"; packet = [a\-z]+[;]; * { return lexPacketBroken } $ { return lexEnd } packet { *recv = *recv + 1; goto loop } */ } func test(packets []string) int { fname := "pipe" fw, _ := os.Create(fname); fr, _ := os.Open(fname); in := &Input{ file: fr, data: make([]byte, SIZE+1), cursor: SIZE, marker: SIZE, token: SIZE, limit: SIZE, state: \-1, } // data is zero\-initialized, no need to write sentinel var status int send := 0 recv := 0 loop: for { status = lex(in, &recv) if status == lexEnd { if send != recv { status = lexCountMismatch } break loop } else if status == lexWaitingForInput { if send < len(packets) { fw.WriteString(packets[send]) send += 1 } status = fill(in) if status != lexReady { break loop } } else if status == lexPacketBroken { break loop } else { panic("unexpected status") } } fr.Close() fw.Close() os.Remove(fname) return status } func TestLex(t *testing.T) { var tests = []struct { status int packets []string }{ {lexEnd, []string{}}, {lexEnd, []string{"zero;", "one;", "two;", "three;", "four;"}}, {lexPacketBroken, []string{"??;"}}, {lexPacketTooBig, []string{"looooooooooooong;"}}, } for i, x := range tests { t.Run(fmt.Sprintf("%d", i), func(t *testing.T) { status := test(x.packets) if status != x.status { t.Errorf("got %d, want %d", status, x.status) } }) } } .ft P .fi .UNINDENT .UNINDENT .SH REUSABLE BLOCKS .sp Reuse mode is enabled with the \fB\-r \-\-reusable\fP option. In this mode re2c allows one to reuse definitions, configurations and rules specified by a \fB/*!rules:re2c*/\fP block in subsequent \fB/*!use:re2c*/\fP blocks. As of re2c\-1.2 it is possible to mix such blocks with normal \fB/*!re2c*/\fP blocks; prior to that re2c expects a single rules\-block followed by use\-blocks (normal blocks are disallowed). Use\-blocks can have additional definitions, configurations and rules: they are merged to those specified by the rules\-block. A very common use case for \fB\-r \-\-reusable\fP option is a lexer that supports multiple input encodings: lexer rules are defined once and reused multiple times with encoding\-specific configurations, such as \fBre2c:flags:utf\-8\fP\&. .sp Below is an example of a multi\-encoding lexer: it reads a phrase with Unicode math symbols and accepts input either in UTF8 or in UT32. Note that the \fB\-\-input\-encoding utf8\fP option allows us to write UTF8\-encoded symbols in the regular expressions; without this option re2c would parse them as a plain ASCII byte sequnce (and we would have to use hexadecimal escape sequences). .SS Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go $INPUT \-o $OUTPUT \-r \-\-input\-encoding utf8 package main import "testing" /*!rules:re2c re2c:yyfill:enable = 0; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; re2c:define:YYBACKUP = "marker = cursor"; re2c:define:YYRESTORE = "cursor = marker"; "∀x ∃y: p(x, y)" { return 0; } * { return 1; } */ func lexUTF8(str []uint8) int { var cursor, marker int /*!use:re2c re2c:flags:8 = 1; re2c:define:YYCTYPE = uint8; */ } func lexUTF32(str []uint32) int { var cursor, marker int /*!use:re2c re2c:flags:u = 1; re2c:define:YYCTYPE = uint32; */ } func TestLexUTF8(t *testing.T) { s_utf8 := []uint8{ 0xe2, 0x88, 0x80, 0x78, 0x20, 0xe2, 0x88, 0x83, 0x79, 0x3a, 0x20, 0x70, 0x28, 0x78, 0x2c, 0x20, 0x79, 0x29}; if lexUTF8(s_utf8) != 0 { t.Errorf("utf8 failed") } } func TestLexUTF32(t *testing.T) { s_utf32 := []uint32{ 0x00002200, 0x00000078, 0x00000020, 0x00002203, 0x00000079, 0x0000003a, 0x00000020, 0x00000070, 0x00000028, 0x00000078, 0x0000002c, 0x00000020, 0x00000079, 0x00000029}; if lexUTF32(s_utf32) != 0 { t.Errorf("utf32 failed") } } .ft P .fi .UNINDENT .UNINDENT .SH ENCODING SUPPORT .sp \fBre2c\fP supports the following encodings: ASCII (default), EBCDIC (\fB\-e\fP), UCS\-2 (\fB\-w\fP), UTF\-16 (\fB\-x\fP), UTF\-32 (\fB\-u\fP) and UTF\-8 (\fB\-8\fP). See also inplace configuration \fBre2c:flags\fP\&. .sp The following concepts should be clarified when talking about encodings. A code point is an abstract number that represents a single symbol. A code unit is the smallest unit of memory, which is used in the encoded text (it corresponds to one character in the input stream). One or more code units may be needed to represent a single code point, depending on the encoding. In a fixed\-length encoding, each code point is represented with an equal number of code units. In variable\-length encodings, different code points can be represented with different number of code units. .INDENT 0.0 .IP \(bu 2 ASCII is a fixed\-length encoding. Its code space includes 0x100 code points, from 0 to 0xFF. A code point is represented with exactly one 1\-byte code unit, which has the same value as the code point. The size of \fBYYCTYPE\fP must be 1 byte. .IP \(bu 2 EBCDIC is a fixed\-length encoding. Its code space includes 0x100 code points, from 0 to 0xFF. A code point is represented with exactly one 1\-byte code unit, which has the same value as the code point. The size of \fBYYCTYPE\fP must be 1 byte. .IP \(bu 2 UCS\-2 is a fixed\-length encoding. Its code space includes 0x10000 code points, from 0 to 0xFFFF. One code point is represented with exactly one 2\-byte code unit, which has the same value as the code point. The size of \fBYYCTYPE\fP must be 2 bytes. .IP \(bu 2 UTF\-16 is a variable\-length encoding. Its code space includes all Unicode code points, from 0 to 0xD7FF and from 0xE000 to 0x10FFFF. One code point is represented with one or two 2\-byte code units. The size of \fBYYCTYPE\fP must be 2 bytes. .IP \(bu 2 UTF\-32 is a fixed\-length encoding. Its code space includes all Unicode code points, from 0 to 0xD7FF and from 0xE000 to 0x10FFFF. One code point is represented with exactly one 4\-byte code unit. The size of \fBYYCTYPE\fP must be 4 bytes. .IP \(bu 2 UTF\-8 is a variable\-length encoding. Its code space includes all Unicode code points, from 0 to 0xD7FF and from 0xE000 to 0x10FFFF. One code point is represented with a sequence of one, two, three, or four 1\-byte code units. The size of \fBYYCTYPE\fP must be 1 byte. .UNINDENT .sp In Unicode, values from range 0xD800 to 0xDFFF (surrogates) are not valid Unicode code points. Any encoded sequence of code units that would map to Unicode code points in the range 0xD800\-0xDFFF, is ill\-formed. The user can control how \fBre2c\fP treats such ill\-formed sequences with the \fB\-\-encoding\-policy \fP switch. .sp For some encodings, there are code units that never occur in a valid encoded stream (e.g., 0xFF byte in UTF\-8). If the generated scanner must check for invalid input, the only correct way to do so is to use the default rule (\fB*\fP). Note that the full range rule (\fB[^]\fP) won\(aqt catch invalid code units when a variable\-length encoding is used (\fB[^]\fP means "any valid code point", whereas the default rule (\fB*\fP) means "any possible code unit"). .SH START CONDITIONS .sp Conditions are enabled with \fB\-c\fP \fB\-\-conditions\fP\&. This option allows one to encode multiple interrelated lexers within the same re2c block. .sp Each lexer corresponds to a single condition. It starts with a label of the form \fByyc_name\fP, where \fBname\fP is condition name and \fByyc\fP prefix can be adjusted with configuration \fBre2c:condprefix\fP\&. Different lexers are separated with a comment \fB/* *********************************** */\fP which can be adjusted with configuration \fBre2c:cond:divider\fP\&. .sp Furthermore, each condition has a unique identifier of the form \fByycname\fP, where \fBname\fP is condition name and \fByyc\fP prefix can be adjusted with configuration \fBre2c:condenumprefix\fP\&. Identifiers have the type \fBYYCONDTYPE\fP and should be generated with \fB/*!types:re2c*/\fP directive or \fB\-t\fP \fB\-\-type\-header\fP option. Users shouldn\(aqt define these identifiers manually, as the order of conditions is not specified. .sp Before all conditions re2c generates entry code that checks the current condition identifier and transfers control flow to the start label of the active condition. After matching some rule of this condition, lexer may either transfer control flow back to the entry code (after executing the associated action and optionally setting another condition with \fB=>\fP), or use \fB:=>\fP shortcut and transition directly to the start label of another condition (skipping the action and the entry code). Configuration \fBre2c:cond:goto\fP allows one to change the default behavior. .sp Syntactically each rule must be preceded with a list of comma\-separated condition names or a wildcard \fB*\fP enclosed in angle brackets \fB<\fP and \fB>\fP\&. Wildcard means "any condition" and is semantically equivalent to listing all condition names. Here \fBregexp\fP is a regular expression, \fBdefault\fP refers to the default rule \fB*\fP, and \fBaction\fP is a block of code. .INDENT 0.0 .IP \(bu 2 \fB regexp\-or\-default action\fP .IP \(bu 2 \fB regexp\-or\-default => condition action\fP .IP \(bu 2 \fB regexp\-or\-default :=> condition\fP .UNINDENT .sp Rules with an exclamation mark \fB!\fP in front of condition list have a special meaning: they have no regular expression, and the associated action is merged as an entry code to actions of normal rules. This might be a convenient place to peform a routine task that is common to all rules. .INDENT 0.0 .IP \(bu 2 \fB action\fP .UNINDENT .sp Another special form of rules with an empty condition list \fB<>\fP and no regular expression allows one to specify an "entry condition" that can be used to execute code before entering the lexer. It is semantically equivalent to a condition with number zero, name \fB0\fP and an empty regular expression. .INDENT 0.0 .IP \(bu 2 \fB<> action\fP .IP \(bu 2 \fB<> => condition action\fP .IP \(bu 2 \fB<> :=> condition\fP .UNINDENT .SS Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C //go:generate re2go \-c $INPUT \-o $OUTPUT \-i package main import ( "errors" "testing" ) var ( eSyntax = errors.New("syntax error") eOverflow = errors.New("overflow error") ) /*!types:re2c*/ const u32Limit uint64 = 1<<32 func parse_u32(str string) (uint32, error) { var cursor, marker int result := uint64(0) cond := yycinit add_digit := func(base uint64, offset byte) { result = result * base + uint64(str[cursor\-1] \- offset) if result >= u32Limit { result = u32Limit } } /*!re2c re2c:yyfill:enable = 0; re2c:define:YYCTYPE = byte; re2c:define:YYPEEK = "str[cursor]"; re2c:define:YYSKIP = "cursor += 1"; re2c:define:YYSHIFT = "cursor += @@{shift}"; re2c:define:YYBACKUP = "marker = cursor"; re2c:define:YYRESTORE = "cursor = marker"; re2c:define:YYGETCONDITION = "cond"; re2c:define:YYSETCONDITION = "cond = @@"; <*> * { return 0, eSyntax } \(aq0b\(aq / [01] :=> bin "0" :=> oct "" / [1\-9] :=> dec \(aq0x\(aq / [0\-9a\-fA\-F] :=> hex "\ex00" { if result < u32Limit { return uint32(result), nil } else { return 0, eOverflow } } [01] { add_digit(2, \(aq0\(aq); goto yyc_bin } [0\-7] { add_digit(8, \(aq0\(aq); goto yyc_oct } [0\-9] { add_digit(10, \(aq0\(aq); goto yyc_dec } [0\-9] { add_digit(16, \(aq0\(aq); goto yyc_hex } [a\-f] { add_digit(16, \(aqa\(aq\-10); goto yyc_hex } [A\-F] { add_digit(16, \(aqA\(aq\-10); goto yyc_hex } */ } func TestLex(t *testing.T) { var tests = []struct { num uint32 str string err error }{ {1234567890, "1234567890\e000", nil}, {13, "0b1101\e000", nil}, {0x7fe, "0x007Fe\e000", nil}, {0644, "0644\e000", nil}, {0, "9999999999\e000", eOverflow}, {0, "123??\e000", eSyntax}, } for _, x := range tests { t.Run(x.str, func(t *testing.T) { num, err := parse_u32(x.str) if !(num == x.num && err == x.err) { t.Errorf("got %d, want %d", num, x.num) } }) } } .ft P .fi .UNINDENT .UNINDENT .SH SKELETON PROGRAMS .sp With the \fB\-S, \-\-skeleton\fP option, re2c ignores all non\-re2c code and generates a self\-contained C program that can be further compiled and executed. The program consists of lexer code and input data. For each constructed DFA (block or condition) re2c generates a standalone lexer and two files: an \fB\&.input\fP file with strings derived from the DFA and a \fB\&.keys\fP file with expected match results. The program runs each lexer on the corresponding \fB\&.input\fP file and compares results with the expectations. Skeleton programs are very useful for a number of reasons: .INDENT 0.0 .IP \(bu 2 They can check correctness of various re2c optimizations (the data is generated early in the process, before any DFA transformations have taken place). .IP \(bu 2 Generating a set of input data with good coverage may be useful for both testing and benchmarking. .IP \(bu 2 Generating self\-contained executable programs allows one to get minimized test cases (the original code may be large or have a lot of dependencies). .UNINDENT .sp The difficulty with generating input data is that for all but the most trivial cases the number of possible input strings is too large (even if the string length is limited). Re2c solves this difficulty by generating sufficiently many strings to cover almost all DFA transitions. It uses the following algorithm. First, it constructs a skeleton of the DFA. For encodings with 1\-byte code unit size (such as ASCII, UTF\-8 and EBCDIC) skeleton is just an exact copy of the original DFA. For encodings with multibyte code units skeleton is a copy of DFA with certain transitions omitted: namely, re2c takes at most 256 code units for each disjoint continuous range that corresponds to a DFA transition. The chosen values are evenly distributed and include range bounds. Instead of trying to cover all possible paths in the skeleton (which is infeasible) re2c generates sufficiently many paths to cover all skeleton transitions, and thus trigger the corresponding conditional jumps in the lexer. The algorithm implementation is limited by ~1Gb of transitions and consumes constant amount of memory (re2c writes data to file as soon as it is generated). .SH VISUALIZATION AND DEBUG .sp With the \fB\-D, \-\-emit\-dot\fP option, re2c does not generate code. Instead, it dumps the generated DFA in DOT format. One can convert this dump to an image of the DFA using Graphviz or another library. Note that this option shows the final DFA after it has gone through a number of optimizations and transformations. Earlier stages can be dumped with various debug options, such as \fB\-\-dump\-nfa\fP, \fB\-\-dump\-dfa\-raw\fP etc. (see the full list of options). .SH SEE ALSO .sp You can find more information about re2c at the official website: \fI\%http://re2c.org\fP\&. Similar programs are flex(1), lex(1), quex(\fI\%http://quex.sourceforge.net\fP). .SH AUTHORS .sp Re2c was originaly written by Peter Bumbulis in 1993. Since then it has been developed and maintained by multiple volunteers; mots notably, Brain Young, Marcus Boerger, Dan Nuffer and Ulya Trofimovich. .\" Generated by docutils manpage writer. .