.\" Man page generated from reStructuredText. . . .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 .. .TH "RE2C" 1 "" "" "" .SH NAME re2c \- generate fast lexical analyzers for C/C++, Go and Rust .SH SYNOPSIS .sp Note: examples are in C++ (but can be easily adapted to C). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C re2c [ OPTIONS ] [ WARNINGS ] INPUT re2go [ OPTIONS ] [ WARNINGS ] INPUT re2rust [ OPTIONS ] [ WARNINGS ] INPUT .ft P .fi .UNINDENT .UNINDENT .sp Input can be either a file or \fB\-\fP for stdin. .SH INTRODUCTION .sp re2c works as a preprocessor. It reads the input file (which is usually a program in the target language, but can be anything) and looks for blocks of code enclosed in special\-form comments. The text outside of these blocks is copied verbatim into the output file. The contents of the blocks are processed by re2c. It translates them to code in the target language and outputs the generated code in place of the block. .sp Here is an example of a small program that checks if a given string contains a decimal number: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT \-i \-\-case\-ranges #include bool lex(const char *s) { const char *YYCURSOR = s; /*!re2c re2c:yyfill:enable = 0; re2c:define:YYCTYPE = char; number = [1\-9][0\-9]*; number { return true; } * { return false; } */ } int main() { assert(lex(\(dq1234\(dq)); return 0; } .ft P .fi .UNINDENT .UNINDENT .sp In the output everything between \fB/*!re2c\fP and \fB*/\fP has been replaced with the generated code: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /* Generated by re2c */ // re2c $INPUT \-o $OUTPUT \-i \-\-case\-ranges #include bool lex(const char *s) { const char *YYCURSOR = s; { char yych; yych = *YYCURSOR; switch (yych) { case \(aq1\(aq ... \(aq9\(aq: goto yy2; default: goto yy1; } yy1: ++YYCURSOR; { return false; } yy2: yych = *++YYCURSOR; switch (yych) { case \(aq0\(aq ... \(aq9\(aq: goto yy2; default: goto yy3; } yy3: { return true; } } } int main() { assert(lex(\(dq1234\(dq)); return 0; } .ft P .fi .UNINDENT .UNINDENT .SH SYNTAX .sp A re2c program consists of a sequence of \fIblocks\fP intermixed with code in the target language. There are three main kinds of blocks: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fB/*!re2c[:] ... */\fP A \fIglobal block\fP contains definitions, configurations, directives and rules. re2c compiles regular expressions associated with each rule into a deterministic finite automaton, encodes it in the form of conditional jumps in the target language and replaces the block with the generated code. Names and configurations defined in a global block are added to the global scope and become visible to subsequent blocks. At the start of the program the global scope is initialized with command\-line \fI\%options\fP\&. The \fB:\fP part is optional: if specified, the name can be used to refer to the block in another part of the program. .TP .B \fB/*!local:re2c[:] ... */\fP A \fIlocal block\fP is like a global block, but the names and configurations in it have local scope (they do not affect other blocks). .TP .B \fB/*!rules:re2c[:] ... */\fP A \fIrules block\fP is like a local block, but it does not generate any code and is meant to be reused in other blocks. This is a way of sharing code (more details in the \fI\%reusable blocks\fP section). .UNINDENT .UNINDENT .UNINDENT .sp There are also many auxiliary blocks; see section \fI\%blocks and directives\fP for a full list of them. A block may contain the following kinds of statements: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fB = ;\fP A \fIdefinition\fP binds a name to a regular expression. Names may contain alphanumeric characters and underscore. The \fI\%regular expressions\fP section gives an overview of re2c syntax for regular expressions. Once defined, the name can be used in other regular expressions and in rules. Recursion in named definitions is not allowed, and each name should be defined before it is used. A block inherits named definitions from the global scope. Redefining a name that exists in the current scope is an error. .TP .B \fB = ;\fP A \fIconfiguration\fP allows one to change re2c behavior and customize the generated code. For a full list of configurations supported by re2c see the \fI\%configurations\fP section. Depending on a particular configuration, the value can be a keyword, a nonnegative integer number or a one\-line string which should be enclosed in double or single quotes unless it consists of alphanumeric characters. A block inherits configurations from the global scope and may redefine them or add new ones. Configurations defined inside of a block affect the whole block, even if they appear at the end of it. .TP .B \fB { }\fP A \fIrule\fP binds a regular expression to a semantic action (a block of code in the target language). If the regular expression matches, the associated semantic action is executed. If multiple rules match, the longest match takes precedence. If multiple rules match the same string, the earliest one takes precedence. There are two special rules: the default rule \fB*\fP and the end of input rule \fB$\fP\&. The default rule should always be defined, it has the lowest priority regardless of its place in the block, and it matches any code unit (not necessarily a valid character, see the \fI\%encoding support\fP section). The end of input rule should be defined if the corresponding method for \fI\%handling the end of input\fP is used. If \fI\%start conditions\fP are used, rules have more complex syntax. .TP .B \fB!;\fP A \fIdirective\fP is one of the special predefined statements. Each directive has a unique purpose. For example, the \fB!use\fP directive merges a rules block into the current one (see the \fI\%reusable blocks\fP section), and the \fB!include\fP directive allows one to include an outer file (see the \fI\%include files\fP section). .UNINDENT .UNINDENT .UNINDENT .SH PROGRAM INTERFACE .sp The generated code interfaces with the outer program with the help of \fIprimitives\fP \-\- symbolic names that can be defined as variables, functions or macros in the target language (collectively referred to as the \fBAPI\fP). The definition of primitives is left for the user: this gives them both freedom in customizing the lexer and responsibility to understand how it works. Not all primitives have to be defined \-\-\- only those used by a given program. The manual provides definitions for the most popular use cases. For a full list of primitives and their meaning see the \fI\%API primitives\fP section. .sp There are two API flavors that define the set of primitives used by re2c: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBPointer API\fP This API is based on C pointer arithmetic. It was historically the first, and for a long time the only one. It consists of pointer\-like primitives \fBYYCURSOR\fP, \fBYYMARKER\fP, \fBYYCTXMARKER\fP, \fBYYLIMIT\fP (which are normally defined as pointers of type \fBYYCTYPE*\fP) and \fBYYFILL\fP\&. This API is enabled by default for C, and it cannot be used with other backends that do not support pointer arithmetic. .TP .B \fBGeneric API\fP This API is more flexible. It consists generic operations and does not assume any particular implementation. The primitives are \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, \fBYYLESSTHAN\fP and \fBYYFILL\fP\&. For the C backend generic API is enabled with \fB\-\-api custom\fP option or \fBre2c:api = custom;\fP configuration; for Go and Rust it is enabled by default. Generic API was added in version 0.14. .UNINDENT .UNINDENT .UNINDENT .sp There are two API styles that determine the form in which the primitives should be defined: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBFree\-form\fP Free\-form style is enabled with configuration \fBre2c:api:style = free\-form;\fP\&. In this style interface primitives should be defined as free\-form pieces of code with interpolated variables of the form \fB@@{var}\fP or optionally just \fB@@\fP if there is a single variable. The set of variables is specific to each primitive. Generic API can be defined in terms of pointers \fBcursor\fP, \fBlimit\fP, \fBmarker\fP and \fBctxmarker\fP as follows: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /*!re2c re2c:define:YYPEEK = \(dq*cursor\(dq; re2c:define:YYSKIP = \(dq++cursor;\(dq; re2c:define:YYBACKUP = \(dqmarker = cursor;\(dq; re2c:define:YYRESTORE = \(dqcursor = marker;\(dq; re2c:define:YYBACKUPCTX = \(dqctxmarker = cursor;\(dq; re2c:define:YYRESTORECTX = \(dqcursor = ctxmarker;\(dq; re2c:define:YYRESTORETAG = \(dqcursor = ${tag};\(dq; re2c:define:YYLESSTHAN = \(dqlimit \- cursor < @@{len}\(dq; re2c:define:YYSTAGP = \(dq@@{tag} = cursor;\(dq; re2c:define:YYSTAGN = \(dq@@{tag} = NULL;\(dq; re2c:define:YYSHIFT = \(dqcursor += @@{shift};\(dq; re2c:define:YYSHIFTSTAG = \(dq@@{tag} += @@{shift};\(dq; */ .ft P .fi .UNINDENT .UNINDENT .nf .fi .sp .TP .B \fBFunction\-like\fP Function\-like style is enabled with configuration \fBre2c:api:style = functions;\fP\&. In this style primitives should be defined as functions or macros with parentheses, accepting the necessary arguments. For historical reasons this API style is the default for C/C++ backend. Generic API can be defined in terms of pointers \fBcursor\fP, \fBlimit\fP, \fBmarker\fP and \fBctxmarker\fP as follows: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C #define YYPEEK() *cursor #define YYSKIP() ++cursor #define YYBACKUP() marker = cursor #define YYRESTORE() cursor = marker #define YYBACKUPCTX() ctxmarker = cursor #define YYRESTORECTX() cursor = ctxmarker #define YYRESTORETAG(tag) cursor = tag #define YYLESSTHAN(len) limit \- cursor < len #define YYSTAGP(tag) tag = cursor #define YYSTAGN(tag) tag = NULL #define YYSHIFT(shift) cursor += shift #define YYSHIFTSTAG(tag, shift) tag += shift .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp For \fBYYFILL\fP definition and instructions how to customize or disable end\-of\-input checks see the \fI\%handling the end of input\fP and \fI\%buffer refilling\fP sections. .SH OPTIONS .sp Some of the options have corresponding \fI\%configurations\fP, others are global and cannot be changed after re2c starts reading the input file. Debug options generally require building re2c in debug configuration. Internal options are useful for experimenting with the algorithms used in re2c. .INDENT 0.0 .TP .B \fB\-? \-\-help \-h\fP Show help message. .TP .B \fB\-\-api \-\-input \fP Specify the API used by the generated code to interface with used\-defined code: \fBdefault\fP is the API based on pointer arithmetic (the default for C), and \fBcustom\fP is the generic API (the default for Go and Rust). .TP .B \fB\-\-bit\-vectors \-b\fP Optimize conditional jumps using bit masks. This option implies \fB\-\-nested\-ifs\fP\&. .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 \fBlow ... high\fP\&. This syntax is a C/C++ language extension that is supported by compilers like GCC, Clang and Tcc. The main advantage over using single cases is smaller generated code and faster generation time, although for some compilers like Tcc it also results in smaller binary size. This option is supported only for C. .TP .B \fB\-\-computed\-gotos \-g\fP Optimize conditional jumps using non\-standard \(dqcomputed goto\(dq 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\-\-bit\-vectors\fP\&. It is supported only for C. .TP .B \fB\-\-conditions \-\-start\-conditions \-c\fP Enable support of Flex\-like \(dqconditions\(dq: multiple interrelated lexers within one block. This is an alternative to manually specifying different re2c blocks connected with \fBgoto\fP or function calls. .TP .B \fB\-\-depfile FILE\fP Write dependency information to \fBFILE\fP in the form of a Makefile rule \fB : [include\-file ...]\fP\&. This allows one to track build dependencies in the presence of \fBinclude:re2c\fP directives, so that updating include files triggers regeneration of the output file. This option depends on the \fB\-\-output\fP option. .TP .B \fB\-\-ebcdic \-\-ecb \-e\fP Generate a lexer that reads input in EBCDIC encoding. re2c assumes that the character range is 0 \-\- 0xFF and 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 \fBmatch\-none\fP 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\-\-flex\-syntax \-F\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 with curly braces. Names without curly braces are treated as double\-quoted strings. .TP .B \fB\-\-header \-\-type\-header \-t HEADER\fP Generate a \fBHEADER\fP file. The contents of the file can be specified with directives \fBheader:re2c:on\fP and \fBheader:re2c:off\fP\&. If conditions are used the header will have a condition enum automatically appended to it (unless there is an explicit \fBconditions:re2c\fP directive). .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 \fBinclude:re2c\fP directive. re2c looks for \fBFILE\fP in the directory of the parent file and in the include locations specified with \fB\-I\fP option. .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\-\-invert\-captures\fP Invert the meaning of capturing and non\-capturing groups. By default \fB(...)\fP is capturing and \fB(! ...)\fP is non\-capturing. With this option \fB(! ...)\fP is capturing and \fB(...)\fP is non\-capturing. .TP .B \fB\-\-lang \fP Specify the output language. Supported languages are C, Go and Rust. The default is C for re2c, Go for re2go and Rust for re2rust. .TP .B \fB\-\-leftmost\-captures\fP Enable submatch extraction with leftmost greedy capturing groups. .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. The default is \fBgnu\fP\&. .TP .B \fB\-\-loop\-switch\fP Encode DFA in a form of a loop over a switch statement. Individual states are switch cases. The current state is stored in a variable \fByystate\fP\&. Transitions between states update \fByystate\fP to the case label of the destination state and \fBcontinue\fP to the head of the loop. This option is always enabled for Rust, as it has no \fBgoto\fP statement and cannot use the goto/label approach which is the default for C and Go backends. .TP .B \fB\-\-nested\-ifs \-s\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\-\-no\-debug\-info \-i\fP Do not output line directives. This may be useful when the generated code is stored in a version control system (to avoid huge autogenerated diffs on small changes). This option is on by default for Rust, as it does not have line directives. .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\-\-no\-unsafe\fP Do not generate \fBunsafe\fP wrapper over \fBYYPEEK\fP (this option is specific to Rust). For performance reasons \fBYYPEEK\fP should avoid bounds\-checking, as the lexer already performs end\-of\-input checks in a more efficient way. The user may choose to provide a safe \fBYYPEEK\fP definition, or a definition that is unsafe only in release builds, in which case the \fB\-\-no\-unsafe\fP option helps to avoid warnings about redundant \fBunsafe\fP blocks. .TP .B \fB\-\-output \-o OUTPUT\fP Specify the \fBOUTPUT\fP file. .TP .B \fB\-\-posix\-captures \-P\fP Enable submatch extraction with POSIX\-style capturing groups. .TP .B \fB\-\-reusable \-r\fP Deprecated since version 2.2 (reusable blocks are allowed by default now). .TP .B \fB\-\-skeleton \-S\fP Ignore user\-defined interface code and generate a self\-contained \(dqskeleton\(dq program. Additionally, generate input files with strings derived from the regular grammar and compressed match results that are used to verify \(dqskeleton\(dq behavior on all inputs. This option is useful for finding bugs in optimizations and code generation. This option is supported only for C. .TP .B \fB\-\-storable\-state \-f\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\fP primitives, and variables \fByych\fP, \fByyaccept\fP and \fBstate\fP should be part of the stored lexer state. .TP .B \fB\-\-tags \-T\fP Enable submatch extraction with tags. .TP .B \fB\-\-ucs2 \-\-wide\-chars \-w\fP Generate a lexer that reads UCS2\-encoded input. re2c assumes that the character range is 0 \-\- 0xFFFF and character size is 2 bytes. This option implies \fB\-\-nested\-ifs\fP\&. .TP .B \fB\-\-utf8 \-\-utf\-8 \-8\fP Generate a lexer that reads input in UTF\-8 encoding. re2c assumes that the character range is 0 \-\- 0x10FFFF and character size is 1 byte. .TP .B \fB\-\-utf16 \-\-utf\-16 \-x\fP Generate a lexer that reads UTF16\-encoded input. re2c assumes that the character range is 0 \-\- 0x10FFFF and character size is 2 bytes. This option implies \fB\-\-nested\-ifs\fP\&. .TP .B \fB\-\-utf32 \-\-unicode \-u\fP Generate a lexer that reads UTF32\-encoded input. re2c assumes that the character range is 0 \-\- 0x10FFFF and character size is 4 bytes. This option implies \fB\-\-nested\-ifs\fP\&. .TP .B \fB\-\-verbose\fP Output a short message in case of success. .TP .B \fB\-\-vernum \-V\fP Show version information in \fBMMmmpp\fP format (major, minor, patch). .TP .B \fB\-\-version \-v\fP Show version information. .TP .B \fB\-\-single\-pass \-1\fP Deprecated. Does nothing (single pass is the default now). .UNINDENT .INDENT 0.0 .TP .B \fB\-\-debug\-output \-d\fP Emit \fBYYDEBUG\fP invocations in the generated code. This is useful to trace lexer execution. .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). .TP .B \fB\-\-emit\-dot \-D\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). .UNINDENT .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 \(dqtable filling\(dq 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. .TP .B \fB\-\-no\-lookahead\fP Internal option, deprecated. It used to enable TDFA(0) algorithm. Unlike TDFA(1), TDFA(0) algorithm does not use one\-symbol lookahead. It applies register operations to the incoming transitions rather than the outgoing ones. Benchmarks showed that TDFA(0) algorithm is less efficient than TDFA(1). .TP .B \fB\-\-no\-optimize\-tags\fP Internal option: 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 \(dqglobal topological order\(dq 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, deprecated. It used to enable staDFA algorithm, which differs from TDFA in that register operations are placed in states rather than on transitions. Benchmarks showed that staDFA algorithm is less efficient than TDFA. .TP .B \fB\-\-fixed\-tags \fP Internal option: specify whether the fixed\-tag optimization should be applied to all tags (\fBall\fP), none of them (\fBnone\fP), or only those in toplevel concatenation (\fBtoplevel\fP). The default is \fBall\fP\&. \(dqFixed\(dq tags are those that are located within a fixed distance to some other tag (called \(dqbase\(dq). In such cases only the base tag needs to be tracked, and the value of the fixed tag can be computed as the value of the base tag plus a static offset. For tags that are under alternative or repetition it is also necessary to check if the base tag has a no\-match value (in that case fixed tag should also be set to no\-match, disregarding the offset). For tags in top\-level concatenation the check is not needed, because they always match. .UNINDENT .SH WARNINGS .sp Warnings can be invividually enabled, disabled and turned into an error. .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\-\-\-header\fP option or the \fBconditions: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 re2c permits 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 a dangerous and common mistake. It can be easily fixed by adding the default rule \fB*\fP which has the lowest priority, matches any code unit, and always consumes a single 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 BLOCKS AND DIRECTIVES .sp Below is the list of re2c directives (syntactic constructs that mark the beginning and end of the code that should be processed by re2c). Named blocks were added in re2c version 2.2. They are exactly the same as unnamed blocks, except that the name can be used to reference a block in other parts of the program. More information on each directive can be found in the related sections. .INDENT 0.0 .TP .B \fB/*!re2c[:] ... */\fP A global re2c block with an optional name. The block may contain named definitions, configurations and rules in any order. Named definitions and configurations are defined in the global scope, so they are inherited by subsequent blocks. The code for a global block is generated at the point where the block is specified. .TP .B \fB/*!local:re2c[:] ... */\fP A local re2c block with an optional name. Unlike global blocks, definitions and configurations inside of a local block are not added into the global scope. In all other respects local blocks are the same as global blocks. .TP .B \fB/*!rules:re2c[:] ... */\fP A reusable block with an optional name. Rules blocks have the same structure as local or global blocks, but they do not produce any code and they can be reused multiple times in other blocks with the help of a \fB!use:;\fP directive or a \fB/*!use:re2c[:] ... */\fP block. A rules block on its own does not add any definitions into the global scope. The code for it is generated at the point of use. Prior to re2c version 2.2 rules blocks required \fB\-r \-\-reusable\fP option. .TP .B \fB/*!use:re2c[:] ... */\fP A use block that references a previously defined rules block. If the name is specified, re2c looks for a rules blocks with this name. Otherwise the most recent rules block is used (either a named or an unnamed one). A use block can add definitions, configurations and rules of its own, which are added to those of the referenced rules block. Prior to re2c version 2.2 use blocks required \fB\-r \-\-reusable\fP option. .TP .B \fB!use:;\fP An in\-block use directive that merges a previously defined rules block with the specified name into the current block. Named definitions, configurations and rules of the referenced block are added to the current ones. Conflicts between overlapping rules and configurations are resolved in the usual way: the first rule takes priority, and the latest configuration overrides the preceding ones. One exception is the special rules \fB*\fP, \fB$\fP and \fB\fP for which a block\-local definition always takes priority. A use directive can be placed anywhere inside of a block, and multiple use directives are allowed. .TP .B \fB/*!max:re2c[:[:...]] ... */\fP A directive that generates \fBYYMAXFILL\fP definition. An optional list of block names specifies which blocks should be included when computing \fBYYMAXFILL\fP value (if the list is empty, all blocks are included). By default the generated code is a macro\-definition for C (\fB#define YYMAXFILL \fP), or a global variable for Go (\fBvar YYMAXFILL int = \fP). It can be customized with an optional configuration \fBformat\fP that specifies a template string where \fB@@{max}\fP (or \fB@@\fP for short) is replaced with the numeric value of \fBYYMAXFILL\fP\&. .TP .B \fB/*!maxnmatch:re2c[:[:...]] ... */\fP A directive that generates \fBYYMAXNMATCH\fP definition (it requires \fB\-P \-\-posix\-captures\fP option). An optional list of block names specifies which blocks should be included when computing \fBYYMAXNMATCH\fP value (if the list is empty, all blocks are included). By default the generated code is a macro\-definition for C (\fB#define YYMAXNMATCH \fP), or a global variable for Go (\fBvar YYMAXNMATCH int = \fP). It can be customized with an optional configuration \fBformat\fP that specifies a template string where \fB@@{max}\fP (or \fB@@\fP for short) is replaced with the numeric value of \fBYYMAXNMATCH\fP\&. .TP .B \fB/*!stags:re2c[:[:...]] ... */\fP, \fB/*!mtags:re2c[:[:...]] ... */\fP Directives that specify a template piece of code that is expanded for each s\-tag/m\-tag variable generated by re2c. An optional list of block names specifies which blocks should be included when computing the set of tag variables (if the list is empty, all blocks are included). There are two optional configurations: \fBformat\fP and \fBseparator\fP\&. Configuration \fBformat\fP specifies a template string where \fB@@{tag}\fP (or \fB@@\fP for short) is replaced with the name of each tag variable. Configuration \fBseparator\fP specifies a piece of code used to join the generated \fBformat\fP pieces for different tag variables. .TP .B \fB/*!getstate:re2c[:[:...]] ... */\fP A directive that generates conditional dispatch on the lexer state (it requires \fB\-\-storable\-state\fP option). An optional list of block names specifies which blocks should be included in the state dispatch. The default transition goes to the start label of the first block on the list. If the list is empty, all blocks are included, and the default transition goes to the first block in the file that has a start label. This directive is incompatible with the \fB\-\-loop\-switch\fP option and Rust, as it requires cross\-block transitions that are unsupported without the \fBgoto\fP statement. .TP .B \fB/*!conditions:re2c[:[:...]] ... */\fP, \fB/*!types:re2c... */\fP A directive that generates condition enumeration (it requires \fB\-\-conditions\fP option). An optional list of block names specifies which blocks should be included when computing the set of conditions (if the list is empty, all blocks are included). By default the generated code is an enumeration \fBYYCONDTYPE\fP\&. It can be customized with optional configurations \fBformat\fP and \fBseparator\fP\&. Configuration \fBformat\fP specifies a template string where \fB@@{cond}\fP (or \fB@@\fP for short) is replaced with the name of each condition, and \fB@@{num}\fP is replaced with a numeric index of that condition. Configuration \fBseparator\fP specifies a piece of code used to join the generated \fBformat\fP pieces for different conditions. .TP .B \fB/*!include:re2c */\fP This directive allows one to include \fB\fP, which must be a double\-quoted file path. The contents of the file are literally substituted in place of the directive, in the same way as \fB#include\fP works in C/C++. This directive can be used together with the \fB\-\-depfile\fP option to generate build system dependencies on the included files. .TP .B \fB!include ;\fP This directive is the same as \fB/*!include:re2c */\fP, except that it should be used inside of a re2c block. .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\&. .TP .B \fB/*!ignore:re2c ... */\fP A block which contents are ignored and removed from the output file. .TP .B \fB%{ ... %}\fP A global re2c block in the \fB\-\-flex\-support\fP mode. This is deprecated and exists for backward compatibility. .UNINDENT .SH 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 position after the last matched character. It is used only in C pointer 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 position after the last available input character. It is not changed by the generated code. The lexer compares \fBYYCURSOR\fP to \fBYYLIMIT\fP in order to determine if there are enough input characters left. \fBYYLIMIT\fP is used only in C pointer 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 restore the \fBYYCURSOR\fP position if the longer match fails and the lexer needs to rollback. Initialization is not needed. \fBYYMARKER\fP is used only in C pointer 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 C pointer API, and only with the lookahead operator \fB/\fP\&. .TP .B \fBYYFILL\fP A generic API primitive with one argument \fBlen\fP\&. \fBYYFILL\fP should provide at least \fBlen\fP more input characters or fail. If \fBre2c:eof\fP is used, then \fBlen\fP is always \fB1\fP and \fBYYFILL\fP should always return to the calling function; zero return value indicates success. If \fBre2c:eof\fP is not used, then \fBYYFILL\fP return value is ignored and it should not return on failure. The maximum value of \fBlen\fP is \fBYYMAXFILL\fP\&. 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 maximum value of the argument to \fBYYFILL\fP\&. 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 are 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. \fBYYSKIP\fP should 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. \fBYYBACKUP\fP should 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. \fBYYRESTORE\fP should 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. \fBYYBACKUPCTX\fP should 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. \fBYYRESTORECTX\fP should 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\&. \fBYYRESTORETAG\fP should 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, where \fBtag\fP can be a pointer or an offset (see submatch extraction section for details). \fBYYSTAGP\fP should set \fBtag\fP 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, where \fBtag\fP can be a pointer or an offset (see submatch extraction section for details). \fBYYSTAGN\fP should to set \fBtag\fP to a value that represents non\-existent input position. 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\&. \fBYYMTAGP\fP should append the current position to the submatch history of \fBtag\fP (see the submatch extraction section for details.) 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\&. \fBYYMTAGN\fP should append a value that represents non\-existent input position position to the submatch history of \fBtag\fP (see the submatch extraction section for details.) 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\&. \fBYYSHIFT\fP should 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\&. \fBYYSHIFTSTAG\fP should 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\&. \fBYYSHIFTMTAG\fP should 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 the \fB/*!types:re2c*/\fP directive or the \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 .SH CONFIGURATIONS .INDENT 0.0 .TP .B \fBre2c:api\fP, \fBre2c:flags:input\fP Same as the \fB\-\-api\fP option. .TP .B \fBre2c:api:sigil\fP Specify the marker (\(dqsigil\(dq) that is used for argument placeholders in the API primitives. The default is \fB@@\fP\&. A placeholder starts 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:api:style\fP Specify API style. Possible values are \fBfunctions\fP (the default for C) and \fBfree\-form\fP (the default for Go and Rust). In \fBfunctions\fP style API primitives are generated with an argument list in parentheses following the name of the primitive. The arguments are provided only for autogenerated parameters (such as the number of characters passed to \fBYYFILL\fP), but not for the general lexer context, so the primitives behave more like macros in C/C++ or closures in Go and Rust. In free\-form style API primitives do not have a fixed form: they should be defined as strings containing free\-form pieces of code with interpolated variables of the form \fB@@{var}\fP or \fB@@\fP (they correspond to arguments in function\-like style). This configuration may be overridden for individual API primitives, see for example \fBre2c:define:YYFILL:naked\fP configuration for \fBYYFILL\fP\&. .TP .B \fBre2c:bit\-vectors\fP, \fBre2c:flags:bit\-vectors\fP, \fBre2c:flags:b\fP Same as the \fB\-\-bit\-vectors\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:case\-insensitive\fP, \fBre2c:flags:case\-insensitive\fP Same as the \fB\-\-case\-insensitive\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:case\-inverted\fP, \fBre2c:flags:case\-inverted\fP Same as the \fB\-\-case\-inverted\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:case\-ranges\fP, \fBre2c:flags:case\-ranges\fP Same as the \fB\-\-case\-ranges\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:computed\-gotos\fP, \fBre2c:flags:computed\-gotos\fP, \fBre2c:flags:g\fP Same as the \fB\-\-computed\-gotos\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:computed\-gotos:threshold\fP, \fBre2c:cgoto:threshold\fP If computed \fBgoto\fP is used, this configuration 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:cond:goto\fP Specifies a piece of code used for the autogenerated shortcut rules \fB:=>\fP in conditions. The default is \fBgoto @@;\fP\&. The \fB@@\fP placeholder is substituted with condition name (see configurations \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 is \fB@@\fP\&. Overrides the more generic \fBre2c:api:sigil\fP configuration. .TP .B \fBre2c:cond:prefix\fP, \fBre2c:condprefix\fP Specifies the prefix used for condition labels. The default is \fByyc_\fP\&. .TP .B \fBre2c:cond:enumprefix\fP, \fBre2c:condenumprefix\fP Specifies the prefix used for condition identifiers. The default is \fByyc\fP\&. .TP .B \fBre2c:debug\-output\fP, \fBre2c:flags:debug\-output\fP, \fBre2c:flags:d\fP Same as the \fB\-\-debug\-output\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:define:YYBACKUP\fP Defines generic API primitive \fBYYBACKUP\fP (see the API primitives section). .TP .B \fBre2c:define:YYBACKUPCTX\fP Defines generic API primitive \fBYYBACKUPCTX\fP (see the API primitives section). .TP .B \fBre2c:define:YYCONDTYPE\fP Defines \fBYYCONDTYPE\fP (see the API primitives section). .TP .B \fBre2c:define:YYCTYPE\fP Defines \fBYYCTYPE\fP (see the API primitives section). .TP .B \fBre2c:define:YYCTXMARKER\fP Defines API primitive \fBYYCTXMARKER\fP (see the API primitives section). .TP .B \fBre2c:define:YYCURSOR\fP Defines API primitive \fBYYCURSOR\fP (see the API primitives section). .TP .B \fBre2c:define:YYDEBUG\fP Defines API primitive \fBYYDEBUG\fP (see the API primitives section). .TP .B \fBre2c:define:YYFILL\fP Defines API primitive \fBYYFILL\fP (see the API primitives 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 Overrides the more generic \fBre2c:api:style\fP configuration for \fBYYFILL\fP\&. Zero value corresponds to free\-form API style. .TP .B \fBre2c:define:YYGETCONDITION\fP Defines API primitive \fBYYGETCONDITION\fP (see the API primitives section). .TP .B \fBre2c:define:YYGETCONDITION:naked\fP Overrides the more generic \fBre2c:api:style\fP configuration for \fBYYGETCONDITION\fP\&. Zero value corresponds to free\-form API style. .TP .B \fBre2c:define:YYGETSTATE\fP Defines API primitive \fBYYGETSTATE\fP (see the API primitives section). .TP .B \fBre2c:define:YYGETSTATE:naked\fP Overrides the more generic \fBre2c:api:style\fP configuration for \fBYYGETSTATE\fP\&. Zero value corresponds to free\-form API style. .TP .B \fBre2c:define:YYLESSTHAN\fP Defines generic API primitive \fBYYLESSTHAN\fP (see the API primitives section). .TP .B \fBre2c:define:YYLIMIT\fP Defines API primitive \fBYYLIMIT\fP (see the API primitives section). .TP .B \fBre2c:define:YYMARKER\fP Defines API primitive \fBYYMARKER\fP (see the API primitives section). .TP .B \fBre2c:define:YYMTAGN\fP Defines generic API primitive \fBYYMTAGN\fP (see the API primitives section). .TP .B \fBre2c:define:YYMTAGP\fP Defines generic API primitive \fBYYMTAGP\fP (see the API primitives section). .TP .B \fBre2c:define:YYPEEK\fP Defines generic API primitive \fBYYPEEK\fP (see the API primitives section). .TP .B \fBre2c:define:YYRESTORE\fP Defines generic API primitive \fBYYRESTORE\fP (see the API primitives section). .TP .B \fBre2c:define:YYRESTORECTX\fP Defines generic API primitive \fBYYRESTORECTX\fP (see the API primitives section). .TP .B \fBre2c:define:YYRESTORETAG\fP Defines generic API primitive \fBYYRESTORETAG\fP (see the API primitives section). .TP .B \fBre2c:define:YYSETCONDITION\fP Defines API primitive \fBYYSETCONDITION\fP (see the API primitives 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 Overrides the more generic \fBre2c:api:style\fP configuration for \fBYYSETCONDITION\fP\&. Zero value corresponds to free\-form API style. .TP .B \fBre2c:define:YYSETSTATE\fP Defines API primitive \fBYYSETSTATE\fP (see the API primitives 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 Overrides the more generic \fBre2c:api:style\fP configuration for \fBYYSETSTATE\fP\&. Zero value corresponds to free\-form API style. .TP .B \fBre2c:define:YYSKIP\fP Defines generic API primitive \fBYYSKIP\fP (see the API primitives section). .TP .B \fBre2c:define:YYSHIFT\fP Defines generic API primitive \fBYYSHIFT\fP (see the API primitives section). .TP .B \fBre2c:define:YYSHIFTMTAG\fP Defines generic API primitive \fBYYSHIFTMTAG\fP (see the API primitives section). .TP .B \fBre2c:define:YYSHIFTSTAG\fP Defines generic API primitive \fBYYSHIFTSTAG\fP (see the API primitives section). .TP .B \fBre2c:define:YYSTAGN\fP Defines generic API primitive \fBYYSTAGN\fP (see the API primitives section). .TP .B \fBre2c:define:YYSTAGP\fP Defines generic API primitive \fBYYSTAGP\fP (see the API primitives section). .TP .B \fBre2c:empty\-class\fP, \fBre2c:flags:empty\-class\fP Same as the \fB\-\-empty\-class\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:encoding:ebcdic\fP, \fBre2c:flags:ecb\fP, \fBre2c:flags:e\fP Same as the \fB\-\-ebcdic\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:encoding:ucs2\fP, \fBre2c:flags:wide\-chars\fP, \fBre2c:flags:w\fP Same as the \fB\-\-ucs2\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:encoding:utf8\fP, \fBre2c:flags:utf\-8\fP, \fBre2c:flags:8\fP Same as the \fB\-\-utf8\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:encoding:utf16\fP, \fBre2c:flags:utf\-16\fP, \fBre2c:flags:x\fP Same as the \fB\-\-utf16\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:encoding:utf32\fP, \fBre2c:flags:unicode\fP, \fBre2c:flags:u\fP Same as the \fB\-\-utf32\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:encoding\-policy\fP, \fBre2c:flags:encoding\-policy\fP Same as the \fB\-\-encoding\-policy\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:eof\fP Specifies the sentinel symbol used with the end\-of\-input rule \fB$\fP\&. The default value is \fB\-1\fP (\fB$\fP rule is not used). Other possible values include all valid code units. Only decimal numbers are recognized. .TP .B \fBre2c:header\fP, \fBre2c:flags:type\-header\fP, \fBre2c:flags:t\fP Specifies the name of the generated header file relative to the directory of the output file. Same as the \fB\-\-header\fP option except that the file path is relative. .TP .B \fBre2c:indent:string\fP Specifies the string used for indentation. The default is a single tab character \fB\(dq\et\(dq\fP\&. Indent string should contain whitespace characters only. To disable indentation entirely, set this configuration to an empty string. .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:invert\-captures\fP Same as the \fB\-\-invert\-captures\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:label:prefix\fP, \fBre2c:labelprefix\fP Specifies the prefix used for DFA state labels. The default is \fByy\fP\&. .TP .B \fBre2c:label:start\fP, \fBre2c:startlabel\fP Controls the generation of a block start label. 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:label:yyFillLabel\fP Specifies the prefix of \fBYYFILL\fP labels used with \fBre2c:eof\fP and in storable state mode. .TP .B \fBre2c:label:yyloop\fP Specifies the name of the label marking the start of the lexer loop with \fB\-\-loop\-switch\fP option. The default is \fByyloop\fP\&. .TP .B \fBre2c:label:yyNext\fP Specifies the name of the optional label that follows \fBYYGETSTATE\fP switch in storable state mode (enabled with \fBre2c:state:nextlabel\fP). The default is \fByyNext\fP\&. .TP .B \fBre2c:leftmost\-captures\fP Same as the \fB\-\-leftmost\-captures\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:lookahead\fP, \fBre2c:flags:lookahead\fP Deprecated (see the deprecated \fB\-\-no\-lookahead\fP option). .TP .B \fBre2c:nested\-ifs\fP, \fBre2c:flags:nested\-ifs\fP, \fBre2c:flags:s\fP Same as the \fB\-\-nested\-ifs\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:posix\-captures\fP, \fBre2c:flags:posix\-captures\fP, \fBre2c:flags:P\fP Same as the \fB\-\-posix\-captures\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:tags\fP, \fBre2c:flags:tags\fP, \fBre2c:flags:T\fP Same as the \fB\-\-tags\fP option, but can be configured on per\-block basis. .TP .B \fBre2c:tags:expression\fP Specifies the expression used for 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. All occurrences of \fB@@{tag}\fP or \fB@@\fP are replaced with the actual tag name. For example, \fBre2c:tags:expression = \(dqs.@@\(dq;\fP results in expressions of the form \fBs.yyt\fP in the generated code. See also \fBre2c:api:sigil\fP configuration. .TP .B \fBre2c:tags:prefix\fP Specifies the prefix for tag variable names. The default is \fByyt\fP\&. .TP .B \fBre2c:sentinel\fP Specifies the sentinel symbol used for the end\-of\-input checks (when bounds checks are disabled with \fBre2c:yyfill:enable = 0;\fP and \fBre2c:eof\fP is not set). This configuration does not affect code generation: its purpose is to verify that the sentinel is not allowed in the middle of a rule, and ensure that the lexer won\(aqt read past the end of buffer. The default value is \fI\-1\(ga\fP (in that case re2c assumes that the sentinel is zero, which is the most common case). Only decimal numbers are recognized. .TP .B \fBre2c:state:abort\fP If set to a positive integer value, changes the default case in \fBYYGETSTATE\fP switch: by default it aborts the program, and an explicit \fB\-1\fP case contains transition to the start of the block. .TP .B \fBre2c:state:nextlabel\fP Controls if the \fBYYGETSTATE\fP switch is followed by an \fByyNext\fP label (the default value is zero, which corresponds to no label). Alternatively one can use \fBre2c:label:start\fP to generate a specific start label, or an explicit \fBgetstate:re2c\fP directive to generate the \fBYYGETSTATE\fP switch separately from the lexer block. .TP .B \fBre2c:unsafe\fP, \fBre2c:flags:unsafe\fP Same as the \fB\-\-no\-unsafe\fP option, but can be configured on per\-block basis. If set to zero, it suppresses the generation of \fBunsafe\fP wrappers around \fBYYPEEK\fP\&. The default is non\-zero (wrappers are generated). This configuration is specific to Rust. .TP .B \fBre2c:variable:yyaccept\fP Specifies the name of the \fByyaccept\fP variable (see the API primitives section). .TP .B \fBre2c:variable:yybm\fP Specifies the name of the \fByybm\fP variable (used for bitmaps). .TP .B \fBre2c:variable:yybm:hex\fP, \fBre2c:yybm:hex\fP If set to nonzero, bitmaps for the \fB\-\-bit\-vectors\fP option are generated in hexadecimal format. The default is zero (bitmaps are in decimal format). .TP .B \fBre2c:variable:yych\fP Specifies the name of the \fByych\fP variable (see the API primitives section). .TP .B \fBre2c:variable:yych:emit\fP, \fBre2c:yych:emit\fP If set to zero, \fByych\fP definition is not generated. The default is non\-zero. .TP .B \fBre2c:variable:yych:conversion\fP, \fBre2c:yych:conversion\fP If set to non\-zero, re2c automatically generates a conversion to \fBYYCTYPE\fP every time \fByych\fP is read. The default is to zero (no conversion). .TP .B \fBre2c:variable:yyctable\fP Specifies the name of the \fByyctable\fP variable (the jump table generated for \fBYYGETCONDITION\fP switch with \fB\-\-computed\-gotos\fP option). .TP .B \fBre2c:variable:yytarget\fP Specifies the name of the \fByytarget\fP variable. .TP .B \fBre2c:variable:yystable\fP Deprecated. .TP .B \fBre2c:variable:yystate\fP Specifies the name of the \fByystate\fP variable (used with the \fB\-\-loop\-switch\fP option to store the current DFA state). .TP .B \fBre2c:yyfill:check\fP If set to zero, suppresses the generation of pre\-\fBYYFILL\fP check for the number of input characters (the \fBYYLESSTHAN\fP definition in generic API and the \fBYYLIMIT\fP\-based comparison in C pointer API). The default is non\-zero (generate the check). .TP .B \fBre2c:yyfill:enable\fP If set to zero, suppresses the generation of \fBYYFILL\fP (together with the check). This should be used when the whole input fits into one piece of memory (there is no need for buffering) and the end\-of\-input checks do not rely on the \fBYYFILL\fP checks (e.g. if a sentinel character is used). Use warnings (\fB\-W\fP option) and \fBre2c:sentinel\fP configuration to verify that the generated lexer cannot read past the end of input. The default is non\-zero (\fBYYFILL\fP is enabled). .TP .B \fBre2c:yyfill:parameter\fP If set to zero, suppresses the generation of parameter passed to \fBYYFILL\fP\&. The parameter is the minimum number of characters that must be supplied. Defaults to non\-zero (the parameter is generated). This configuration can be overridden with \fBre2c:define:YYFILL:naked\fP or \fBre2c:api:style\fP\&. .UNINDENT .SH REGULAR EXPRESSIONS .sp re2c uses the following syntax for regular expressions: .INDENT 0.0 .IP \(bu 2 \fB\(dqfoo\(dq\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. If submatch extraction is enabled, \fB(R)\fP is a capturing or a non\-capturing group depending on \fB\-\-invert\-captures\fP option. .IP \(bu 2 \fB(!R)\fP If submatch extraction is enabled, \fB(!R)\fP is a non\-capturing or a capturing group depending on \fB\-\-invert\-captures\fP option. .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\(dqname\(dq\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 HANDLING THE END OF INPUT .sp One of the main problems for the lexer is to know when to stop. There are a few terminating conditions: .INDENT 0.0 .IP \(bu 2 the lexer may match some rule (including default rule \fB*\fP) and come to a final state .IP \(bu 2 the lexer may fail to match any rule and come to a default state .IP \(bu 2 the lexer may reach the end of input .UNINDENT .sp The first two conditions terminate the lexer in a \(dqnatural\(dq way: it comes to a state with no outgoing transitions, and the matching automatically stops. The third condition, end of input, is different: it may happen in any state, and the lexer should be able to handle it. Checking for the end of input interrupts the normal lexer workflow and adds conditional branches to the generated program, therefore it is necessary to minimize the number of such checks. re2c supports a few different methods for handling the end of input. Which one to use depends on the complexity of regular expressions, the need for buffering, performance considerations and other factors. Here is a list of methods: .INDENT 0.0 .IP \(bu 2 \fBSentinel.\fP This method eliminates the need for the end of input checks altogether. It is simple and efficient, but limited to the case when there is a natural \(dqsentinel\(dq character that can never occur in valid input. This character may still occur in invalid input, but it should not be allowed by the regular expressions, except perhaps as the last character of a rule. The sentinel is appended at the end of input and serves as a stop signal: when the lexer reads this character, it is either a syntax error or the end of input. In both cases the lexer should stop. This method is used if \fBYYFILL\fP is disabled with \fBre2c:yyfill:enable = 0;\fP and \fBre2c:eof\fP has the default value \fB\-1\fP\&. .nf .fi .sp .IP \(bu 2 \fBSentinel with bounds checks.\fP This method is generic: it allows to handle any input without restrictions on the regular expressions. The idea is to reduce the number of end of input checks by performing them only on certain characters. Similar to the \(dqsentinel\(dq method, one of the characters is chosen as a \(dqsentinel\(dq and appended at the end of input. However, there is no restriction on where the sentinel may occur (in fact, any character can be chosen for a sentinel). When the lexer reads this character, it additionally performs a bounds check. If the current position is within bounds, the lexer resumes matching and handles the sentinel as a regular character. Otherwise it invokes \fBYYFILL\fP (unless it is disabled). If more input is supplied, the lexer will rematch the last character and continue as if the sentinel wasn\(aqt there. Otherwise it must be the real end of input, and the lexer stops. This method is used when \fBre2c:eof\fP has non\-negative value (it should be set to the numeric value of the sentinel). \fBYYFILL\fP is optional. .nf .fi .sp .IP \(bu 2 \fBBounds checks with padding.\fP This method is generic, and it may be faster than the \(dqsentinel with bounds checks\(dq method, but it is also more complex. The idea is to partition DFA states into strongly connected components (SCCs) and generate a single check per SCC for enough characters to cover the longest non\-looping path in this SCC. This reduces the number of checks, but there is a problem with short lexemes at the end of input, as the check requires enough characters to cover the longest lexeme. This can be fixed by padding the input with a few fake characters that do not form a valid lexeme suffix (so that the lexer cannot match them). The length of padding should be \fBYYMAXFILL\fP, generated with \fB/*!max:re2c*/\fP\&. If there is not enough input, the lexer invokes \fBYYFILL\fP which should supply at least the required number of characters or not return. This method is used if \fBYYFILL\fP is enabled and \fBre2c:eof\fP is \fB\-1\fP (this is the default configuration). .nf .fi .sp .IP \(bu 2 \fBCustom checks.\fP Generic API allows to override basic operations like reading a character, which makes it possible to include the end\-of\-input checks as part of them. This approach is error\-prone and should be used with caution. To use a custom method, enable generic API with \fB\-\-api custom\fP or \fBre2c:api = custom;\fP and disable default bounds checks with \fBre2c:yyfill:enable = 0;\fP or \fBre2c:yyfill:check = 0;\fP\&. .UNINDENT .sp The following subsections contain an example of each method. .SS Sentinel .sp This example uses a sentinel character to handle the end of input. The program counts space\-separated words in a null\-terminated string. The sentinel is null: it is the last character of each input string, and it is not allowed in the middle of a lexeme by any of the rules (in particular, it is not included in character ranges where it is easy to overlook). If a null occurs in the middle of a string, it is a syntax error and the lexer will match default rule \fB*\fP, but it won\(aqt read past the end of input or crash (use \fI\%\-Wsentinel\-in\-midrule\fP warning and \fBre2c:sentinel\fP configuration to verify this). Configuration \fBre2c:yyfill:enable = 0;\fP suppresses the generation of bounds checks and \fBYYFILL\fP invocations. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT #include // Expect a null\-terminated string. static int lex(const char *YYCURSOR) { int count = 0; for (;;) { /*!re2c re2c:define:YYCTYPE = char; re2c:yyfill:enable = 0; * { return \-1; } [\ex00] { return count; } [a\-z]+ { ++count; continue; } [ ]+ { continue; } */ } } int main() { assert(lex(\(dq\(dq) == 0); assert(lex(\(dqone two three\(dq) == 3); assert(lex(\(dqf0ur\(dq) == \-1); return 0; } .ft P .fi .UNINDENT .UNINDENT .SS Sentinel with bounds checks .sp This example uses sentinel with bounds checks to handle the end of input (this method was added in version 1.2). The program counts space\-separated single\-quoted strings. The sentinel character is null, which is specified with \fBre2c:eof = 0;\fP configuration. As in the \fI\%sentinel\fP method, null is the last character of each input string, but it is allowed in the middle of a rule (for example, \fB\(aqaaa\e0aa\(aq\e0\fP is valid input, but \fB\(aqaaa\e0\fP is a syntax error). Bounds checks are generated in each state that matches an input character, but they are scoped to the branch that handles null. Bounds checks are of the form \fBYYLIMIT <= YYCURSOR\fP or \fBYYLESSTHAN(1)\fP with generic API. If the check condition is true, lexer has reached the end of input and should stop (\fBYYFILL\fP is disabled with \fBre2c:yyfill:enable = 0;\fP as the input fits into one buffer, see the \fI\%YYFILL with sentinel\fP section for an example that uses \fBYYFILL\fP). Reaching the end of input opens three possibilities: if the lexer is in the initial state it will match the end\-of\-input rule \fB$\fP, otherwise it may fallback to a previously matched rule (including default rule \fB*\fP) or go to a default state, causing \fI\%\-Wundefined\-control\-flow\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT #include // Expect a null\-terminated string. static int lex(const char *str, unsigned int len) { const char *YYCURSOR = str, *YYLIMIT = str + len, *YYMARKER; int count = 0; for (;;) { /*!re2c re2c:define:YYCTYPE = char; re2c:yyfill:enable = 0; re2c:eof = 0; str = [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq]; * { return \-1; } $ { return count; } str { ++count; continue; } [ ]+ { continue; } */ } } #define TEST(s, r) assert(lex(s, sizeof(s) \- 1) == r) int main() { TEST(\(dq\(dq, 0); TEST(\(dq\(aqqu\e0tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq \(dq, 3); TEST(\(dq\(aqunterminated\e\e\(aq\(dq, \-1); return 0; } .ft P .fi .UNINDENT .UNINDENT .SS Bounds checks with padding .sp This example uses bounds checks with padding to handle the end of input (this method is enabled by default). The program counts space\-separated single\-quoted strings. There is a padding of \fBYYMAXFILL\fP null characters appended at the end of input, where \fBYYMAXFILL\fP value is autogenerated with \fB/*!max:re2c*/\fP\&. It is not necessary to use null for padding \-\-\- any characters can be used as long as they do not form a valid lexeme suffix (in this example padding should not contain single quotes, as they may be mistaken for a suffix of a single\-quoted string). There is a \(dqstop\(dq rule that matches the first padding character (null) and terminates the lexer (note that it checks if null is at the beginning of padding, otherwise it is a syntax error). Bounds checks are generated only in some states that are determined by the strongly connected components of the underlying automaton. Checks have the form \fB(YYLIMIT \- YYCURSOR) < n\fP or \fBYYLESSTHAN(n)\fP with generic API, where \fBn\fP is the minimum number of characters that are needed for the lexer to proceed (it also means that the next bounds check will occur in at most \fBn\fP characters). If the check condition is true, the lexer has reached the end of input and will invoke \fBYYFILL(n)\fP that should either supply at least \fBn\fP input characters or not return. In this example \fBYYFILL\fP always fails and terminates the lexer with an error (which is fine because the input fits into one buffer). See the \fI\%YYFILL with padding\fP section for an example that refills the input buffer with \fBYYFILL\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT #include #include #include /*!max:re2c*/ static int lex(const char *str, unsigned int len) { // Make a copy of the string with YYMAXFILL zeroes at the end. char *buf = (char*) malloc(len + YYMAXFILL); memcpy(buf, str, len); memset(buf + len, 0, YYMAXFILL); const char *YYCURSOR = buf, *YYLIMIT = buf + len + YYMAXFILL; int count = 0; loop: /*!re2c re2c:api:style = free\-form; re2c:define:YYCTYPE = char; re2c:define:YYFILL = \(dqgoto fail;\(dq; str = [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq]; [\ex00] { // Check that it is the sentinel, not some unexpected null. if (YYCURSOR \- 1 == buf + len) goto exit; else goto fail; } str { ++count; goto loop; } [ ]+ { goto loop; } * { goto fail; } */ fail: count = \-1; exit: free(buf); return count; } #define TEST(s, r) assert(lex(s, sizeof(s) \- 1) == r) int main() { TEST(\(dq\(dq, 0); TEST(\(dq\(aqqu\e0tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq \(dq, 3); TEST(\(dq\(aqunterminated\e\e\(aq\(dq, \-1); TEST(\(dq\(aqunexpected \e0 null\e\e\(aq\(dq, \-1); return 0; } .ft P .fi .UNINDENT .UNINDENT .SS Custom checks .sp This example uses a custom end\-of\-input handling method based on generic API. The program counts space\-separated single\-quoted strings. It is the same as the \fI\%sentinel with bounds checks\fP example, except that the input is not null\-terminated (this method can be used if padding is not an option, not even a single character). To cover up for the absence of sentinel character at the end of input, \fBYYPEEK\fP is redefined to perform a bounds check before it reads the next input character. This is inefficient because checks are done very often. If the check condition fails, \fBYYPEEK\fP returns the real character, otherwise it returns a fake sentinel character. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT #include #include #include static int lex(const char *str, unsigned int len) { // For the sake of example create a string without terminating null. char *buf = (char*) malloc(len); memcpy(buf, str, len); const char *cur = buf, *lim = buf + len, *mar; int count = 0; for (;;) { /*!re2c re2c:yyfill:enable = 0; re2c:eof = 0; re2c:api = custom; re2c:api:style = free\-form; re2c:define:YYCTYPE = char; re2c:define:YYLESSTHAN = \(dqcur >= lim\(dq; re2c:define:YYPEEK = \(dqcur < lim ? *cur : 0\(dq; // fake null re2c:define:YYSKIP = \(dq++cur;\(dq; re2c:define:YYBACKUP = \(dqmar = cur;\(dq; re2c:define:YYRESTORE = \(dqcur = mar;\(dq; str = [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq]; * { count = \-1; break; } $ { break;; } str { ++count; continue; } [ ]+ { continue; } */ } free(buf); return count; } #define TEST(s, r) assert(lex(s, sizeof(s) \- 1) == r) int main() { TEST(\(dq\(dq, 0); TEST(\(dq\(aqqu\e0tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq \(dq, 3); TEST(\(dq\(aqunterminated\e\e\(aq\(dq, \-1); return 0; } .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 positions: .INDENT 0.0 .IP \(bu 2 cursor: the next input character to be read (\fBYYCURSOR\fP in C pointer API or \fBYYSKIP\fP/\fBYYPEEK\fP in generic API) .IP \(bu 2 limit: the position after the last available input character (\fBYYLIMIT\fP in C pointer 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 C pointer 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 (described in the section about storable state). .SS YYFILL with sentinel .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 C pointer 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 // re2c $INPUT \-o $OUTPUT #include #include #include #define BUFSIZE 4095 struct Input { FILE *file; char buf[BUFSIZE + 1], *lim, *cur, *mar, *tok; // +1 for sentinel bool eof; }; static int fill(Input &in) { if (in.eof) return 1; const size_t shift = in.tok \- in.buf; const size_t used = in.lim \- in.tok; // Error: lexeme too long. In real life could reallocate a larger buffer. if (shift < 1) return 2; // Shift buffer contents (discard everything up to the current token). memmove(in.buf, in.tok, used); in.lim \-= shift; in.cur \-= shift; in.mar \-= shift; in.tok \-= shift; // Fill free space at the end of buffer with new data from file. in.lim += fread(in.lim, 1, BUFSIZE \- used, in.file); in.lim[0] = 0; in.eof = in.lim < in.buf + BUFSIZE; return 0; } static int lex(Input &in) { int count = 0; for (;;) { in.tok = in.cur; /*!re2c re2c:api:style = free\-form; re2c:define:YYCTYPE = char; re2c:define:YYCURSOR = in.cur; re2c:define:YYMARKER = in.mar; re2c:define:YYLIMIT = in.lim; re2c:define:YYFILL = \(dqfill(in) == 0\(dq; re2c:eof = 0; str = [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq]; * { return \-1; } $ { return count; } str { ++count; continue; } [ ]+ { continue; } */ } } int main() { const char *fname = \(dqinput\(dq; const char content[] = \(dq\(aqqu\e0tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq \(dq; // Prepare input file: a few times the size of the buffer, containing // strings with zeroes and escaped quotes. FILE *f = fopen(fname, \(dqw\(dq); for (int i = 0; i < BUFSIZE; ++i) { fwrite(content, 1, sizeof(content) \- 1, f); } fclose(f); int count = 3 * BUFSIZE; // number of quoted strings written to file // Initialize lexer state: all pointers are at the end of buffer. Input in; in.file = fopen(fname, \(dqr\(dq); in.cur = in.mar = in.tok = in.lim = in.buf + BUFSIZE; in.eof = 0; // Sentinel (at YYLIMIT pointer) is set to zero, which triggers YYFILL. in.lim[0] = 0; // Run the lexer. assert(lex(in) == count); // Cleanup: remove input file. fclose(in.file); remove(fname); return 0; } .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 C pointer 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 // re2c $INPUT \-o $OUTPUT #include #include #include /*!max:re2c*/ #define BUFSIZE (4096 \- YYMAXFILL) struct Input { FILE *file; char buf[BUFSIZE + YYMAXFILL], *lim, *cur, *tok; bool eof; }; static int fill(Input &in, size_t need) { if (in.eof) return 1; const size_t shift = in.tok \- in.buf; const size_t used = in.lim \- in.tok; // Error: lexeme too long. In real life could reallocate a larger buffer. if (shift < need) return 2; // Shift buffer contents (discard everything up to the current token). memmove(in.buf, in.tok, used); in.lim \-= shift; in.cur \-= shift; in.tok \-= shift; // Fill free space at the end of buffer with new data from file. in.lim += fread(in.lim, 1, BUFSIZE \- used, in.file); // If read less than expected, this is end of input => add zero padding // so that the lexer can access characters at the end of buffer. if (in.lim < in.buf + BUFSIZE) { in.eof = true; memset(in.lim, 0, YYMAXFILL); in.lim += YYMAXFILL; } return 0; } static int lex(Input &in) { int count = 0; for (;;) { in.tok = in.cur; /*!re2c re2c:api:style = free\-form; re2c:define:YYCTYPE = char; re2c:define:YYCURSOR = in.cur; re2c:define:YYLIMIT = in.lim; re2c:define:YYFILL = \(dqif (fill(in, @@) != 0) return \-1;\(dq; str = [\(aq] ([^\(aq\e\e] | [\e\e][^])* [\(aq]; [\ex00] { // Check that it is the sentinel, not some unexpected null. return in.tok == in.lim \- YYMAXFILL ? count : \-1; } str { ++count; continue; } [ ]+ { continue; } * { return \-1; } */ } } int main() { const char *fname = \(dqinput\(dq; const char content[] = \(dq\(aqqu\e0tes\(aq \(aqare\(aq \(aqfine: \e\e\(aq\(aq \(dq; // Prepare input file: a few times the size of the buffer, containing // strings with zeroes and escaped quotes. FILE *f = fopen(fname, \(dqw\(dq); for (int i = 0; i < BUFSIZE; ++i) { fwrite(content, 1, sizeof(content) \- 1, f); } fclose(f); int count = 3 * BUFSIZE; // number of quoted strings written to file // Initialize lexer state: all pointers are at the end of buffer. // This immediately triggers YYFILL, as the check \(gain.cur < in.lim\(ga fails. Input in; in.file = fopen(fname, \(dqr\(dq); in.cur = in.tok = in.lim = in.buf + BUFSIZE; in.eof = 0; // Run the lexer. assert(lex(in) == count); // Cleanup: remove input file. fclose(in.file); remove(fname); return 0; } .ft P .fi .UNINDENT .UNINDENT .SH MULTIPLE BLOCKS .sp Sometimes it is necessary to have multiple interrelated lexers (for example, if there is a high\-level state machine that transitions between lexer modes). This can be implemented using multiple connected re2c blocks. Another option is to use \fI\%start conditions\fP\&. .sp The implementation of connections between blocks depends on the target language. In languages that have \fBgoto\fP statement (such as C/C++ and Go) one can have all blocks in one function, each of them prefixed with a label. Transition from one block to another is a simple \fBgoto\fP\&. In languages that do not have \fBgoto\fP (such as Rust) it is necessary to use a loop with a switch on a state variable, similar to the \fByystate\fP loop/switch generated by re2c, or else wrap each block in a function and use function calls. .sp The example below uses multiple blocks to parse binary, octal, decimal and hexadecimal numbers. Each base has its own block. The initial block determines base and dispatches to other blocks. Common configurations are defined in a separate block at the beginning of the program; they are inherited by the other blocks. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT \-i #include #include #include static const uint64_t ERROR = UINT64_MAX; template static void add(uint64_t &u, char d) { u = u * BASE + d; if (u > UINT32_MAX) u = ERROR; } static uint64_t parse_u32(const char *s) { const char *YYCURSOR = s, *YYMARKER; uint64_t u = 0; /*!re2c re2c:yyfill:enable = 0; re2c:define:YYCTYPE = char; end = \(dq\ex00\(dq; \(aq0b\(aq / [01] { goto bin; } \(dq0\(dq { goto oct; } \(dq\(dq / [1\-9] { goto dec; } \(aq0x\(aq / [0\-9a\-fA\-F] { goto hex; } * { return ERROR; } */ bin: /*!re2c end { return u; } [01] { add<2>(u, YYCURSOR[\-1] \- \(aq0\(aq); goto bin; } * { return ERROR; } */ oct: /*!re2c end { return u; } [0\-7] { add<8>(u, YYCURSOR[\-1] \- \(aq0\(aq); goto oct; } * { return ERROR; } */ dec: /*!re2c end { return u; } [0\-9] { add<10>(u, YYCURSOR[\-1] \- \(aq0\(aq); goto dec; } * { return ERROR; } */ hex: /*!re2c end { return u; } [0\-9] { add<16>(u, YYCURSOR[\-1] \- \(aq0\(aq); goto hex; } [a\-f] { add<16>(u, YYCURSOR[\-1] \- \(aqa\(aq + 10); goto hex; } [A\-F] { add<16>(u, YYCURSOR[\-1] \- \(aqA\(aq + 10); goto hex; } * { return ERROR; } */ } int main() { assert(parse_u32(\(dq\(dq) == ERROR); assert(parse_u32(\(dq1234567890\(dq) == 1234567890); assert(parse_u32(\(dq0b1101\(dq) == 13); assert(parse_u32(\(dq0x7Fe\(dq) == 2046); assert(parse_u32(\(dq0644\(dq) == 420); assert(parse_u32(\(dq9999999999\(dq) == ERROR); return 0; } .ft P .fi .UNINDENT .UNINDENT .SH START CONDITIONS .sp Start conditions are enabled with \fB\-\-start\-conditions\fP option. They provide a way to encode multiple interrelated automata within the same re2c block. .sp Each condition corresponds to a single automaton and has a unique name specified by the user and a unique internal number defined by re2c. The numbers are used to switch between conditions: the generated code uses \fBYYGETCONDITION\fP and \fBYYSETCONDITION\fP primitives to get the current condition or set it to the given number. Use \fB/*!conditions:re2c*/\fP directive or the \fB\-\-header\fP option to generate numeric condition identifiers. Configuration \fBre2c:cond:enumprefix\fP specifies the generated identifier prefix. .sp In condition mode every rule must be prefixed with a list of comma\-separated condition names in angle brackets, or a wildcard \fB<*>\fP to denote all conditions. The rule syntax is extended as follows: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fB< cond\-list > regexp action\fP A rule that is merged to every condition on the \fBcond\-list\fP\&. It matches \fBregexp\fP and executes the associated \fBaction\fP\&. .TP .B \fB< cond\-list > regexp => cond action\fP A rule that is merged to every condition on the \fBcond\-list\fP\&. It matches \fBregexp\fP, sets the current condition to \fBcond\fP and executes the associated \fBaction\fP\&. .TP .B \fB< cond\-list > regexp :=> cond\fP A rule that is merged to every condition on the \fBcond\-list\fP\&. It matches \fBregexp\fP and immediately transitions to \fBcond\fP (there is no semantic action). .TP .B \fB action\fP The \fBaction\fP is prepended to semantic actions of all rules for every condition on the \fBcond\-list\fP\&. This may be used to deduplicate common code. .TP .B \fB< > action\fP A rule that is merged to a special entry condition with number zero and name \fB\(dq0\(dq\fP\&. It matches empty string and executes the \fBaction\fP\&. .TP .B \fB< > => cond action\fP A rule that is merged to a special entry condition with number zero and name \fB\(dq0\(dq\fP\&. It matches empty string, sets the current condition to \fBcond\fP and executes the \fBaction\fP\&. .TP .B \fB< > :=> cond\fP A rule that is merged to a special entry condition with number zero and name \fB\(dq0\(dq\fP\&. It matches empty string and immediately transitions to \fBcond\fP\&. .UNINDENT .UNINDENT .UNINDENT .sp The code re2c generates for conditions depends on whether re2c uses goto/label approach or loop/switch approach to encode the automata. .sp In languages that have \fBgoto\fP statement (such as C/C++ and Go) conditions are naturally implemented as blocks of code prefixed with labels of the form \fByyc_\fP, where \fBcond\fP is a condition name (label prefix can be changed with \fBre2c:cond:prefix\fP). Transitions between conditions are implemented using \fBgoto\fP and condition labels. Before all conditions re2c generates an initial switch on \fBYYGETSTATE\fP that jumps to the start state of the current condition. The shortcut rules \fB:=>\fP bypass the initial switch and jump directly to the specified condition (\fBre2c:cond:goto\fP can be used to change the default behavior). The rules with semantic actions do not automatically jump to the next condition; this should be done by the user\-defined action code. .sp In languages that do not have \fBgoto\fP (such as Rust) re2c reuses the \fByystate\fP variable to store condition numbers. Each condition gets a numeric identifier equal to the number of its start state, and a switch between conditions is no different than a switch between DFA states of a single condition. There is no need for a separate initial condition switch. (Since the same approach is used to implement storable states, \fBYYGETCONDITION\fP/\fBYYSETCONDITION\fP are redundant if both storable states and conditions are used). .sp The program below uses start conditions to parse binary, octal, decimal and hexadecimal numbers. There is a single block where each base has its own condition, and the initial condition is connected to all of them. User\-defined variable \fBcond\fP stores the current condition number; it is initialized to the number of the initial condition generated with \fB/*!conditions:re2c*/\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT \-ci #include #include #include static const uint64_t ERROR = UINT64_MAX; /*!conditions:re2c*/ template static void add(uint64_t &u, char d) { u = u * BASE + d; if (u > UINT32_MAX) u = ERROR; } static uint64_t parse_u32(const char *s) { const char *YYCURSOR = s, *YYMARKER; int c = yycinit; uint64_t u = 0; /*!re2c re2c:api:style = free\-form; re2c:define:YYCTYPE = char; re2c:define:YYGETCONDITION = \(dqc\(dq; re2c:define:YYSETCONDITION = \(dqc = @@;\(dq; re2c:yyfill:enable = 0; <*> * { return ERROR; } \(aq0b\(aq / [01] :=> bin \(dq0\(dq :=> oct \(dq\(dq / [1\-9] :=> dec \(aq0x\(aq / [0\-9a\-fA\-F] :=> hex \(dq\ex00\(dq { return u; } [01] { add<2>(u, YYCURSOR[\-1] \- \(aq0\(aq); goto yyc_bin; } [0\-7] { add<8>(u, YYCURSOR[\-1] \- \(aq0\(aq); goto yyc_oct; } [0\-9] { add<10>(u, YYCURSOR[\-1] \- \(aq0\(aq); goto yyc_dec; } [0\-9] { add<16>(u, YYCURSOR[\-1] \- \(aq0\(aq); goto yyc_hex; } [a\-f] { add<16>(u, YYCURSOR[\-1] \- \(aqa\(aq + 10); goto yyc_hex; } [A\-F] { add<16>(u, YYCURSOR[\-1] \- \(aqA\(aq + 10); goto yyc_hex; } */ } int main() { assert(parse_u32(\(dq\(dq) == ERROR); assert(parse_u32(\(dq1234567890\(dq) == 1234567890); assert(parse_u32(\(dq0b1101\(dq) == 13); assert(parse_u32(\(dq0x7Fe\(dq) == 2046); assert(parse_u32(\(dq0644\(dq) == 420); assert(parse_u32(\(dq9999999999\(dq) == ERROR); return 0; } .ft P .fi .UNINDENT .UNINDENT .SH STORABLE STATE .sp With \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 \(dqpull\(dq model, in which the lexer \(dqpulls\(dq 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 \(dqpush\(dq 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 \(dqpull\(dq model: .INDENT 0.0 .IP \(bu 2 Define \fBYYSETSTATE()\fP and \fBYYGETSTATE(state)\fP primitives. .IP \(bu 2 Define \fByych\fP, \fByyaccept\fP (if used) 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 Optionally use \fBgetstate:re2c\fP to generate \fBYYGETSTATE\fP switch detached from the main lexer. This only works for languages that have \fBgoto\fP (not in \fB\-\-loop\-switch\fP mode). .IP \(bu 2 Use \fBre2c:eof\fP and the \fI\%sentinel with bounds checks\fP method to handle the end of input. Padding\-based method may not work because it is unclear when to append padding: the current end of input may not be the ultimate end of input, and appending padding too early may cut off a partially read greedy lexeme. Furthermore, due to high\-level program logic getting more input may depend on processing the lexeme at the end of buffer (which already is blocked due to the end\-of\-input condition). .UNINDENT .sp Here is an example of a \(dqpush\(dq model lexer that simulates reading packets from a socket. The lexer loops until it encounters the end of input and returns to the calling function. The calling function provides more input by \(dqsending\(dq the next packet and resumes lexing. This process stops when all the packets have been sent, or when there is an error. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT \-f #include #include #include #define DEBUG 0 #define LOG(...) if (DEBUG) fprintf(stderr, __VA_ARGS__); // Use a small buffer to cover the case when a lexeme doesn\(aqt fit. // In real world use a larger buffer. #define BUFSIZE 10 struct State { FILE *file; char buf[BUFSIZE + 1], *lim, *cur, *mar, *tok; int state; }; typedef enum {END, READY, WAITING, BAD_PACKET, BIG_PACKET} Status; static Status fill(State &st) { const size_t shift = st.tok \- st.buf; const size_t used = st.lim \- st.tok; const size_t free = BUFSIZE \- used; // Error: no space. In real life can reallocate a larger buffer. if (free < 1) return BIG_PACKET; // Shift buffer contents (discard already processed data). memmove(st.buf, st.tok, used); st.lim \-= shift; st.cur \-= shift; st.mar \-= shift; st.tok \-= shift; // Fill free space at the end of buffer with new data. const size_t read = fread(st.lim, 1, free, st.file); st.lim += read; st.lim[0] = 0; // append sentinel symbol return READY; } static Status lex(State &st, unsigned int *recv) { char yych; /*!getstate:re2c*/ for (;;) { st.tok = st.cur; /*!re2c re2c:api:style = free\-form; re2c:define:YYCTYPE = \(dqchar\(dq; re2c:define:YYCURSOR = \(dqst.cur\(dq; re2c:define:YYMARKER = \(dqst.mar\(dq; re2c:define:YYLIMIT = \(dqst.lim\(dq; re2c:define:YYGETSTATE = \(dqst.state\(dq; re2c:define:YYSETSTATE = \(dqst.state = @@;\(dq; re2c:define:YYFILL = \(dqreturn WAITING;\(dq; re2c:eof = 0; packet = [a\-z]+[;]; * { return BAD_PACKET; } $ { return END; } packet { *recv = *recv + 1; continue; } */ } } void test(const char **packets, Status expect) { // Create a \(dqsocket\(dq (open the same file for reading and writing). const char *fname = \(dqpipe\(dq; FILE *fw = fopen(fname, \(dqw\(dq); FILE *fr = fopen(fname, \(dqr\(dq); setvbuf(fw, NULL, _IONBF, 0); setvbuf(fr, NULL, _IONBF, 0); // Initialize lexer state: \(gastate\(ga value is \-1, all pointers are at the end // of buffer. State st; st.file = fr; st.cur = st.mar = st.tok = st.lim = st.buf + BUFSIZE; // Sentinel (at YYLIMIT pointer) is set to zero, which triggers YYFILL. st.lim[0] = 0; st.state = \-1; // Main loop. The buffer contains incomplete data which appears packet by // packet. When the lexer needs more input it saves its internal state and // returns to the caller which should provide more input and resume lexing. Status status; unsigned int send = 0, recv = 0; for (;;) { status = lex(st, &recv); if (status == END) { LOG(\(dqdone: got %u packets\en\(dq, recv); break; } else if (status == WAITING) { LOG(\(dqwaiting...\en\(dq); if (*packets) { LOG(\(dqsent packet %u\en\(dq, send); fprintf(fw, \(dq%s\(dq, *packets++); ++send; } status = fill(st); LOG(\(dqqueue: \(aq%s\(aq\en\(dq, st.buf); if (status == BIG_PACKET) { LOG(\(dqerror: packet too big\en\(dq); break; } assert(status == READY); } else { assert(status == BAD_PACKET); LOG(\(dqerror: ill\-formed packet\en\(dq); break; } } // Check results. assert(status == expect); if (status == END) assert(recv == send); // Cleanup: remove input file. fclose(fw); fclose(fr); remove(fname); } int main() { const char *packets1[] = {0}; const char *packets2[] = {\(dqzero;\(dq, \(dqone;\(dq, \(dqtwo;\(dq, \(dqthree;\(dq, \(dqfour;\(dq, 0}; const char *packets3[] = {\(dqzer0;\(dq, 0}; const char *packets4[] = {\(dqlooooooooooong;\(dq, 0}; test(packets1, END); test(packets2, END); test(packets3, BAD_PACKET); test(packets4, BIG_PACKET); return 0; } .ft P .fi .UNINDENT .UNINDENT .SH REUSABLE BLOCKS .sp Reusable blocks are re2c blocks that can be reused any number of times and combined with other re2c blocks. They are defined with \fB/*!rules:re2c[:] ... */\fP (the \fB\fP is optional). A rules block can be used in two contexts: either in a use block, or in a use directive inside of another block. The code for a rules block is generated at every point of use. .sp Use blocks are defined with \fB/*!use:re2c[:] ... */\fP\&. The \fB\fP is optional; if not specified, the associated rules block is the most recent one (whether named or unnamed). A use block can add named definitions, configurations and rules of its own. An important use case for use blocks is a lexer that supports multiple input encodings: the same rules block is reused multiple times with encoding\-specific configurations (see the example below). .sp In\-block use directive \fB!use:;\fP can be used from inside of a re2c block. It merges the referenced block \fB\fP into the current one. If some of the merged rules and configurations overlap with the previously defined ones, conflicts are resolved in the usual way: the earliest rule takes priority, and latest configuration overrides preceding ones. One exception are the special rules \fB*\fP, \fB$\fP and (in condition mode) \fB\fP, for which a block\-local definition overrides any inherited ones. Use directive allows one to combine different re2c blocks together in one block (see the example below). .sp Named blocks and in\-block use directive were added in re2c version 2.2. Since that version reusable blocks are allowed by default (no special option is needed). Before version 2.2 reuse mode was enabled with \fB\-r \-\-reusable\fP option. Before version 1.2 reusable blocks could not be mixed with normal blocks. .SS Example of a \fB!use\fP directive .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT #include // This example shows how to combine reusable re2c blocks: two blocks // (\(aqcolors\(aq and \(aqfish\(aq) are merged into one. The \(aqsalmon\(aq rule occurs // in both blocks; the \(aqfish\(aq block takes priority because it is used // earlier. Default rule * occurs in all three blocks; the local (not // inherited) definition takes priority. enum What { COLOR, FISH, DUNNO }; /*!rules:re2c:colors * { assert(false); } \(dqred\(dq | \(dqsalmon\(dq | \(dqmagenta\(dq { return COLOR; } */ /*!rules:re2c:fish * { assert(false); } \(dqhaddock\(dq | \(dqsalmon\(dq | \(dqeel\(dq { return FISH; } */ static What lex(const char *s) { const char *YYCURSOR = s, *YYMARKER; /*!re2c re2c:yyfill:enable = 0; re2c:define:YYCTYPE = char; !use:fish; !use:colors; * { return DUNNO; } // overrides inherited \(aq*\(aq rules */ } int main() { assert(lex(\(dqsalmon\(dq) == FISH); assert(lex(\(dqwhat?\(dq) == DUNNO); return 0; } .ft P .fi .UNINDENT .UNINDENT .SS Example of a \fB/*!use:re2c ... */\fP block .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT \-\-input\-encoding utf8 #include #include // This example supports multiple input encodings: UTF\-8 and UTF\-32. // Both lexers are generated from the same rules block, and the use // blocks add only encoding\-specific configurations. /*!rules:re2c re2c:yyfill:enable = 0; \(dq∀x ∃y\(dq { return 0; } * { return 1; } */ static int lex_utf8(const uint8_t *s) { const uint8_t *YYCURSOR = s, *YYMARKER; /*!use:re2c re2c:define:YYCTYPE = uint8_t; re2c:encoding:utf8 = 1; */ } static int lex_utf32(const uint32_t *s) { const uint32_t *YYCURSOR = s, *YYMARKER; /*!use:re2c re2c:define:YYCTYPE = uint32_t; re2c:encoding:utf32 = 1; */ } int main() { static const uint8_t s8[] = // UTF\-8 { 0xe2, 0x88, 0x80, 0x78, 0x20, 0xe2, 0x88, 0x83, 0x79 }; static const uint32_t s32[] = // UTF32 { 0x00002200, 0x00000078, 0x00000020, 0x00002203, 0x00000079 }; assert(lex_utf8(s8) == 0); assert(lex_utf32(s32) == 0); return 0; } .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 \(dqtag\(dq 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 = \(dq@@\(dq;\fP (specifies the template where \fB@@\fP is substituted with the name of each tag variable), and \fBseparator = \(dq\(dq;\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 C pointer 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 C pointer 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 a simple example of using s\-tags to parse semantic versions consisting of three numeric components: major, minor, patch (the latter is optional). See below for a more complex example that uses \fBYYFILL\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT #include #include struct SemVer { int major, minor, patch; }; static int s2n(const char *s, const char *e) { // pre\-parsed string to number int n = 0; for (; s < e; ++s) n = n * 10 + (*s \- \(aq0\(aq); return n; } static bool lex(const char *str, SemVer &ver) { const char *YYCURSOR = str, *YYMARKER; // User\-defined tag variables that are available in semantic action. const char *t1, *t2, *t3, *t4, *t5; // Autogenerated tag variables used by the lexer to track tag values. /*!stags:re2c format = \(aqconst char *@@;\en\(aq; */ /*!re2c re2c:yyfill:enable = 0; re2c:define:YYCTYPE = char; re2c:tags = 1; num = [0\-9]+; @t1 num @t2 \(dq.\(dq @t3 num @t4 (\(dq.\(dq @t5 num)? [\ex00] { ver.major = s2n(t1, t2); ver.minor = s2n(t3, t4); ver.patch = t5 != NULL ? s2n(t5, YYCURSOR \- 1) : 0; return true; } * { return false; } */ } int main() { SemVer v; assert(lex(\(dq23.34\(dq, v) && v.major == 23 && v.minor == 34 && v.patch == 0); assert(lex(\(dq1.2.999\(dq, v) && v.major == 1 && v.minor == 2 && v.patch == 999); assert(!lex(\(dq1.a\(dq, v)); return 0; } .ft P .fi .UNINDENT .UNINDENT .sp Here is a more complex example of using s\-tags with \fBYYFILL\fP to parse a file with newline\-separated semantic versions. Tag variables are part of the lexer state, and they are adjusted in \fBYYFILL\fP like other input positions. Note that it is necessary for s\-tags because their values are invalidated after shifting buffer contents. It may not be necessary in a custom implementation where tag variables store offsets relative to the start of the input string rather than the buffer, which may be the case with m\-tags. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT \-\-tags #include #include #include #include #include #define BUFSIZE 4095 struct Input { FILE *file; char buf[BUFSIZE + 1], *lim, *cur, *mar, *tok; // Tag variables must be part of the lexer state passed to YYFILL. // They don\(aqt correspond to tags and should be autogenerated by re2c. /*!stags:re2c format = \(aqconst char *@@;\(aq; */ bool eof; }; struct SemVer { int major, minor, patch; }; static bool operator==(const SemVer &x, const SemVer &y) { return x.major == y.major && x.minor == y.minor && x.patch == y.patch; } static int s2n(const char *s, const char *e) { // pre\-parsed string to number int n = 0; for (; s < e; ++s) n = n * 10 + (*s \- \(aq0\(aq); return n; } static int fill(Input &in) { if (in.eof) return 1; const size_t shift = in.tok \- in.buf; const size_t used = in.lim \- in.tok; // Error: lexeme too long. In real life could reallocate a larger buffer. if (shift < 1) return 2; // Shift buffer contents (discard everything up to the current token). memmove(in.buf, in.tok, used); in.lim \-= shift; in.cur \-= shift; in.mar \-= shift; in.tok \-= shift; // Tag variables need to be shifted like other input positions. The check // for non\-NULL is only needed if some tags are nested inside of alternative // or repetition, so that they can have NULL value. /*!stags:re2c format = \(dqif (in.@@) in.@@ \-= shift;\en\(dq; */ // Fill free space at the end of buffer with new data from file. in.lim += fread(in.lim, 1, BUFSIZE \- used, in.file); in.lim[0] = 0; in.eof = in.lim < in.buf + BUFSIZE; return 0; } static bool lex(Input &in, std::vector &vers) { // User\-defined local variables that store final tag values. // They are different from tag variables autogenerated with \(gastags:re2c\(ga, // as they are set at the end of match and used only in semantic actions. const char *t1, *t2, *t3, *t4; for (;;) { in.tok = in.cur; /*!re2c re2c:eof = 0; re2c:api:style = free\-form; re2c:define:YYCTYPE = char; re2c:define:YYCURSOR = in.cur; re2c:define:YYMARKER = in.mar; re2c:define:YYLIMIT = in.lim; re2c:define:YYFILL = \(dqfill(in) == 0\(dq; re2c:tags:expression = \(dqin.@@\(dq; num = [0\-9]+; num @t1 \(dq.\(dq @t2 num @t3 (\(dq.\(dq @t4 num)? [\en] { int major = s2n(in.tok, t1); int minor = s2n(t2, t3); int patch = t4 != NULL ? s2n(t4, in.cur \- 1) : 0; SemVer ver = {major, minor, patch}; vers.push_back(ver); continue; } $ { return true; } * { return false; } */} } int main() { const char *fname = \(dqinput\(dq; const SemVer semver = {1, 22, 333}; std::vector expect(BUFSIZE, semver), actual; // Prepare input file (make sure it exceeds buffer size). FILE *f = fopen(fname, \(dqw\(dq); for (int i = 0; i < BUFSIZE; ++i) fprintf(f, \(dq1.22.333\en\(dq); fclose(f); // Reopen input file for reading. f = fopen(fname, \(dqr\(dq); // Initialize lexer state: all pointers are at the end of buffer. Input in; in.file = f; in.cur = in.mar = in.tok = in.lim = in.buf + BUFSIZE; /*!stags:re2c format = \(dqin.@@ = in.lim;\en\(dq; */ in.eof = false; // Sentinel (at YYLIMIT pointer) is set to zero, which triggers YYFILL. *in.lim = 0; // Run the lexer and check results. assert(lex(in, actual) && expect == actual); // Cleanup: remove input file. fclose(f); remove(fname); return 0; } .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of using POSIX capturing groups to parse semantic versions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT #include #include // Maximum number of capturing groups among all rules. /*!maxnmatch:re2c*/ struct SemVer { int major, minor, patch; }; static int s2n(const char *s, const char *e) { // pre\-parsed string to number int n = 0; for (; s < e; ++s) n = n * 10 + (*s \- \(aq0\(aq); return n; } static bool lex(const char *str, SemVer &ver) { const char *YYCURSOR = str, *YYMARKER; // Allocate memory for capturing parentheses (twice the number of groups). const char *yypmatch[YYMAXNMATCH * 2]; size_t yynmatch; // Autogenerated tag variables used by the lexer to track tag values. /*!stags:re2c format = \(aqconst char *@@;\en\(aq; */ /*!re2c re2c:yyfill:enable = 0; re2c:define:YYCTYPE = char; re2c:posix\-captures = 1; num = [0\-9]+; (num) \(dq.\(dq (num) (\(dq.\(dq num)? [\ex00] { // \(gayynmatch\(ga is the number of capturing groups assert(yynmatch == 4); // Even \(gayypmatch\(ga values are for opening parentheses, odd values // are for closing parentheses, the first group is the whole match. ver.major = s2n(yypmatch[2], yypmatch[3]); ver.minor = s2n(yypmatch[4], yypmatch[5]); ver.patch = yypmatch[6] ? s2n(yypmatch[6] + 1, yypmatch[7]) : 0; return true; } * { return false; } */ } int main() { SemVer v; assert(lex(\(dq23.34\(dq, v) && v.major == 23 && v.minor == 34 && v.patch == 0); assert(lex(\(dq1.2.999\(dq, v) && v.major == 1 && v.minor == 2 && v.patch == 999); assert(!lex(\(dq1.a\(dq, v)); return 0; } .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of using m\-tags to parse a version with a variable number of components. Tag variables are stored in a trie. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT #include #include #include static const int MTAG_ROOT = \-1; // An m\-tag tree is a way to store histories with an O(1) copy operation. // Histories naturally form a tree, as they have common start and fork at some // point. The tree is stored as an array of pairs (tag value, link to parent). // An m\-tag is represented with a single link in the tree (array index). struct Mtag { const char *elem; // tag value int pred; // index of the predecessor node or root }; typedef std::vector MtagTrie; typedef std::vector Ver; // unbounded number of version components static int s2n(const char *s, const char *e) { // pre\-parsed string to number int n = 0; for (; s < e; ++s) n = n * 10 + (*s \- \(aq0\(aq); return n; } // Append a single value to an m\-tag history. static void add_mtag(MtagTrie &trie, int &mtag, const char *value) { Mtag m = {value, mtag}; mtag = (int)trie.size(); trie.push_back(m); } // Recursively unwind tag histories and collect version components. static void unfold(const MtagTrie &trie, int x, int y, Ver &ver) { // Reached the root of the m\-tag tree, stop recursion. if (x == MTAG_ROOT && y == MTAG_ROOT) return; // Unwind history further. unfold(trie, trie[x].pred, trie[y].pred, ver); // Get tag values. Tag histories must have equal length. assert(x != MTAG_ROOT && y != MTAG_ROOT); const char *ex = trie[x].elem, *ey = trie[y].elem; if (ex != NULL && ey != NULL) { // Both tags are valid pointers, extract component. ver.push_back(s2n(ex, ey)); } else { // Both tags are NULL (this corresponds to zero repetitions). assert(ex == NULL && ey == NULL); } } static bool parse(const char *str, Ver &ver) { const char *YYCURSOR = str, *YYMARKER; MtagTrie mt; // User\-defined tag variables that are available in semantic action. const char *t1, *t2; int t3, t4; // Autogenerated tag variables used by the lexer to track tag values. /*!stags:re2c format = \(aqconst char *@@ = NULL;\(aq; */ /*!mtags:re2c format = \(aqint @@ = MTAG_ROOT;\(aq; */ /*!re2c re2c:api:style = free\-form; re2c:define:YYCTYPE = char; re2c:define:YYSTAGP = \(dq@@ = YYCURSOR;\(dq; re2c:define:YYSTAGN = \(dq@@ = NULL;\(dq; re2c:define:YYMTAGP = \(dqadd_mtag(mt, @@, YYCURSOR);\(dq; re2c:define:YYMTAGN = \(dqadd_mtag(mt, @@, NULL);\(dq; re2c:yyfill:enable = 0; re2c:tags = 1; num = [0\-9]+; @t1 num @t2 (\(dq.\(dq #t3 num #t4)* [\ex00] { ver.clear(); ver.push_back(s2n(t1, t2)); unfold(mt, t3, t4, ver); return true; } * { return false; } */ } int main() { Ver v; assert(parse(\(dq1\(dq, v) && v == Ver({1})); assert(parse(\(dq1.2.3.4.5.6.7\(dq, v) && v == Ver({1, 2, 3, 4, 5, 6, 7})); assert(!parse(\(dq1.2.\(dq, v)); return 0; } .ft P .fi .UNINDENT .UNINDENT .SH ENCODING SUPPORT .sp It is necessary to understand the difference between \fBcode points\fP and \fBcode units\fP\&. A code point is a numeric identifier of a symbol. A code unit is the smallest unit of storage in the encoded text. A single code point may be represented with one or more code units. In a fixed\-length encoding all code points are represented with the same number of code units. In a variable\-length encoding code points may be represented with a different number of code units. Note that the \(dqany\(dq rule \fB[^]\fP matches any code point, but not necessarily any code unit (the only way to match any code unit regardless of the encoding is the default rule \fB*\fP). The generated lexer works with a stream of code units: \fByych\fP stores a code unit, and \fBYYCTYPE\fP is the code unit type. Regular expressions, on the other hand, are specified in terms of code points. When re2c compiles regular expressions to automata it translates code points to code units. This is generally not a simple mapping: in variable\-length encodings a single code point range may get translated to a complex code unit graph. The following encodings are supported: .INDENT 0.0 .IP \(bu 2 \fBASCII\fP (enabled by default). It is a fixed\-length encoding with code space \fB[0\-255]\fP and 1\-byte code points and code units. .IP \(bu 2 \fBEBCDIC\fP (enabled with \fB\-\-ebcdic\fP or \fBre2c:encoding:ebcdic\fP). It is a fixed\-length encoding with code space \fB[0\-255]\fP and 1\-byte code points and code units. .IP \(bu 2 \fBUCS2\fP (enabled with \fB\-\-ucs2\fP or \fBre2c:encoding:ucs2\fP). It is a fixed\-length encoding with code space \fB[0\-0xFFFF]\fP and 2\-byte code points and code units. .IP \(bu 2 \fBUTF8\fP (enabled with \fB\-\-utf8\fP or \fBre2c:encoding:utf8\fP). It is a variable\-length Unicode encoding. Code unit size is 1 byte. Code points are represented with 1 \-\- 4 code units. .IP \(bu 2 \fBUTF16\fP (enabled with \fB\-\-utf16\fP or \fBre2c:encoding:utf16\fP). It is a variable\-length Unicode encoding. Code unit size is 2 bytes. Code points are represented with 1 \-\- 2 code units. .IP \(bu 2 \fBUTF32\fP (enabled with \fB\-\-utf32\fP or \fBre2c:encoding:utf32\fP). It is a fixed\-length Unicode encoding with code space \fB[0\-0x10FFFF]\fP and 4\-byte code points and code units. .UNINDENT .sp Include file \fBinclude/unicode_categories.re\fP provides re2c definitions for the standard Unicode categories. .sp Option \fB\-\-input\-encoding\fP specifies source file encoding, which can be used to enable Unicode literals in regular expressions. For example \fB\-\-input\-encoding utf8\fP tells re2c that the source file is in UTF8 (it differs from \fB\-\-utf8\fP which sets input text encoding). Option \fB\-\-encoding\-policy\fP specifies the way re2c handles Unicode surrogates (code points in range \fB[0xD800\-0xDFFF]\fP). .sp Below is an example of a lexer for UTF8 encoded Unicode identifiers. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT \-8 \-\-case\-ranges \-i #include #include /*!include:re2c \(dqunicode_categories.re\(dq */ static int lex(const char *s) { const char *YYCURSOR = s, *YYMARKER; /*!re2c re2c:define:YYCTYPE = \(aqunsigned char\(aq; re2c:yyfill:enable = 0; // Simplified \(dqUnicode Identifier and Pattern Syntax\(dq // (see https://unicode.org/reports/tr31) id_start = L | Nl | [$_]; id_continue = id_start | Mn | Mc | Nd | Pc | [\eu200D\eu05F3]; identifier = id_start id_continue*; identifier { return 0; } * { return 1; } */ } int main() { assert(lex(\(dq_Ыдентификатор\(dq) == 0); return 0; } .ft P .fi .UNINDENT .UNINDENT .SH INCLUDE FILES .sp re2c allows one to include other files using directive \fB/*!include:re2c FILE */\fP or \fB!include FILE ;\fP, where \fBFILE\fP is a path to the file to be included. The first form should be used outside of re2c blocks, and the second form allows one to include a file in the middle of a re2c block. 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. Include directives in re2c work 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. Use \fB\-\-depfile\fP option to track build dependencies of the output file on include files. 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. Below is an example of using include directive. .SS Include file 1 (definitions.h) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C typedef enum { OK, FAIL } Result; /*!re2c number = [1\-9][0\-9]*; */ .ft P .fi .UNINDENT .UNINDENT .SS Include file 2 (extra_rules.re.inc) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // floating\-point numbers frac = [0\-9]* \(dq.\(dq [0\-9]+ | [0\-9]+ \(dq.\(dq; exp = \(aqe\(aq [+\-]? [0\-9]+; float = frac exp? | [0\-9]+ exp; float { return OK; } .ft P .fi .UNINDENT .UNINDENT .SS Input file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C // re2c $INPUT \-o $OUTPUT \-i #include /*!include:re2c \(dqdefinitions.h\(dq */ Result lex(const char *s) { const char *YYCURSOR = s, *YYMARKER; /*!re2c re2c:define:YYCTYPE = char; re2c:yyfill:enable = 0; * { return FAIL; } number { return OK; } !include \(dqextra_rules.re.inc\(dq; */ } int main() { assert(lex(\(dq123\(dq) == OK); assert(lex(\(dq123.4567\(dq) == OK); return 0; } .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 // re2c $INPUT \-o $OUTPUT \-i \-\-header lexer/state.h #include #include #include \(dqlexer/state.h\(dq // the header is generated by re2c /*!header:re2c:on*/ struct LexerState { const char *str, *cur; /*!stags:re2c format = \(dqconst char *@@;\(dq; */ }; /*!header:re2c:off*/ long lex(LexerState& st) { const char *t; /*!re2c re2c:header = \(dqlexer/state.h\(dq; re2c:yyfill:enable = 0; re2c:define:YYCTYPE = char; re2c:define:YYCURSOR = \(dqst.cur\(dq; re2c:tags = 1; re2c:tags:expression = \(dqst.@@\(dq; [a]* @t [b]* { return t \- st.str; } */ } int main() { const char *s = \(dqab\(dq; LexerState st = { s, s /*!stags:re2c format = \(dq, NULL\(dq; */ }; assert(lex(st) == 1); return 0; } .ft P .fi .UNINDENT .UNINDENT .SS Header file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /* Generated by re2c */ typedef struct { const char *str, *cur, *mar; const char *yyt1; } LexerState; .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. .