]> granicus.if.org Git - re2c/commitdiff
Partially described '--skeleton'.
authorUlya Trofimovich <skvadrik@gmail.com>
Thu, 19 Nov 2015 12:14:02 +0000 (12:14 +0000)
committerUlya Trofimovich <skvadrik@gmail.com>
Thu, 19 Nov 2015 12:14:02 +0000 (12:14 +0000)
21 files changed:
Makefile
src/manual/features/dot/dot.rst
src/manual/features/skeleton/collapsed.png [new file with mode: 0644]
src/manual/features/skeleton/collapsed_next.png [new file with mode: 0644]
src/manual/features/skeleton/example.c [new file with mode: 0644]
src/manual/features/skeleton/example.c.line4.input [new file with mode: 0644]
src/manual/features/skeleton/example.c.line4.keys [new file with mode: 0644]
src/manual/features/skeleton/example.png [new file with mode: 0644]
src/manual/features/skeleton/example.rst [new file with mode: 0644]
src/manual/features/skeleton/failures.rst [new file with mode: 0644]
src/manual/features/skeleton/gen.sh [new file with mode: 0755]
src/manual/features/skeleton/generating_data.rst [new file with mode: 0644]
src/manual/features/skeleton/hex2.re [new file with mode: 0644]
src/manual/features/skeleton/montage.sh [new file with mode: 0755]
src/manual/features/skeleton/plot.gnuplot [new file with mode: 0644]
src/manual/features/skeleton/plot_input.png [new file with mode: 0644]
src/manual/features/skeleton/plot_keys.png [new file with mode: 0644]
src/manual/features/skeleton/points_1_7 [new file with mode: 0644]
src/manual/features/skeleton/points_8_1024 [new file with mode: 0644]
src/manual/features/skeleton/skeleton.rst
src/manual/features/skeleton/use.rst [new file with mode: 0644]

index 512ef2c13ad6080a38c7a3bcf7871cdbea46fcd0..18c3c9a61a63c07e29f75e27083ba959fc0cbbf5 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -89,6 +89,16 @@ SRC_OTH = \
     src/manual/features/dot/php_json_neato.png \
     src/manual/features/dot/utf8_any.re \
     src/manual/features/dot/php_json.re \
+    src/manual/features/skeleton/collapsed.png \
+    src/manual/features/skeleton/collapsed_next.png \
+    src/manual/features/skeleton/example.c \
+    src/manual/features/skeleton/example.c.line4.input \
+    src/manual/features/skeleton/example.c.line4.keys \
+    src/manual/features/skeleton/example.png \
+    src/manual/features/skeleton/gen.sh \
+    src/manual/features/skeleton/hex2.re \
+    src/manual/features/skeleton/plot_input.png \
+    src/manual/features/skeleton/plot_keys.png \
     src/about/1994_bumbulis_cowan_re2c_a_more_versatile_scanner_generator.pdf
 
 OBJ_RST = $(SRC_RST:%.rst=%.html)
index 362973ba1831d0f84d464006840eece96abc1f0e..c3167a5e258b361a1aed29cbb2b6936fdb312516 100644 (file)
@@ -18,7 +18,7 @@ Generate and render :
 .. code-block::
 
     $ re2c -D8 -o utf8_any.dot utf8_any.re
-    $ dot -T png -o utf8_any.png utf8_any.dot
+    $ dot -Tpng -o utf8_any.png utf8_any.dot
 
 Here is the picture:
 
@@ -43,12 +43,12 @@ Generate .dot file:
 
     $ re2c -Dc -o php_json.dot php_json.re
 
-Render with ```dot -G ratio=0.3 -T png -o php_json_dot.png php_json.dot```:
+Render with ```dot -Gratio=0.3 -Tpng -o php_json_dot.png php_json.dot```:
 
 .. image:: php_json_dot.png
     :width: 80%
 
-Render with ```neato -E len=4 -T png -o php_json_neato.png php_json.dot```:
+Render with ```neato -Elen=4 -Tpng -o php_json_neato.png php_json.dot```:
 
 .. image:: php_json_neato.png
     :width: 50%
