-
Notifications
You must be signed in to change notification settings - Fork 169
Commit
- Loading branch information
There are no files selected for viewing
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Large diffs are not rendered by default.
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
|re2c| works as a preprocessor. It reads the input file (which is usually a | ||
|lang_name| program, 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. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,117 @@ | ||
Blocks | ||
------ | ||
|
||
Block start and end markers are either ``/*!re2c`` and ``*/`` (suitable for | ||
languages that have C-style multiline comments), or ``%{`` and ``%}`` (suitable | ||
for other languages). Blocks may have optional names that allow them to be | ||
referenced in other parts of the program (named blocks were added in version | ||
2.2). There are different kinds of blocks: | ||
|
||
``/*!re2c[:<name>] ... */`` or ``%{[:<name>] ... %}`` | ||
A *global block* 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 `options`_. | ||
|
||
``/*!local:re2c[:<name>] ... */`` or ``%{local[:<name>] ... %}`` | ||
A *local block* is like a global block, but the names and configurations in | ||
it have local scope (they do not affect other blocks). | ||
|
||
``/*!rules:re2c[:<name>] ... */`` or ``%{rules[:<name>] ... %}`` | ||
A *rules block* is like a local block, but it does not generate any code by | ||
itself, nor does it add any definitions to the global scope -- it is meant | ||
to be reused in other blocks. This is a way of sharing code (more details in | ||
the `reusable blocks`_ section). Prior to |re2c| version 2.2 rules blocks | ||
required ``-r --reusable`` option. | ||
|
||
``/*!use:re2c[:<name>] ... */`` or ``%{use[:<name>] ... %}`` | ||
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 ``-r --reusable`` option. | ||
|
||
``/*!max:re2c[:<name1>[:<name2>...]] ... */`` or ``%{max[:<name1>[:<name2>...]] ... %}`` | ||
A directive that generates ``YYMAXFILL`` definition. | ||
An optional list of block names specifies which blocks should be included | ||
when computing ``YYMAXFILL`` value (if the list is empty, all blocks are | ||
included). | ||
By default the generated code is a macro-definition for C | ||
(``#define YYMAXFILL <n>``), or a global variable for Go | ||
(``var YYMAXFILL int = <n>``). It can be customized with an optional | ||
configuration ``format`` that specifies a template string where ``@@{max}`` | ||
(or ``@@`` for short) is replaced with the numeric value of ``YYMAXFILL``. | ||
|
||
``/*!maxnmatch:re2c[:<name1>[:<name2>...]] ... */`` or ``%{maxnmatch[:<name1>[:<name2>...]] ... %}`` | ||
A directive that generates ``YYMAXNMATCH`` definition (it requires | ||
``-P --posix-captures`` option). | ||
An optional list of block names specifies which blocks should be included | ||
when computing ``YYMAXNMATCH`` value (if the list is empty, all blocks are | ||
included). | ||
By default the generated code is a macro-definition for C | ||
(``#define YYMAXNMATCH <n>``), or a global variable for Go | ||
(``var YYMAXNMATCH int = <n>``). It can be customized with an optional | ||
configuration ``format`` that specifies a template string where ``@@{max}`` | ||
(or ``@@`` for short) is replaced with the numeric value of ``YYMAXNMATCH``. | ||
|
||
``/*!stags:re2c[:<name1>[:<name2>...]] ... */``, ``/*!mtags:re2c[:<name1>[:<name2>...]] ... */`` or ``%{stags[:<name1>[:<name2>...]] ... %}``, ``%{mtags[:<name1>[:<name2>...]] ... %{`` | ||
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: ``format`` and ``separator``. | ||
Configuration ``format`` specifies a template string where ``@@{tag}`` (or | ||
``@@`` for short) is replaced with the name of each tag variable. | ||
Configuration ``separator`` specifies a piece of code used to join the | ||
generated ``format`` pieces for different tag variables. | ||
|
||
``/*!getstate:re2c[:<name1>[:<name2>...]] ... */`` or ``%{getstate[:<name1>[:<name2>...]] ... %}`` | ||
A directive that generates conditional dispatch on the lexer state (it | ||
requires ``--storable-state`` 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 ``--loop-switch`` option and Rust, | ||
as it requires cross-block transitions that are unsupported without the | ||
``goto`` statement. | ||
|
||
``/*!conditions:re2c[:<name1>[:<name2>...]] ... */``, ``/*!types:re2c... */`` or ``%{conditions[:<name1>[:<name2>...]] ... %}``, ``%{types... %}`` | ||
A directive that generates condition enumeration (it requires | ||
``--conditions`` 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 ``YYCONDTYPE``. It can be | ||
customized with optional configurations ``format`` and ``separator``. | ||
Configuration ``format`` specifies a template string where ``@@{cond}`` (or | ||
``@@`` for short) is replaced with the name of each condition, and | ||
``@@{num}`` is replaced with a numeric index of that condition. | ||
Configuration ``separator`` specifies a piece of code used to join the | ||
generated ``format`` pieces for different conditions. | ||
|
||
``/*!include:re2c <file> */`` or ``%{include <file> %}`` | ||
This directive allows one to include ``<file>``, 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 ``#include`` works in C/C++. This | ||
directive can be used together with the ``--depfile`` option to generate | ||
build system dependencies on the included files. | ||
|
||
``/*!header:re2c:on*/`` or ``%{header:on %}`` | ||
This directive marks the start of header file. Everything after it and up to | ||
the following ``/*!header:re2c:off*/`` directive is processed by |re2c| and | ||
written to the header file specified with ``-t --type-header`` option. | ||
|
||
``/*!header:re2c:off*/`` or ``%{header:off %}`` | ||
This directive marks the end of header file started with | ||
``/*!header:re2c:on*/``. | ||
|
||
``/*!ignore:re2c ... */`` or ``%{ignore:re2c ... %}`` | ||
A block which contents are ignored and removed from the output file. | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,5 @@ | ||
Configurations | ||
-------------- | ||
|
||
``re2c:api``, ``re2c:flags:input`` | ||
Same as the ``--api`` option. | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
Directives | ||
---------- | ||
|
||
``!use:<name>;`` | ||
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 ``*``, ``$`` and ``<!>`` | ||
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. | ||
|
||
``!include <file>;`` | ||
This directive is the same as ``/*!include:re2c <file> */``, except that it | ||
should be used inside of a |re2c| block. |
This file was deleted.
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,5 @@ | ||
Regular expressions | ||
------------------- | ||
|
||
|re2c| uses the following syntax for regular expressions: | ||
|
||
|