1
2The generated code interfaces with the outer program with the help of
3*primitives* -- symbolic names that can be defined as variables, functions or
4macros in the target language (collectively referred to as the API).
5The primitives should be defined by the user. This approach gives the user
6freedom and flexibility in customizing the lexer, but it also requires some
7understanding of how the lexer works in order to implement the primitives
8correctly and efficiently. The manual provides examples for the most popular
9use cases. For the full list of primitives see the `interface primitives`_
10section.
11
12.. _generic_api:
13
14There are two *API flavours* that define the set of primitives used by re2c:
15
16  **Pointer API**
17    This API is also called *default API*, since it was historically the first,
18    and for a long time the only one. This is a more restrictive API based on C
19    pointer arithmetics. It consists of pointer-like primitives ``YYCURSOR``,
20    ``YYMARKER``, ``YYCTXMARKER``, ``YYLIMIT`` (which are normally defined as
21    pointers of type ``YYCTYPE*``) and ``YYFILL``. Pointer API is enabled by
22    default for the C backend, and it cannot be used with backends that do not
23    support pointer arithmetics.
24
25  **Generic API**
26    This is a more flexible API that does not assume pointer semantics. It
27    consists of primitives
28    ``YYPEEK``,
29    ``YYSKIP``,
30    ``YYBACKUP``,
31    ``YYBACKUPCTX``,
32    ``YYSTAGP``,
33    ``YYSTAGN``,
34    ``YYMTAGP``,
35    ``YYMTAGN``,
36    ``YYRESTORE``,
37    ``YYRESTORECTX``,
38    ``YYRESTORETAG``,
39    ``YYSHIFT``,
40    ``YYSHIFTSTAG``,
41    ``YYSHIFTMTAG``,
42    ``YYLESSTHAN``
43    and ``YYFILL``.
44    For the C backend generic API is enabled with ``--input custom`` option or
45    ``re2c:flags:input = custom;`` configuration; for the Go backend it is
46    enabled by default. Generic API was added in version 0.14. It is
47    intentionally designed to give the user as much freedom as possible in
48    redefining the input model and the semantics of different actions performed
49    by the generated code.
50
51There are two *API styles* determine the form in which the primitives should be
52defined:
53
54