diff --git a/src/manual/features/skeleton/collapsed.png b/src/manual/features/skeleton/collapsed.png
new file mode 100644 (file)
index 0000000..d6d77a0
Binary files /dev/null and b/src/manual/features/skeleton/collapsed.png differ
diff --git a/src/manual/features/skeleton/collapsed_next.png b/src/manual/features/skeleton/collapsed_next.png
new file mode 100644 (file)
index 0000000..de1cdd0
Binary files /dev/null and b/src/manual/features/skeleton/collapsed_next.png differ
diff --git a/src/manual/features/skeleton/example.c b/src/manual/features/skeleton/example.c
new file mode 100644 (file)
index 0000000..7bd0335
--- /dev/null
@@ -0,0 +1,242 @@
+/* Generated by re2c 0.14.1.dev on Mon Nov 16 15:03:12 2015*/
+
+#include <stdio.h>
+#include <stdlib.h> /* malloc, free */
+
+static void *read_file
+    ( const char *fname
+    , size_t unit
+    , size_t padding
+    , size_t *pfsize
+    )
+{
+    void *buffer = NULL;
+    size_t fsize = 0;
+
+    /* open file */
+    FILE *f = fopen(fname, "rb");
+    if(f == NULL) {
+        goto error;
+    }
+
+    /* get file size */
+    fseek(f, 0, SEEK_END);
+    fsize = (size_t) ftell(f) / unit;
+    fseek(f, 0, SEEK_SET);
+
+    /* allocate memory for file and padding */
+    buffer = malloc(unit * (fsize + padding));
+    if (buffer == NULL) {
+        goto error;
+    }
+
+    /* read the whole file in memory */
+    if (fread(buffer, unit, fsize, f) != fsize) {
+        goto error;
+    }
+
+    fclose(f);
+    *pfsize = fsize;
+    return buffer;
+
+error:
+    fprintf(stderr, "error: cannot read file '%s'\n", fname);
+    free(buffer);
+    if (f != NULL) {
+        fclose(f);
+    }
+    return NULL;
+}
+
+#define YYCTYPE unsigned char
+#define YYKEYTYPE unsigned char
+#define YYPEEK() *cursor
+#define YYSKIP() ++cursor
+#define YYLESSTHAN(n) (limit - cursor) < n
+#define YYFILL(n) { break; }
+
+static int action_line4
+    ( unsigned int i
+    , const YYKEYTYPE *keys
+    , const YYCTYPE *start
+    , const YYCTYPE *token
+    , const YYCTYPE **cursor
+    , YYKEYTYPE rule_act
+    )
+{
+    const long pos = token - start;
+    const long len_act = *cursor - token;
+    const long len_exp = (long) keys [3 * i + 1];
+    const YYKEYTYPE rule_exp = keys [3 * i + 2];
+    if (rule_exp == 255) {
+        fprintf
+            ( stderr
+            , "warning: lex_line4: control flow is undefined for input"
+                " at position %ld, rerun re2c with '-W'\n"
+            , pos
+            );
+    }
+    if (len_act == len_exp && rule_act == rule_exp) {
+        const YYKEYTYPE offset = keys[3 * i];
+        *cursor = token + offset;
+        return 0;
+    } else {
+        fprintf
+            ( stderr
+            , "error: lex_line4: at position %ld (iteration %u):\n"
+                "\texpected: match length %ld, rule %u\n"
+                "\tactual:   match length %ld, rule %u\n"
+            , pos
+            , i
+            , len_exp
+            , rule_exp
+            , len_act
+            , rule_act
+            );
+        return 1;
+    }
+}
+
+int lex_line4()
+{
+    const size_t padding = 2; /* YYMAXFILL */
+    int status = 0;
+    size_t input_len = 0;
+    size_t keys_count = 0;
+    YYCTYPE *input = NULL;
+    YYKEYTYPE *keys = NULL;
+    const YYCTYPE *cursor = NULL;
+    const YYCTYPE *limit = NULL;
+    const YYCTYPE *token = NULL;
+    const YYCTYPE *eof = NULL;
+    unsigned int i = 0;
+
+    input = (YYCTYPE *) read_file
+        ("example.c.line4.input"
+        , sizeof (YYCTYPE)
+        , padding
+        , &input_len
+        );
+    if (input == NULL) {
+        status = 1;
+        goto end;
+    }
+
+    keys = (YYKEYTYPE *) read_file
+        ("example.c.line4.keys"
+        , 3 * sizeof (YYKEYTYPE)
+        , 0
+        , &keys_count
+        );
+    if (keys == NULL) {
+        status = 1;
+        goto end;
+    }
+
+    cursor = input;
+    limit = input + input_len + padding;
+    eof = input + input_len;
+
+    for (i = 0; status == 0 && i < keys_count; ++i) {
+        token = cursor;
+        YYCTYPE yych;
+
+        if (YYLESSTHAN (2)) YYFILL(2);
+        yych = YYPEEK ();
+        switch (yych) {
+        case '0':
+        case '1':
+        case '2':
+        case '3':
+        case '4':
+        case '5':
+        case '6':
+        case '7':
+        case '8':
+        case '9':
+        case 'A':
+        case 'B':
+        case 'C':
+        case 'D':
+        case 'E':
+        case 'F':
+        case 'a':
+        case 'b':
+        case 'c':
+        case 'd':
+        case 'e':
+        case 'f':    goto yy4;
+        default:    goto yy2;
+        }
+yy2:
+        YYSKIP ();
+yy3:
+        status = action_line4(i, keys, input, token, &cursor, 254);
+        continue;
+yy4:
+        YYSKIP ();
+        yych = YYPEEK ();
+        switch (yych) {
+        case '0':
+        case '1':
+        case '2':
+        case '3':
+        case '4':
+        case '5':
+        case '6':
+        case '7':
+        case '8':
+        case '9':
+        case 'A':
+        case 'B':
+        case 'C':
+        case 'D':
+        case 'E':
+        case 'F':
+        case 'a':
+        case 'b':
+        case 'c':
+        case 'd':
+        case 'e':
+        case 'f':    goto yy5;
+        default:    goto yy3;
+        }
+yy5:
+        YYSKIP ();
+        status = action_line4(i, keys, input, token, &cursor, 0);
+        continue;
+
+    }
+    if (status == 0) {
+        if (cursor != eof) {
+            status = 1;
+            const long pos = token - input;
+            fprintf(stderr, "error: lex_line4: unused input strings left at position %ld\n", pos);
+        }
+        if (i != keys_count) {
+            status = 1;
+            fprintf(stderr, "error: lex_line4: unused keys left after %u iterations\n", i);
+        }
+    }
+
+end:
+    free(input);
+    free(keys);
+
+    return status;
+}
+
+#undef YYCTYPE
+#undef YYKEYTYPE
+#undef YYPEEK
+#undef YYSKIP
+#undef YYLESSTHAN
+#undef YYFILL
+
+int main()
+{
+    if(lex_line4() != 0) {
+        return 1;
+    }
+    return 0;
+}
diff --git a/src/manual/features/skeleton/example.c.line4.input b/src/manual/features/skeleton/example.c.line4.input
new file mode 100644 (file)
index 0000000..d75e6c9
Binary files /dev/null and b/src/manual/features/skeleton/example.c.line4.input differ
diff --git a/src/manual/features/skeleton/example.c.line4.keys b/src/manual/features/skeleton/example.c.line4.keys
new file mode 100644 (file)
index 0000000..a6d2ba5
Binary files /dev/null and b/src/manual/features/skeleton/example.c.line4.keys differ
diff --git a/src/manual/features/skeleton/example.png b/src/manual/features/skeleton/example.png
new file mode 100644 (file)
index 0000000..4fe9c3e
Binary files /dev/null and b/src/manual/features/skeleton/example.png differ
diff --git a/src/manual/features/skeleton/example.rst b/src/manual/features/skeleton/example.rst
new file mode 100644 (file)
index 0000000..29571e5
--- /dev/null
@@ -0,0 +1,91 @@
+Example
+~~~~~~~
+
+`[hex2.re] <hex2.re>`_
+
+.. include:: hex2.re
+    :code: c
+    :number-lines:
+
+Here is a very simple program (it tries to match two-digit hexadecimal numbers).
+We can see the generated DFA using ```re2c -D hex2.re | dot -Gratio=0.5 -Tpng -o example.png```:
+
+.. image:: example.png
+    :width: 40%
+
+Given this program, ```re2c -S -o example.c hex2.re``` generates three files:
+``example.c`` (main program), ``example.c.line4.input`` (input data) and ``example.c.line4.keys`` (expected match results).
+First, let's look at the generated strings:
+
+`[example.c.line4.input] <example.c.line4.input>`_
+
+.. code-block:: bash
+
+    $ hexdump -C example.c.line4.input
+    00000000  00 2f 3a 40 47 60 67 ff  30 30 30 39 30 41 30 46  |./:@G`g.00090A0F|
+    00000010  30 61 30 66 39 30 39 39  39 41 39 46 39 61 39 66  |0a0f90999A9F9a9f|
+    00000020  41 30 41 39 41 41 41 46  41 61 41 66 46 30 46 39  |A0A9AAAFAaAfF0F9|
+    00000030  46 41 46 46 46 61 46 66  61 30 61 39 61 41 61 46  |FAFFFaFfa0a9aAaF|
+    00000040  61 61 61 66 66 30 66 39  66 41 66 46 66 61 66 66  |aaaff0f9fAfFfaff|
+    00000050  30 00 30 2f 30 3a 30 40  30 47 30 60 30 67 30 ff  |0.0/0:0@0G0`0g0.|
+    00000060  39 00 39 2f 39 3a 39 40  39 47 39 60 39 67 39 ff  |9.9/9:9@9G9`9g9.|
+    00000070  41 00 41 2f 41 3a 41 40  41 47 41 60 41 67 41 ff  |A.A/A:A@AGA`AgA.|
+    00000080  46 00 46 2f 46 3a 46 40  46 47 46 60 46 67 46 ff  |F.F/F:F@FGF`FgF.|
+    00000090  61 00 61 2f 61 3a 61 40  61 47 61 60 61 67 61 ff  |a.a/a:a@aGa`aga.|
+    000000a0  66 00 66 2f 66 3a 66 40  66 47 66 60 66 67 66 ff  |f.f/f:f@fGf`fgf.|
+    000000b0
+
+Byte sequences correspond to the paths in DFA.
+All strings are glued together, so it's hard to tell where is the end of one string and the beginning of another.
+For that re2c generates keys:
+
+`[example.c.line4.keys] <example.c.line4.keys>`_
+
+.. code-block:: bash
+
+    $ hexdump -v -e '"%04_ax| " 24/1 "%02x " "\n"' example.c.line4.keys 
+    0000| 01 01 fe 01 01 fe 01 01 fe 01 01 fe 01 01 fe 01 01 fe 01 01 fe 01 01 fe
+    0018| 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00
+    0030| 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00
+    0048| 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00
+    0060| 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00 02 02 00
+    0078| 02 02 00 02 02 00 02 02 00 02 02 00 02 01 fe 02 01 fe 02 01 fe 02 01 fe
+    0090| 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe
+    00a8| 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe
+    00c0| 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe
+    00d8| 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe
+    00f0| 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe 02 01 fe
+    0108| 02 01 fe 02 01 fe 02 01 fe 02 01 fe                              
+
+A key is a triplet: string length, the length of matching prefix and the number of matching rule.
+All three components occupy equal amount of memory (re2c uses unsigned integer type of minimal sufficient width).
+Keys are packed into array of length ``3 * n`` (where ``n`` is the number of keys).
+In our case each triplet occupies three bytes.
+
+And finally, the program itself:
+
+`[example.c] <example.c>`_
+
+.. include:: example.c
+    :code: c
+    :number-lines:
+
+re2c generated two auxilary functions: ``read_file`` and ``action_line4``.
+``read_file`` is used to map ``.input`` and ``.keys`` files into memory (this function is shared between all lexers).
+``action_line4`` is a replacement for actions: it compares actual lexing results with the expected results.
+This function is specific to each lexer.
+Lexing is done by ``lex_line4``: this function contains the generated DFA.
+``main`` simply calls the lexer.
+
+Compile and run:
+
+.. code-block:: bash
+
+    $ gcc -o example example.c
+    $ ./example
+    $ echo $?
+    0
+
+When everything is fine, the program outputs nothing and exits with zero.
+
+
diff --git a/src/manual/features/skeleton/failures.rst b/src/manual/features/skeleton/failures.rst
new file mode 100644 (file)
index 0000000..3275b0b
--- /dev/null
@@ -0,0 +1,106 @@
+Failures
+~~~~~~~~
+
+Skeleton's main purpose was to find and prevent errors in re2c code generation (which it did).
+I don't have a ready example of failure (otherwise I would have fixed re2c),
+but we can trigger various errors by alternating the generated program, input and keys.
+
+Artificial examples
+...................
+
+Let's take the first key in ``example.c.line4.keys``  (bytes ``0x01``, ``0x01`` and ``0xFE``) and mangle it in various ways.
+For example, let's change the first byte (length of current input string) to ``0xFF``:
+
+.. code-block:: bash
+
+    $ re2c -S -o example.c hex2.re
+    $ sed -i -e 's/\x01\x01\xfe/\xff\x01\xfe/' example.c.line4.keys
+    $ ./example
+    error: lex_line4: unused input strings left at position 255
+    error: lex_line4: unused keys left after 1 iterations
+
+Lexer complains about unused keys and input strings.
+The alternated parameter controls offset of the next string:
+lexer was forced to jump past the end of input.
+Now let's alter the second byte (length of the matching prefix):
+
+.. code-block:: bash
+
+    $ re2c -S -o example.c hex2.re
+    $ sed -i -e 's/\x01\x01\xfe/\x01\x03\xfe/' example.c.line4.keys
+    $ ./example
+    error: lex_line4: at position 0 (iteration 0):
+            expected: match length 3, rule 254
+            actual:   match length 1, rule 254
+
+Third byte stands for rule number:
+
+.. code-block:: bash
+
+    $ re2c -S -o example.c hex2.re
+    $ sed -i -e 's/\x01\x01\xfe/\x01\x01\xfd/' example.c.line4.keys
+    $ ./example
+    error: lex_line4: at position 0 (iteration 0):
+            expected: match length 1, rule 253
+            actual:   match length 1, rule 254
+
+Now let's change the input string:
+
+.. code-block:: bash
+
+    $ re2c -S -o example.c hex2.re
+    $ sed -i -e 's/@/00/' example.c.line4.input
+    $ ./example
+    error: lex_line4: at position 3 (iteration 3):
+            expected: match length 1, rule 254
+            actual:   match length 2, rule 0
+
+And so on.
+Of course, some errors won't be captured by skeleton program: it's not feasible to cover all possible inputs.
+For example, of all the hex digits ``[0-9a-fA-F]`` re2c uses only ``[09afAF]``:
+we can mangle the lexer to not to recognize ``[1-8b-eB-E]`` as hex digits and the program won't notice.
+However, the chosen values are *edge* values they are tested *extensively*
+(see the section about data generation for details).
+
+
+Undefined control flow
+......................
+
+One special case of failure is caused by undefined control flow in the generated lexer.
+Suppose, for example, that we forgot to handle default case in the example above:
+
+.. code-block:: cpp
+    :number-lines:
+
+    /*!re2c
+        [0-9a-fA-F]{2} {}
+    */
+
+In this case re2c generates code that is perfectly correct,
+but because of the undefined control flow skeleton program fails:
+
+.. code-block:: bash
+
+    $ re2c -S -o example.c hex2.re
+    $ gcc -o example example.c
+    $ ./example
+    warning: lex_line3: control flow is undefined for input at position 72, rerun re2c with '-W'
+    error: lex_line3: at position 72 (iteration 36):
+            expected: match length 0, rule 255
+            actual:   match length 3, rule 0
+
+In this case we are lucky: lexer erroneously hit an action and was terminated.
+We got a nice error and a warning that suggests that we should rerun re2c with ``-W``:
+
+.. code-block:: bash
+
+    $ re2c -W -S -o example.c hex2.re
+    re2c: warning: line 3: control flow is undefined for strings that match 
+            '[\x0-\x2F\x3A-\x40\x47-\x60\x67-\xFF]'
+            '[\x30-\x39\x41-\x46\x61-\x66] [\x0-\x2F\x3A-\x40\x47-\x60\x67-\xFF]'
+    , use default rule '*' [-Wundefined-control-flow]
+
+However, it could be much worse: segfault or eternal loop.
+One thing is for sure: the generated input would have triggered undefined control flow anyway.
+
+
diff --git a/src/manual/features/skeleton/gen.sh b/src/manual/features/skeleton/gen.sh
new file mode 100755 (executable)
index 0000000..97a313a
--- /dev/null
@@ -0,0 +1,8 @@
+printf "%10s%10s%10s%10s\n\n" iters edges input keys
+for i in `seq $1 $2`
+do
+    echo '/*!re2c * {} [0-9a-fA-F]{'$i'} {} */' | re2c -S -o example.c -
+    input=`stat -c '%s' example.c.line1.input`
+    keys=`stat -c '%s' example.c.line1.keys`
+    printf "%10d%10d%10d%10d\n" $i $((14 * i)) $input $keys
+done
diff --git a/src/manual/features/skeleton/generating_data.rst b/src/manual/features/skeleton/generating_data.rst
new file mode 100644 (file)
index 0000000..1006f39
--- /dev/null
@@ -0,0 +1,115 @@
+Generating data
+~~~~~~~~~~~~~~~
+
+
+One cannot just run lexer on all possible inputs:
+for an alphabet of ``n`` characters and input length ``m``, the number of input strings is ``n`` to the power of ``m``.
+
+
+The problem can be mitigated by tailoring the set of input strings to a particular lexer.
+For most lexers only a small subset of all input strings makes sense: the majority of them are ill-formed.
+Ill-formed inputs are rejected after the first few characters, so that remaining characters are insignificant:
+lexer will never reach them and they can be as well discarded.
+Input strings that differ only in discarded suffixes are collapsed into one.
+This reduces the overall number of strings greatly.
+
+
+Still the number of inputs is too large.
+We can further reduce it by collapsing disjoint character sets:
+for each each character range we only take its boundaries.
+This cuts off many interesting well-formed inputs, but we have to give up some of them this way or another.
+The graph from the example above results into the following residual DFA:
+
+.. image:: collapsed.png
+    :width: 90%
+
+All further algorithms work with the residual graph.
+re2c has two algorithms:
+
+* First algorithm generates all possible paths from start node to end nodes
+  by performing deep-first search on graph (loops are iterated once).
+  The number of input strings grows exponentially with the number of edges,
+  thus the algorithm is only suitable for small graphs and graphs with loosely connected nodes.
+
+* Second algoritm constructs path cover: a set of paths from start node to end nodes
+  such that each edge in graph is covered by at least one path.
+  The number of generated strings is bounded by the number of edges in graph.
+  However, the total length of the generated strings depends quadratically on the number of edges.
+  (An example of quadratic dependency is shown below.
+  Upper bound follows from the fact that total length cannot exceed the number of strings
+  times maximal string length, both values obviously bounded by the number of edges.)
+
+re2c proceeds as follows: first, it estimates the amount of data needed to generate all paths
+(estimation can be done in linear time).
+If it exceeds certain limit (~32Mb edges), re2c fallbacks to path cover (which is limited by ~1Gb of edges).
+Both algorithms are implemented so that they consume constant amount of RAM
+(they dump data to file as soon as it is generated).
+
+We can look at both algorithms in action on the same example, simply alternating repetition counter:
+
+.. code-block:: cpp
+    :number-lines:
+
+    /*!re2c
+        *              {}
+        [0-9a-fA-F]{1} {} // [0-9a-fA-F]{2}, [0-9a-fA-F]{3}, [0-9a-fA-F]{4}, ...
+    */
+
+Each increment of the repetition counter adds 14 new edges to the residual DFA.
+For example, here is a picture of DFA with three repetitions
+(compare it with the above picture of two repetitions â€” edges in bold have been added):
+
+.. image:: collapsed_next.png
+    :width: 60%
+
+The following script shows how ``.input`` and ``.keys`` file size depends on the number of edges in graph:
+
+`[gen.sh] <gen.sh>`_
+
+.. include:: gen.sh
+    :code: bash
+    :number-lines:
+
+It expects two arguments: lower and upped bounds of the iteration counter.
+From the example output we can see that for counter values 1 through 7 re2c generated all paths,
+then it switched to path cover:
+
+.. code-block::
+
+    $ ./gen.sh 1 16
+         iters     edges     input      keys
+    
+             1        14        14        42
+             2        28       176       276
+             3        42      1616      1680
+             4        56     13064     10104
+             5        70     98600     60648
+             6        84    712904    363912
+             7        98   5005256   2183496
+             8       112       336       210
+             9       126       414       234
+            10       140       500       258
+            11       154       594       282
+            12       168       696       306
+            13       182       806       330
+            14       196       924       354
+            15       210      1050       378
+            16       224      1184       402
+
+The following pictures show how ``.keys`` file size depends on the number of edges.
+Total size of keys equals size of a single key times the number of generated strings.
+On the 1st plot (repetitions 1 through 7) it grows exponentially.
+On the 2nd plot (repetitions 8 through 1024) it grows linearly (the change of angle
+is due to the change of key size: starting from repetition count 256 path length gets out of 1-byte range).
+The 3rd plot shows the relation between 1st and 2nd plots.
+
+.. image:: plot_keys.png
+    :width: 100%
+
+Size of ``.input`` grows exponentially (repetitions 1 through 7) and quadratically (repetitions 8 through 1024).
+The exact quadratic function is ``f(x) = 4x^2+ 10x``, where ``x`` is the repetition counter.
+However, graphs like this rarely occur in practice: maximal path length is usually less than a hundred.
+
+.. image:: plot_input.png
+    :width: 100%
+
diff --git a/src/manual/features/skeleton/hex2.re b/src/manual/features/skeleton/hex2.re
new file mode 100644 (file)
index 0000000..c4c3b50
--- /dev/null
@@ -0,0 +1,4 @@
+/*!re2c
+    *              {}
+    [0-9a-fA-F]{2} {}
+*/
diff --git a/src/manual/features/skeleton/montage.sh b/src/manual/features/skeleton/montage.sh
new file mode 100755 (executable)
index 0000000..b809d8b
--- /dev/null
@@ -0,0 +1,5 @@
+gnuplot plot.gnuplot \
+    && montage input_1_7.png input_8_1024.png input_1_1024.png -tile 3x1 -geometry +0+0 plot_input.png \
+    && rm input_1_7.png input_8_1024.png input_1_1024.png \
+    && montage keys_1_7.png keys_8_1024.png keys_1_1024.png -tile 3x1 -geometry +0+0 plot_keys.png \
+    && rm keys_1_7.png keys_8_1024.png keys_1_1024.png
diff --git a/src/manual/features/skeleton/plot.gnuplot b/src/manual/features/skeleton/plot.gnuplot
new file mode 100644 (file)
index 0000000..aa29109
--- /dev/null
@@ -0,0 +1,34 @@
+set terminal png font "Courier,mono"
+
+
+
+set output 'input_1_7.png'
+set title "Size of .input: [0-9a-fA-F]{1..7}"
+plot "points_1_7" using 2:3 lc rgb '#ff6600' lw 2 with lines title ".input"
+
+set output 'input_8_1024.png'
+set title "Size of .input: [0-9a-fA-F]{8..1024}"
+plot "points_8_1024" using 2:3 lc rgb '#ff6600' lw 2 with lines title ".input"
+
+set output 'input_1_1024.png'
+set title "Size of .input"
+plot "points_1_7"    using 2:3 lc rgb '#ff6600' lw 2 with lines title ".input", \
+     "points_8_1024" using 2:3 lc rgb '#ff6600' lw 2 with lines notitle
+
+
+
+set output 'keys_1_7.png'
+set title "Size of .keys: [0-9a-fA-F]{1..7}"
+plot "points_1_7" using 2:4 lc rgb '#003399' lw 2 with lines title ".keys"
+
+set output 'keys_8_1024.png'
+set title "Size of .keys: [0-9a-fA-F]{8..1024}"
+plot "points_8_1024" using 2:4 lc rgb '#003399' lw 2 with lines title ".keys"
+
+set output 'keys_1_1024.png'
+set title "Size of .keys"
+plot "points_1_7"    using 2:4 lc rgb '#003399' lw 2 with lines title ".keys", \
+     "points_8_1024" using 2:4 lc rgb '#003399' lw 2 with lines notitle
+
+
+
diff --git a/src/manual/features/skeleton/plot_input.png b/src/manual/features/skeleton/plot_input.png
new file mode 100644 (file)
index 0000000..4c7befa
Binary files /dev/null and b/src/manual/features/skeleton/plot_input.png differ
diff --git a/src/manual/features/skeleton/plot_keys.png b/src/manual/features/skeleton/plot_keys.png
new file mode 100644 (file)
index 0000000..e46e3f7
Binary files /dev/null and b/src/manual/features/skeleton/plot_keys.png differ
diff --git a/src/manual/features/skeleton/points_1_7 b/src/manual/features/skeleton/points_1_7
new file mode 100644 (file)
index 0000000..e46952b
--- /dev/null
@@ -0,0 +1,9 @@
+     iters     edges     input      keys
+
+         1        14        14        42
+         2        28       176       276
+         3        42      1616      1680
+         4        56     13064     10104
+         5        70     98600     60648
+         6        84    712904    363912
+         7        98   5005256   2183496
diff --git a/src/manual/features/skeleton/points_8_1024 b/src/manual/features/skeleton/points_8_1024
new file mode 100644 (file)
index 0000000..5ed1cb6
--- /dev/null
@@ -0,0 +1,1019 @@
+     iters     edges     input      keys
+
+         8       112       336       210
+         9       126       414       234
+        10       140       500       258
+        11       154       594       282
+        12       168       696       306
+        13       182       806       330
+        14       196       924       354
+        15       210      1050       378
+        16       224      1184       402
+        17       238      1326       426
+        18       252      1476       450
+        19       266      1634       474
+        20       280      1800       498
+        21       294      1974       522
+        22       308      2156       546
+        23       322      2346       570
+        24       336      2544       594
+        25       350      2750       618
+        26       364      2964       642
+        27       378      3186       666
+        28       392      3416       690
+        29       406      3654       714
+        30       420      3900       738
+        31       434      4154       762
+        32       448      4416       786
+        33       462      4686       810
+        34       476      4964       834
+        35       490      5250       858
+        36       504      5544       882
+        37       518      5846       906
+        38       532      6156       930
+        39       546      6474       954
+        40       560      6800       978
+        41       574      7134      1002
+        42       588      7476      1026
+        43       602      7826      1050
+        44       616      8184      1074
+        45       630      8550      1098
+        46       644      8924      1122
+        47       658      9306      1146
+        48       672      9696      1170
+        49       686     10094      1194
+        50       700     10500      1218
+        51       714     10914      1242
+        52       728     11336      1266
+        53       742     11766      1290
+        54       756     12204      1314
+        55       770     12650      1338
+        56       784     13104      1362
+        57       798     13566      1386
+        58       812     14036      1410
+        59       826     14514      1434
+        60       840     15000      1458
+        61       854     15494      1482
+        62       868     15996      1506
+        63       882     16506      1530
+        64       896     17024      1554
+        65       910     17550      1578
+        66       924     18084      1602
+        67       938     18626      1626
+        68       952     19176      1650
+        69       966     19734      1674
+        70       980     20300      1698
+        71       994     20874      1722
+        72      1008     21456      1746
+        73      1022     22046      1770
+        74      1036     22644      1794
+        75      1050     23250      1818
+        76      1064     23864      1842
+        77      1078     24486      1866
+        78      1092     25116      1890
+        79      1106     25754      1914
+        80      1120     26400      1938
+        81      1134     27054      1962
+        82      1148     27716      1986
+        83      1162     28386      2010
+        84      1176     29064      2034
+        85      1190     29750      2058
+        86      1204     30444      2082
+        87      1218     31146      2106
+        88      1232     31856      2130
+        89      1246     32574      2154
+        90      1260     33300      2178
+        91      1274     34034      2202
+        92      1288     34776      2226
+        93      1302     35526      2250
+        94      1316     36284      2274
+        95      1330     37050      2298
+        96      1344     37824      2322
+        97      1358     38606      2346
+        98      1372     39396      2370
+        99      1386     40194      2394
+       100      1400     41000      2418
+       101      1414     41814      2442
+       102      1428     42636      2466
+       103      1442     43466      2490
+       104      1456     44304      2514
+       105      1470     45150      2538
+       106      1484     46004      2562
+       107      1498     46866      2586
+       108      1512     47736      2610
+       109      1526     48614      2634
+       110      1540     49500      2658
+       111      1554     50394      2682
+       112      1568     51296      2706
+       113      1582     52206      2730
+       114      1596     53124      2754
+       115      1610     54050      2778
+       116      1624     54984      2802
+       117      1638     55926      2826
+       118      1652     56876      2850
+       119      1666     57834      2874
+       120      1680     58800      2898
+       121      1694     59774      2922
+       122      1708     60756      2946
+       123      1722     61746      2970
+       124      1736     62744      2994
+       125      1750     63750      3018
+       126      1764     64764      3042
+       127      1778     65786      3066
+       128      1792     66816      3090
+       129      1806     67854      3114
+       130      1820     68900      3138
+       131      1834     69954      3162
+       132      1848     71016      3186
+       133      1862     72086      3210
+       134      1876     73164      3234
+       135      1890     74250      3258
+       136      1904     75344      3282
+       137      1918     76446      3306
+       138      1932     77556      3330
+       139      1946     78674      3354
+       140      1960     79800      3378
+       141      1974     80934      3402
+       142      1988     82076      3426
+       143      2002     83226      3450
+       144      2016     84384      3474
+       145      2030     85550      3498
+       146      2044     86724      3522
+       147      2058     87906      3546
+       148      2072     89096      3570
+       149      2086     90294      3594
+       150      2100     91500      3618
+       151      2114     92714      3642
+       152      2128     93936      3666
+       153      2142     95166      3690
+       154      2156     96404      3714
+       155      2170     97650      3738
+       156      2184     98904      3762
+       157      2198    100166      3786
+       158      2212    101436      3810
+       159      2226    102714      3834
+       160      2240    104000      3858
+       161      2254    105294      3882
+       162      2268    106596      3906
+       163      2282    107906      3930
+       164      2296    109224      3954
+       165      2310    110550      3978
+       166      2324    111884      4002
+       167      2338    113226      4026
+       168      2352    114576      4050
+       169      2366    115934      4074
+       170      2380    117300      4098
+       171      2394    118674      4122
+       172      2408    120056      4146
+       173      2422    121446      4170
+       174      2436    122844      4194
+       175      2450    124250      4218
+       176      2464    125664      4242
+       177      2478    127086      4266
+       178      2492    128516      4290
+       179      2506    129954      4314
+       180      2520    131400      4338
+       181      2534    132854      4362
+       182      2548    134316      4386
+       183      2562    135786      4410
+       184      2576    137264      4434
+       185      2590    138750      4458
+       186      2604    140244      4482
+       187      2618    141746      4506
+       188      2632    143256      4530
+       189      2646    144774      4554
+       190      2660    146300      4578
+       191      2674    147834      4602
+       192      2688    149376      4626
+       193      2702    150926      4650
+       194      2716    152484      4674
+       195      2730    154050      4698
+       196      2744    155624      4722
+       197      2758    157206      4746
+       198      2772    158796      4770
+       199      2786    160394      4794
+       200      2800    162000      4818
+       201      2814    163614      4842
+       202      2828    165236      4866
+       203      2842    166866      4890
+       204      2856    168504      4914
+       205      2870    170150      4938
+       206      2884    171804      4962
+       207      2898    173466      4986
+       208      2912    175136      5010
+       209      2926    176814      5034
+       210      2940    178500      5058
+       211      2954    180194      5082
+       212      2968    181896      5106
+       213      2982    183606      5130
+       214      2996    185324      5154
+       215      3010    187050      5178
+       216      3024    188784      5202
+       217      3038    190526      5226
+       218      3052    192276      5250
+       219      3066    194034      5274
+       220      3080    195800      5298
+       221      3094    197574      5322
+       222      3108    199356      5346
+       223      3122    201146      5370
+       224      3136    202944      5394
+       225      3150    204750      5418
+       226      3164    206564      5442
+       227      3178    208386      5466
+       228      3192    210216      5490
+       229      3206    212054      5514
+       230      3220    213900      5538
+       231      3234    215754      5562
+       232      3248    217616      5586
+       233      3262    219486      5610
+       234      3276    221364      5634
+       235      3290    223250      5658
+       236      3304    225144      5682
+       237      3318    227046      5706
+       238      3332    228956      5730
+       239      3346    230874      5754
+       240      3360    232800      5778
+       241      3374    234734      5802
+       242      3388    236676      5826
+       243      3402    238626      5850
+       244      3416    240584      5874
+       245      3430    242550      5898
+       246      3444    244524      5922
+       247      3458    246506      5946
+       248      3472    248496      5970
+       249      3486    250494      5994
+       250      3500    252500      6018
+       251      3514    254514      6042
+       252      3528    256536      6066
+       253      3542    258566      6090
+       254      3556    260604      6114
+       255      3570    262650      6138
+       256      3584    264704     12324
+       257      3598    266766     12372
+       258      3612    268836     12420
+       259      3626    270914     12468
+       260      3640    273000     12516
+       261      3654    275094     12564
+       262      3668    277196     12612
+       263      3682    279306     12660
+       264      3696    281424     12708
+       265      3710    283550     12756
+       266      3724    285684     12804
+       267      3738    287826     12852
+       268      3752    289976     12900
+       269      3766    292134     12948
+       270      3780    294300     12996
+       271      3794    296474     13044
+       272      3808    298656     13092
+       273      3822    300846     13140
+       274      3836    303044     13188
+       275      3850    305250     13236
+       276      3864    307464     13284
+       277      3878    309686     13332
+       278      3892    311916     13380
+       279      3906    314154     13428
+       280      3920    316400     13476
+       281      3934    318654     13524
+       282      3948    320916     13572
+       283      3962    323186     13620
+       284      3976    325464     13668
+       285      3990    327750     13716
+       286      4004    330044     13764
+       287      4018    332346     13812
+       288      4032    334656     13860
+       289      4046    336974     13908
+       290      4060    339300     13956
+       291      4074    341634     14004
+       292      4088    343976     14052
+       293      4102    346326     14100
+       294      4116    348684     14148
+       295      4130    351050     14196
+       296      4144    353424     14244
+       297      4158    355806     14292
+       298      4172    358196     14340
+       299      4186    360594     14388
+       300      4200    363000     14436
+       301      4214    365414     14484
+       302      4228    367836     14532
+       303      4242    370266     14580
+       304      4256    372704     14628
+       305      4270    375150     14676
+       306      4284    377604     14724
+       307      4298    380066     14772
+       308      4312    382536     14820
+       309      4326    385014     14868
+       310      4340    387500     14916
+       311      4354    389994     14964
+       312      4368    392496     15012
+       313      4382    395006     15060
+       314      4396    397524     15108
+       315      4410    400050     15156
+       316      4424    402584     15204
+       317      4438    405126     15252
+       318      4452    407676     15300
+       319      4466    410234     15348
+       320      4480    412800     15396
+       321      4494    415374     15444
+       322      4508    417956     15492
+       323      4522    420546     15540
+       324      4536    423144     15588
+       325      4550    425750     15636
+       326      4564    428364     15684
+       327      4578    430986     15732
+       328      4592    433616     15780
+       329      4606    436254     15828
+       330      4620    438900     15876
+       331      4634    441554     15924
+       332      4648    444216     15972
+       333      4662    446886     16020
+       334      4676    449564     16068
+       335      4690    452250     16116
+       336      4704    454944     16164
+       337      4718    457646     16212
+       338      4732    460356     16260
+       339      4746    463074     16308
+       340      4760    465800     16356
+       341      4774    468534     16404
+       342      4788    471276     16452
+       343      4802    474026     16500
+       344      4816    476784     16548
+       345      4830    479550     16596
+       346      4844    482324     16644
+       347      4858    485106     16692
+       348      4872    487896     16740
+       349      4886    490694     16788
+       350      4900    493500     16836
+       351      4914    496314     16884
+       352      4928    499136     16932
+       353      4942    501966     16980
+       354      4956    504804     17028
+       355      4970    507650     17076
+       356      4984    510504     17124
+       357      4998    513366     17172
+       358      5012    516236     17220
+       359      5026    519114     17268
+       360      5040    522000     17316
+       361      5054    524894     17364
+       362      5068    527796     17412
+       363      5082    530706     17460
+       364      5096    533624     17508
+       365      5110    536550     17556
+       366      5124    539484     17604
+       367      5138    542426     17652
+       368      5152    545376     17700
+       369      5166    548334     17748
+       370      5180    551300     17796
+       371      5194    554274     17844
+       372      5208    557256     17892
+       373      5222    560246     17940
+       374      5236    563244     17988
+       375      5250    566250     18036
+       376      5264    569264     18084
+       377      5278    572286     18132
+       378      5292    575316     18180
+       379      5306    578354     18228
+       380      5320    581400     18276
+       381      5334    584454     18324
+       382      5348    587516     18372
+       383      5362    590586     18420
+       384      5376    593664     18468
+       385      5390    596750     18516
+       386      5404    599844     18564
+       387      5418    602946     18612
+       388      5432    606056     18660
+       389      5446    609174     18708
+       390      5460    612300     18756
+       391      5474    615434     18804
+       392      5488    618576     18852
+       393      5502    621726     18900
+       394      5516    624884     18948
+       395      5530    628050     18996
+       396      5544    631224     19044
+       397      5558    634406     19092
+       398      5572    637596     19140
+       399      5586    640794     19188
+       400      5600    644000     19236
+       401      5614    647214     19284
+       402      5628    650436     19332
+       403      5642    653666     19380
+       404      5656    656904     19428
+       405      5670    660150     19476
+       406      5684    663404     19524
+       407      5698    666666     19572
+       408      5712    669936     19620
+       409      5726    673214     19668
+       410      5740    676500     19716
+       411      5754    679794     19764
+       412      5768    683096     19812
+       413      5782    686406     19860
+       414      5796    689724     19908
+       415      5810    693050     19956
+       416      5824    696384     20004
+       417      5838    699726     20052
+       418      5852    703076     20100
+       419      5866    706434     20148
+       420      5880    709800     20196
+       421      5894    713174     20244
+       422      5908    716556     20292
+       423      5922    719946     20340
+       424      5936    723344     20388
+       425      5950    726750     20436
+       426      5964    730164     20484
+       427      5978    733586     20532
+       428      5992    737016     20580
+       429      6006    740454     20628
+       430      6020    743900     20676
+       431      6034    747354     20724
+       432      6048    750816     20772
+       433      6062    754286     20820
+       434      6076    757764     20868
+       435      6090    761250     20916
+       436      6104    764744     20964
+       437      6118    768246     21012
+       438      6132    771756     21060
+       439      6146    775274     21108
+       440      6160    778800     21156
+       441      6174    782334     21204
+       442      6188    785876     21252
+       443      6202    789426     21300
+       444      6216    792984     21348
+       445      6230    796550     21396
+       446      6244    800124     21444
+       447      6258    803706     21492
+       448      6272    807296     21540
+       449      6286    810894     21588
+       450      6300    814500     21636
+       451      6314    818114     21684
+       452      6328    821736     21732
+       453      6342    825366     21780
+       454      6356    829004     21828
+       455      6370    832650     21876
+       456      6384    836304     21924
+       457      6398    839966     21972
+       458      6412    843636     22020
+       459      6426    847314     22068
+       460      6440    851000     22116
+       461      6454    854694     22164
+       462      6468    858396     22212
+       463      6482    862106     22260
+       464      6496    865824     22308
+       465      6510    869550     22356
+       466      6524    873284     22404
+       467      6538    877026     22452
+       468      6552    880776     22500
+       469      6566    884534     22548
+       470      6580    888300     22596
+       471      6594    892074     22644
+       472      6608    895856     22692
+       473      6622    899646     22740
+       474      6636    903444     22788
+       475      6650    907250     22836
+       476      6664    911064     22884
+       477      6678    914886     22932
+       478      6692    918716     22980
+       479      6706    922554     23028
+       480      6720    926400     23076
+       481      6734    930254     23124
+       482      6748    934116     23172
+       483      6762    937986     23220
+       484      6776    941864     23268
+       485      6790    945750     23316
+       486      6804    949644     23364
+       487      6818    953546     23412
+       488      6832    957456     23460
+       489      6846    961374     23508
+       490      6860    965300     23556
+       491      6874    969234     23604
+       492      6888    973176     23652
+       493      6902    977126     23700
+       494      6916    981084     23748
+       495      6930    985050     23796
+       496      6944    989024     23844
+       497      6958    993006     23892
+       498      6972    996996     23940
+       499      6986   1000994     23988
+       500      7000   1005000     24036
+       501      7014   1009014     24084
+       502      7028   1013036     24132
+       503      7042   1017066     24180
+       504      7056   1021104     24228
+       505      7070   1025150     24276
+       506      7084   1029204     24324
+       507      7098   1033266     24372
+       508      7112   1037336     24420
+       509      7126   1041414     24468
+       510      7140   1045500     24516
+       511      7154   1049594     24564
+       512      7168   1053696     24612
+       513      7182   1057806     24660
+       514      7196   1061924     24708
+       515      7210   1066050     24756
+       516      7224   1070184     24804
+       517      7238   1074326     24852
+       518      7252   1078476     24900
+       519      7266   1082634     24948
+       520      7280   1086800     24996
+       521      7294   1090974     25044
+       522      7308   1095156     25092
+       523      7322   1099346     25140
+       524      7336   1103544     25188
+       525      7350   1107750     25236
+       526      7364   1111964     25284
+       527      7378   1116186     25332
+       528      7392   1120416     25380
+       529      7406   1124654     25428
+       530      7420   1128900     25476
+       531      7434   1133154     25524
+       532      7448   1137416     25572
+       533      7462   1141686     25620
+       534      7476   1145964     25668
+       535      7490   1150250     25716
+       536      7504   1154544     25764
+       537      7518   1158846     25812
+       538      7532   1163156     25860
+       539      7546   1167474     25908
+       540      7560   1171800     25956
+       541      7574   1176134     26004
+       542      7588   1180476     26052
+       543      7602   1184826     26100
+       544      7616   1189184     26148
+       545      7630   1193550     26196
+       546      7644   1197924     26244
+       547      7658   1202306     26292
+       548      7672   1206696     26340
+       549      7686   1211094     26388
+       550      7700   1215500     26436
+       551      7714   1219914     26484
+       552      7728   1224336     26532
+       553      7742   1228766     26580
+       554      7756   1233204     26628
+       555      7770   1237650     26676
+       556      7784   1242104     26724
+       557      7798   1246566     26772
+       558      7812   1251036     26820
+       559      7826   1255514     26868
+       560      7840   1260000     26916
+       561      7854   1264494     26964
+       562      7868   1268996     27012
+       563      7882   1273506     27060
+       564      7896   1278024     27108
+       565      7910   1282550     27156
+       566      7924   1287084     27204
+       567      7938   1291626     27252
+       568      7952   1296176     27300
+       569      7966   1300734     27348
+       570      7980   1305300     27396
+       571      7994   1309874     27444
+       572      8008   1314456     27492
+       573      8022   1319046     27540
+       574      8036   1323644     27588
+       575      8050   1328250     27636
+       576      8064   1332864     27684
+       577      8078   1337486     27732
+       578      8092   1342116     27780
+       579      8106   1346754     27828
+       580      8120   1351400     27876
+       581      8134   1356054     27924
+       582      8148   1360716     27972
+       583      8162   1365386     28020
+       584      8176   1370064     28068
+       585      8190   1374750     28116
+       586      8204   1379444     28164
+       587      8218   1384146     28212
+       588      8232   1388856     28260
+       589      8246   1393574     28308
+       590      8260   1398300     28356
+       591      8274   1403034     28404
+       592      8288   1407776     28452
+       593      8302   1412526     28500
+       594      8316   1417284     28548
+       595      8330   1422050     28596
+       596      8344   1426824     28644
+       597      8358   1431606     28692
+       598      8372   1436396     28740
+       599      8386   1441194     28788
+       600      8400   1446000     28836
+       601      8414   1450814     28884
+       602      8428   1455636     28932
+       603      8442   1460466     28980
+       604      8456   1465304     29028
+       605      8470   1470150     29076
+       606      8484   1475004     29124
+       607      8498   1479866     29172
+       608      8512   1484736     29220
+       609      8526   1489614     29268
+       610      8540   1494500     29316
+       611      8554   1499394     29364
+       612      8568   1504296     29412
+       613      8582   1509206     29460
+       614      8596   1514124     29508
+       615      8610   1519050     29556
+       616      8624   1523984     29604
+       617      8638   1528926     29652
+       618      8652   1533876     29700
+       619      8666   1538834     29748
+       620      8680   1543800     29796
+       621      8694   1548774     29844
+       622      8708   1553756     29892
+       623      8722   1558746     29940
+       624      8736   1563744     29988
+       625      8750   1568750     30036
+       626      8764   1573764     30084
+       627      8778   1578786     30132
+       628      8792   1583816     30180
+       629      8806   1588854     30228
+       630      8820   1593900     30276
+       631      8834   1598954     30324
+       632      8848   1604016     30372
+       633      8862   1609086     30420
+       634      8876   1614164     30468
+       635      8890   1619250     30516
+       636      8904   1624344     30564
+       637      8918   1629446     30612
+       638      8932   1634556     30660
+       639      8946   1639674     30708
+       640      8960   1644800     30756
+       641      8974   1649934     30804
+       642      8988   1655076     30852
+       643      9002   1660226     30900
+       644      9016   1665384     30948
+       645      9030   1670550     30996
+       646      9044   1675724     31044
+       647      9058   1680906     31092
+       648      9072   1686096     31140
+       649      9086   1691294     31188
+       650      9100   1696500     31236
+       651      9114   1701714     31284
+       652      9128   1706936     31332
+       653      9142   1712166     31380
+       654      9156   1717404     31428
+       655      9170   1722650     31476
+       656      9184   1727904     31524
+       657      9198   1733166     31572
+       658      9212   1738436     31620
+       659      9226   1743714     31668
+       660      9240   1749000     31716
+       661      9254   1754294     31764
+       662      9268   1759596     31812
+       663      9282   1764906     31860
+       664      9296   1770224     31908
+       665      9310   1775550     31956
+       666      9324   1780884     32004
+       667      9338   1786226     32052
+       668      9352   1791576     32100
+       669      9366   1796934     32148
+       670      9380   1802300     32196
+       671      9394   1807674     32244
+       672      9408   1813056     32292
+       673      9422   1818446     32340
+       674      9436   1823844     32388
+       675      9450   1829250     32436
+       676      9464   1834664     32484
+       677      9478   1840086     32532
+       678      9492   1845516     32580
+       679      9506   1850954     32628
+       680      9520   1856400     32676
+       681      9534   1861854     32724
+       682      9548   1867316     32772
+       683      9562   1872786     32820
+       684      9576   1878264     32868
+       685      9590   1883750     32916
+       686      9604   1889244     32964
+       687      9618   1894746     33012
+       688      9632   1900256     33060
+       689      9646   1905774     33108
+       690      9660   1911300     33156
+       691      9674   1916834     33204
+       692      9688   1922376     33252
+       693      9702   1927926     33300
+       694      9716   1933484     33348
+       695      9730   1939050     33396
+       696      9744   1944624     33444
+       697      9758   1950206     33492
+       698      9772   1955796     33540
+       699      9786   1961394     33588
+       700      9800   1967000     33636
+       701      9814   1972614     33684
+       702      9828   1978236     33732
+       703      9842   1983866     33780
+       704      9856   1989504     33828
+       705      9870   1995150     33876
+       706      9884   2000804     33924
+       707      9898   2006466     33972
+       708      9912   2012136     34020
+       709      9926   2017814     34068
+       710      9940   2023500     34116
+       711      9954   2029194     34164
+       712      9968   2034896     34212
+       713      9982   2040606     34260
+       714      9996   2046324     34308
+       715     10010   2052050     34356
+       716     10024   2057784     34404
+       717     10038   2063526     34452
+       718     10052   2069276     34500
+       719     10066   2075034     34548
+       720     10080   2080800     34596
+       721     10094   2086574     34644
+       722     10108   2092356     34692
+       723     10122   2098146     34740
+       724     10136   2103944     34788
+       725     10150   2109750     34836
+       726     10164   2115564     34884
+       727     10178   2121386     34932
+       728     10192   2127216     34980
+       729     10206   2133054     35028
+       730     10220   2138900     35076
+       731     10234   2144754     35124
+       732     10248   2150616     35172
+       733     10262   2156486     35220
+       734     10276   2162364     35268
+       735     10290   2168250     35316
+       736     10304   2174144     35364
+       737     10318   2180046     35412
+       738     10332   2185956     35460
+       739     10346   2191874     35508
+       740     10360   2197800     35556
+       741     10374   2203734     35604
+       742     10388   2209676     35652
+       743     10402   2215626     35700
+       744     10416   2221584     35748
+       745     10430   2227550     35796
+       746     10444   2233524     35844
+       747     10458   2239506     35892
+       748     10472   2245496     35940
+       749     10486   2251494     35988
+       750     10500   2257500     36036
+       751     10514   2263514     36084
+       752     10528   2269536     36132
+       753     10542   2275566     36180
+       754     10556   2281604     36228
+       755     10570   2287650     36276
+       756     10584   2293704     36324
+       757     10598   2299766     36372
+       758     10612   2305836     36420
+       759     10626   2311914     36468
+       760     10640   2318000     36516
+       761     10654   2324094     36564
+       762     10668   2330196     36612
+       763     10682   2336306     36660
+       764     10696   2342424     36708
+       765     10710   2348550     36756
+       766     10724   2354684     36804
+       767     10738   2360826     36852
+       768     10752   2366976     36900
+       769     10766   2373134     36948
+       770     10780   2379300     36996
+       771     10794   2385474     37044
+       772     10808   2391656     37092
+       773     10822   2397846     37140
+       774     10836   2404044     37188
+       775     10850   2410250     37236
+       776     10864   2416464     37284
+       777     10878   2422686     37332
+       778     10892   2428916     37380
+       779     10906   2435154     37428
+       780     10920   2441400     37476
+       781     10934   2447654     37524
+       782     10948   2453916     37572
+       783     10962   2460186     37620
+       784     10976   2466464     37668
+       785     10990   2472750     37716
+       786     11004   2479044     37764
+       787     11018   2485346     37812
+       788     11032   2491656     37860
+       789     11046   2497974     37908
+       790     11060   2504300     37956
+       791     11074   2510634     38004
+       792     11088   2516976     38052
+       793     11102   2523326     38100
+       794     11116   2529684     38148
+       795     11130   2536050     38196
+       796     11144   2542424     38244
+       797     11158   2548806     38292
+       798     11172   2555196     38340
+       799     11186   2561594     38388
+       800     11200   2568000     38436
+       801     11214   2574414     38484
+       802     11228   2580836     38532
+       803     11242   2587266     38580
+       804     11256   2593704     38628
+       805     11270   2600150     38676
+       806     11284   2606604     38724
+       807     11298   2613066     38772
+       808     11312   2619536     38820
+       809     11326   2626014     38868
+       810     11340   2632500     38916
+       811     11354   2638994     38964
+       812     11368   2645496     39012
+       813     11382   2652006     39060
+       814     11396   2658524     39108
+       815     11410   2665050     39156
+       816     11424   2671584     39204
+       817     11438   2678126     39252
+       818     11452   2684676     39300
+       819     11466   2691234     39348
+       820     11480   2697800     39396
+       821     11494   2704374     39444
+       822     11508   2710956     39492
+       823     11522   2717546     39540
+       824     11536   2724144     39588
+       825     11550   2730750     39636
+       826     11564   2737364     39684
+       827     11578   2743986     39732
+       828     11592   2750616     39780
+       829     11606   2757254     39828
+       830     11620   2763900     39876
+       831     11634   2770554     39924
+       832     11648   2777216     39972
+       833     11662   2783886     40020
+       834     11676   2790564     40068
+       835     11690   2797250     40116
+       836     11704   2803944     40164
+       837     11718   2810646     40212
+       838     11732   2817356     40260
+       839     11746   2824074     40308
+       840     11760   2830800     40356
+       841     11774   2837534     40404
+       842     11788   2844276     40452
+       843     11802   2851026     40500
+       844     11816   2857784     40548
+       845     11830   2864550     40596
+       846     11844   2871324     40644
+       847     11858   2878106     40692
+       848     11872   2884896     40740
+       849     11886   2891694     40788
+       850     11900   2898500     40836
+       851     11914   2905314     40884
+       852     11928   2912136     40932
+       853     11942   2918966     40980
+       854     11956   2925804     41028
+       855     11970   2932650     41076
+       856     11984   2939504     41124
+       857     11998   2946366     41172
+       858     12012   2953236     41220
+       859     12026   2960114     41268
+       860     12040   2967000     41316
+       861     12054   2973894     41364
+       862     12068   2980796     41412
+       863     12082   2987706     41460
+       864     12096   2994624     41508
+       865     12110   3001550     41556
+       866     12124   3008484     41604
+       867     12138   3015426     41652
+       868     12152   3022376     41700
+       869     12166   3029334     41748
+       870     12180   3036300     41796
+       871     12194   3043274     41844
+       872     12208   3050256     41892
+       873     12222   3057246     41940
+       874     12236   3064244     41988
+       875     12250   3071250     42036
+       876     12264   3078264     42084
+       877     12278   3085286     42132
+       878     12292   3092316     42180
+       879     12306   3099354     42228
+       880     12320   3106400     42276
+       881     12334   3113454     42324
+       882     12348   3120516     42372
+       883     12362   3127586     42420
+       884     12376   3134664     42468
+       885     12390   3141750     42516
+       886     12404   3148844     42564
+       887     12418   3155946     42612
+       888     12432   3163056     42660
+       889     12446   3170174     42708
+       890     12460   3177300     42756
+       891     12474   3184434     42804
+       892     12488   3191576     42852
+       893     12502   3198726     42900
+       894     12516   3205884     42948
+       895     12530   3213050     42996
+       896     12544   3220224     43044
+       897     12558   3227406     43092
+       898     12572   3234596     43140
+       899     12586   3241794     43188
+       900     12600   3249000     43236
+       901     12614   3256214     43284
+       902     12628   3263436     43332
+       903     12642   3270666     43380
+       904     12656   3277904     43428
+       905     12670   3285150     43476
+       906     12684   3292404     43524
+       907     12698   3299666     43572
+       908     12712   3306936     43620
+       909     12726   3314214     43668
+       910     12740   3321500     43716
+       911     12754   3328794     43764
+       912     12768   3336096     43812
+       913     12782   3343406     43860
+       914     12796   3350724     43908
+       915     12810   3358050     43956
+       916     12824   3365384     44004
+       917     12838   3372726     44052
+       918     12852   3380076     44100
+       919     12866   3387434     44148
+       920     12880   3394800     44196
+       921     12894   3402174     44244
+       922     12908   3409556     44292
+       923     12922   3416946     44340
+       924     12936   3424344     44388
+       925     12950   3431750     44436
+       926     12964   3439164     44484
+       927     12978   3446586     44532
+       928     12992   3454016     44580
+       929     13006   3461454     44628
+       930     13020   3468900     44676
+       931     13034   3476354     44724
+       932     13048   3483816     44772
+       933     13062   3491286     44820
+       934     13076   3498764     44868
+       935     13090   3506250     44916
+       936     13104   3513744     44964
+       937     13118   3521246     45012
+       938     13132   3528756     45060
+       939     13146   3536274     45108
+       940     13160   3543800     45156
+       941     13174   3551334     45204
+       942     13188   3558876     45252
+       943     13202   3566426     45300
+       944     13216   3573984     45348
+       945     13230   3581550     45396
+       946     13244   3589124     45444
+       947     13258   3596706     45492
+       948     13272   3604296     45540
+       949     13286   3611894     45588
+       950     13300   3619500     45636
+       951     13314   3627114     45684
+       952     13328   3634736     45732
+       953     13342   3642366     45780
+       954     13356   3650004     45828
+       955     13370   3657650     45876
+       956     13384   3665304     45924
+       957     13398   3672966     45972
+       958     13412   3680636     46020
+       959     13426   3688314     46068
+       960     13440   3696000     46116
+       961     13454   3703694     46164
+       962     13468   3711396     46212
+       963     13482   3719106     46260
+       964     13496   3726824     46308
+       965     13510   3734550     46356
+       966     13524   3742284     46404
+       967     13538   3750026     46452
+       968     13552   3757776     46500
+       969     13566   3765534     46548
+       970     13580   3773300     46596
+       971     13594   3781074     46644
+       972     13608   3788856     46692
+       973     13622   3796646     46740
+       974     13636   3804444     46788
+       975     13650   3812250     46836
+       976     13664   3820064     46884
+       977     13678   3827886     46932
+       978     13692   3835716     46980
+       979     13706   3843554     47028
+       980     13720   3851400     47076
+       981     13734   3859254     47124
+       982     13748   3867116     47172
+       983     13762   3874986     47220
+       984     13776   3882864     47268
+       985     13790   3890750     47316
+       986     13804   3898644     47364
+       987     13818   3906546     47412
+       988     13832   3914456     47460
+       989     13846   3922374     47508
+       990     13860   3930300     47556
+       991     13874   3938234     47604
+       992     13888   3946176     47652
+       993     13902   3954126     47700
+       994     13916   3962084     47748
+       995     13930   3970050     47796
+       996     13944   3978024     47844
+       997     13958   3986006     47892
+       998     13972   3993996     47940
+       999     13986   4001994     47988
+      1000     14000   4010000     48036
+      1001     14014   4018014     48084
+      1002     14028   4026036     48132
+      1003     14042   4034066     48180
+      1004     14056   4042104     48228
+      1005     14070   4050150     48276
+      1006     14084   4058204     48324
+      1007     14098   4066266     48372
+      1008     14112   4074336     48420
+      1009     14126   4082414     48468
+      1010     14140   4090500     48516
+      1011     14154   4098594     48564
+      1012     14168   4106696     48612
+      1013     14182   4114806     48660
+      1014     14196   4122924     48708
+      1015     14210   4131050     48756
+      1016     14224   4139184     48804
+      1017     14238   4147326     48852
+      1018     14252   4155476     48900
+      1019     14266   4163634     48948
+      1020     14280   4171800     48996
+      1021     14294   4179974     49044
+      1022     14308   4188156     49092
+      1023     14322   4196346     49140
+      1024     14336   4204544     49188
index 103383a485875b020b6e1ecf35c3b2f941e0306a..25844d33e7df041499504fdffe0d0596afea7938 100644 (file)
@@ -2,6 +2,22 @@ Skeleton
 --------
 
 .. include:: ../home.rst
+.. include:: ../../../contents.rst
+
+
+With ``-S, --skeleton`` option re2c ignores all non-re2c code and generates a self-contained C-90 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:
+``.input`` file with strings derived from the DFA and ``.keys`` file with expected match results.
+The program runs each lexer on the corresponding ``.input`` file
+and compares results with the expectations.
+
+
+.. include:: example.rst
+.. include:: failures.rst
+.. include:: generating_data.rst
+.. include:: use.rst
 
 
 
diff --git a/src/manual/features/skeleton/use.rst b/src/manual/features/skeleton/use.rst
new file mode 100644 (file)
index 0000000..d332c20
--- /dev/null
@@ -0,0 +1,15 @@
+Use
+~~~
+
+Code verification
+.................
+
+
+Benchmarks
+..........
+
+
+Executable specs
+................
+
+