بلوک‌ها (Blocks)

نشانگرهای شروع و پایان بلوک یا /*!re2c و */، یا %{ و %} هستند (از هر دو سبک پشتیبانی می‌شود). از نسخه 2.2، بلوک‌ها می‌توانند نام‌های اختیاری داشته باشند که امکان ارجاع به آن‌ها را در سایر بلوک‌ها فراهم می‌کند. انواع مختلفی از بلوک‌ها وجود دارد:

پیکربندی‌ها (Configurations)

در اینجا فهرست کاملی از پیکربندی‌های پشتیبانی‌شده توسط re2ocaml آورده شده است:

عبارات باقاعده (Regular expressions)

re2ocaml از نحو زیر برای عبارات باقاعده استفاده می‌کند:

کلاس‌های نویسه و لیترال‌های رشته‌ای ممکن است شامل توالی‌های گریز زیر باشند: \a، \b، \f، \n، \r، \t، \v، \\، گریزهای اکتال \ooo و گریزهای هگزادسیمال \xhh، \uhhhh و \Uhhhhhhhh..SS "کنش‌ها (Actions)"

در اینجا فهرستی از کنش‌های از پیش تعریف‌شده که توسط re2ocaml پشتیبانی می‌شوند آمده است:

دستورالعمل‌ها (Directives)

در اینجا فهرست کاملی از دستورالعمل‌های پشتیبانی‌شده توسط re2ocaml آورده شده است:

رابط برنامه (Program interface)

کد تولیدشده به کمک بنیادینه‌ها (primitives)، که در مجموع با نام API شناخته می‌شوند، با برنامه بیرونی ارتباط برقرار می‌کند. اینکه چه بنیادینه‌هایی باید برای یک برنامه خاص تعریف شوند به عوامل متعددی از جمله پیچیدگی عبارت‌های منظم، شیوه نمایش ورودی، بافرینگ و استفاده از ویژگی‌های گوناگون بستگی دارد. تمام بنیادینه‌های لازم باید توسط کاربر در قالب ماکروها، توابع، متغیرها یا هر شکل مناسب دیگری که کد تولیدشده را از نظر نحوی و معنایی صحیح سازد، تعریف شوند. ابزار re2ocaml تعاریف را بررسی نمی‌کند (و نمی‌تواند بررسی کند)، بنابراین اگر چیزی جا افتاده باشد یا به نادرستی تعریف شده باشد، برنامه تولیدشده ممکن است در زمان کامپایل یا زمان اجرا دچار خطا شود. این راهنما مثال‌هایی از تعاریف API را در رایج‌ترین موارد ارائه می‌دهد.

ابزار re2ocaml دارای دو سبک API است که مجموعه اصلی بنیادینه‌های مورد استفاده یک برنامه را مشخص می‌کنند:

در اینجا فهرست کاملی از بنیادینه‌های API آورده شده است که ممکن است توسط کد تولیدشده به منظور ارتباط با برنامه بیرونی استفاده شوند.

گزینه‌ها (OPTIONS)

برخی از گزینه‌ها دارای پیکربندی‌های متناظر هستند، برخی دیگر سراسری بوده و پس از شروع خواندن فایل ورودی توسط re2ocaml قابل تغییر نیستند. گزینه‌های اشکال‌زدایی معمولاً نیازمند ساختن re2ocaml در پیکربندی اشکال‌زدایی هستند. گزینه‌های داخلی برای آزمایش الگوریتم‌های به‌کاررفته در re2ocaml مفید می‌باشند.

هشدارها (Warnings)

هشدارها را می‌توان به‌صورت جداگانه فعال یا غیرفعال کرد و یا به یک خطا تبدیل نمود.

فایل‌های نحو (Syntax files)

پشتیبانی از زبان‌های مختلف در re2c بر پایهٔ ایدهٔ فایل‌های نحو استوار است. یک فایل نحو، فایلی پیکربندی است که نحو زبان مقصد را تعریف می‌کند -- نه کل زبان، بلکه بخش کوچکی از آن که توسط کد تولیدشده استفاده می‌شود. فایل‌های نحو انعطاف‌پذیری بالایی به re2c می‌بخشند، اما نباید به عنوان جایگزینی برای پیکربندی‌های re2c: استفاده شوند: هدف آن‌ها تعریف نحو زبان مقصد است، نه سفارشی‌سازی یک تحلیل‌گر لغوی خاص. تمام زبان‌های پشتیبانی‌شده دارای فایل‌های نحو پیش‌فرضی هستند که بخشی از توزیع به شمار می‌روند (زیردایرکتوری include/syntax را ببینید)؛ آن‌ها همچنین در فایل باینری re2ocaml تعبیه شده‌اند. کاربران می‌توانند یک فایل نحو سفارشی ارائه دهند که چند پیکربندی را برای یکی از زبان‌های پشتیبانی‌شده بازنویسی می‌کند، یا می‌توانند همهٔ پیکربندی‌ها را مجدداً تعریف کنند (در این حالت باید از گزینهٔ --lang none استفاده شود). فایل‌های نحو شامل پیکربندی‌هایی در چهار نوع مختلف هستند: فهرست ویژگی‌ها، پیکربندی‌های زبان، پیکربندی‌های درون‌جایی و الگوهای کد.

فهرست‌های ویژگی (Feature lists)

پیکربندی‌های زبان (Language configurations)

پیکربندی‌های درون‌جایی (Inplace configurations)

الگوهای کد (Code templates)

code-template ::
      name '=' code-exprs ';'
    | CODE_TEMPLATE ';'
    | '<undefined>' ';'
code-exprs ::
      <EMPTY>
    | code-exprs code-expr
code-expr ::
      STRING
    | VARIABLE
    | optional
    | list
optional ::
      '(' CONDITIONAL '?' code-exprs ')'
    | '(' CONDITIONAL '?' code-exprs ':' code-exprs ')'
list ::
      '[' VARIABLE ':' code-exprs ']'
    | '[' VARIABLE '{' NUMBER '}' ':' code-exprs ']'
    | '[' VARIABLE '{' NUMBER ',' NUMBER '}' ':' code-exprs ']'

code:if_then_else =
    [branch{0}: topindent "if " cond " {" nl
        indent [stmt: stmt] dedent]
    [branch{1:-1}: topindent "} else" (.cond ? " if " cond) " {" nl
        indent [stmt: stmt] dedent]
    topindent "}" nl;

if x {
    // do something
} else if y {
    // do something else
} else {
    // don't do anything
}

نگهبان (Sentinel)

این مثال از یک نویسه نگهبان برای مدیریت پایان ورودی استفاده می‌کند. برنامه کلمات جداشده با فاصله را در یک رشته خاتمه‌یافته با null شمارش می‌کند. نگهبان null است: این آخرین نویسه هر رشته ورودی است و در میانه یک لکسم توسط هیچ‌یک از قواعد مجاز نیست (به‌ویژه، در بازه‌های نویسه‌ای که ممکن است نادیده گرفته شوند، گنجانده نشده است). اگر یک null در میانه رشته رخ دهد، این یک خطای نحوی است و تحلیل‌گر لغوی با قاعده پیش‌فرض * مطابقت پیدا می‌کند، اما فراتر از پایان ورودی نمی‌خواند یا دچار کرش نمی‌شود (از هشدار %-Wsentinel-in-midrule و پیکربندی re2c:sentinel برای اعتبارسنجی آن استفاده کنید). پیکربندی re2c:yyfill:enable = 0; از تولید بررسی‌های مرزی و فراخوانی‌های YYFILL جلوگیری می‌کند.

(* re2ocaml  -o  *)
open String
type state = {
    yyinput: string;
    mutable yycursor: int;
}
(* expect a null-terminated string *)
%{
    re2c:YYFN = ["lex;int", "yyrecord;state", "count;int"];
    re2c:yyfill:enable = 0;
    *      { -1 }
    [\x00] { count }
    [a-z]+ { lex yyrecord (count + 1) }
    [ ]+   { lex yyrecord count }
%}
let test(yyinput, count) =
    let st = {yyinput = yyinput; yycursor = 0}
    in if not (lex st 0 = count) then raise (Failure "error")
let main () =
    test("", 0);
    test("one two three", 3);
    test("f0ur", -1)
let _ = main ()

نگهبان با بررسی‌های مرزی (Sentinel with bounds checks)

این مثال از نگهبان همراه با بررسی مرزها برای مدیریت پایان ورودی استفاده می‌کند (این روش در نسخه 1.2 افزوده شد). برنامه رشته‌های درون گیومه تکی جداشده با فاصله را شمارش می‌کند. نویسه نگهبان null است که با پیکربندی re2c:eof = 0; مشخص می‌شود. همانند روش %نگهبان، null آخرین نویسه هر رشته ورودی است، اما در میانه یک قاعده مجاز است (برای مثال، 'aaa\0aa'\0 ورودی معتبر است، اما 'aaa\0 یک خطای نحوی است). بررسی‌های مرزی در هر وضعیتی که با یک نویسه ورودی مطابقت دارد تولید می‌شوند، اما به شاخه‌ای که null را پردازش می‌کند محدود هستند. بررسی‌های مرزی در API عمومی به شکل YYLIMIT <= YYCURSOR یا YYLESSTHAN(1) هستند. اگر شرط بررسی درست باشد، تحلیل‌گر به پایان ورودی رسیده است و باید متوقف شود (YYFILL با re2c:yyfill:enable = 0; غیرفعال شده است چرا که ورودی در یک بافر جا می‌شود، برای مثالی که از YYFILL استفاده می‌کند بخش %YYFILL با نگهبان را ببینید). رسیدن به پایان ورودی سه احتمال را ایجاد می‌کند: اگر تحلیل‌گر در وضعیت اولیه باشد، با قاعده پایان ورودی $ مطابقت پیدا می‌کند؛ در غیر این صورت ممکن است به یک قاعده منطبق‌شده قبلی (از جمله قاعده پیش‌فرض *) عقب‌گرد کند یا به یک وضعیت پیش‌فرض برود، که موجب هشدار %-Wundefined-control-flow می‌شود.

(* re2ocaml  -o  *)
open String
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
    yylimit: int;
}
(* expect a null-terminated string *)
%{
    re2c:YYFN = ["lex;int", "yyrecord;state", "count;int"];
    re2c:yyfill:enable = 0;
    re2c:eof = 0;
    str = ['] ([^'\\] | [\\][^])* ['];
    *    { -1 }
    $    { count }
    str  { lex yyrecord (count + 1) }
    [ ]+ { lex yyrecord count }
%}
let test(str, count) =
    let st = {
        yyinput = str;
        yycursor = 0;
        yymarker = 0;
        yylimit = length str - 1; (* terminating null not included *)
    }
    in if not (lex st 0 = count) then raise (Failure "error")
let main () =
    test("", 0);
    test("'qu\x00tes' 'are' 'fine: \\'' ", 3);
    test("'unterminated\\'", -1)
let _ = main ()

بررسی‌های مرزی با پدینگ (Bounds checks with padding)

این مثال از بررسی مرزها با پدینگ (لایه‌گذاری) برای مدیریت پایان ورودی استفاده می‌کند (این روش به طور پیش‌فرض فعال است). برنامه رشته‌های درون گیومه تکی جداشده با فاصله را شمارش می‌کند. یک پدینگ از نویسه‌های null به تعداد YYMAXFILL در انتهای ورودی الحاق می‌شود، که در آن مقدار YYMAXFILL به طور خودکار با یک بلوک max تولید می‌شود. استفاده از null برای پدینگ الزامی نیست -- هر نویسه‌ای تا زمانی که پسوند لکسم معتبری را تشکیل ندهد می‌تواند استفاده شود (در این مثال پدینگ نباید شامل گیومه تکی باشد، زیرا ممکن است با پسوند یک رشته درون گیومه تکی اشتباه گرفته شود). یک قاعده «توقف» وجود دارد که با اولین نویسه پدینگ (null) تطابق می‌یابد و تحلیل‌گر لغوی را متوقف می‌کند (توجه داشته باشید که بررسی می‌کند آیا null در آغاز پدینگ است یا خیر، در غیر این صورت یک خطای نحوی است). بررسی‌های مرزی تنها در وضعیت‌های خاصی که توسط مؤلفه‌های قویاً همبند اتوماتون مشخص می‌شوند تولید می‌گردند. بررسی‌ها در API عمومی به شکل (YYLIMIT - YYCURSOR) < n یا YYLESSTHAN(n) هستند، که در آن n حداقل تعداد نویسه‌های مورد نیاز برای پیشروی تحلیل‌گر است (همچنین به این معناست که بررسی مرز بعدی حداکثر در n نویسه آینده رخ خواهد داد). اگر شرط بررسی درست باشد، تحلیل‌گر به پایان ورودی رسیده است و YYFILL(n) را فراخوانی می‌کند که باید یا حداقل n نویسه ورودی فراهم کند یا بازنگردد. در این مثال YYFILL همیشه با شکست مواجه می‌شود و تحلیل‌گر را با خطا خاتمه می‌دهد (که اشکالی ندارد چرا که ورودی در یک بافر جا می‌شود). برای مثالی که بافر ورودی را با YYFILL مجدداً پر می‌کند بخش %YYFILL با پدینگ را ببینید.

(* re2ocaml  -o  *)
open String
exception Fill
type state = {
    yyinput: string;
    mutable yycursor: int;
    yylimit: int;
}
%{max %}
%{
    re2c:YYFN = ["lex;int", "yyrecord;state", "count;int"];
    re2c:YYFILL = "raise Fill;";
    str = ['] ([^'\\] | [\\][^])* ['];
    [\x00] {
        (* check that it is the sentinel, not some unexpected null *)
        if yyrecord.yycursor = length yyrecord.yyinput - yymaxfill + 1 then count else -1
    }
    str  { lex yyrecord (count + 1) }
    [ ]+ { lex yyrecord count }
    *    { -1 }
%}
let test(str, count) =
    let buf = cat str (make yymaxfill '\x00') in
    let st = {yyinput = buf; yycursor = 0; yylimit = length buf} in
    let result = try lex st 0 with Fill -> -1 in
    if not (result = count) then raise (Failure "error")
let main () =
    test("", 0);
    test("'unterminated\\'", -1);
    test("'qu\x00tes' 'are' 'fine: \\'' ", 3);
    test("'unexpected \x00 null", -1)
let _ = main ()

بررسی‌های سفارشی (Custom checks)

این مثال از یک روش سفارشی مدیریت پایان ورودی مبتنی بر API عمومی استفاده می‌کند. برنامه رشته‌های درون گیومه تکی جداشده با فاصله را شمارش می‌کند. این مثال همانند مثال %نگهبان است، با این تفاوت که ورودی با null خاتمه نیافته است. برای جبران عدم وجود نویسه نگهبان در انتهای ورودی، YYPEEK بازتعریف شده است تا پیش از خواندن نویسه ورودی بعدی یک بررسی مرز انجام دهد. این روش به دلیل انجام بررسی‌های مکرر ناکارآمد است. اگر شرط بررسی ناموفق باشد، YYPEEK نویسه واقعی را برمی‌گرداند؛ در غیر این صورت یک نویسه نگهبان ساختگی بازمی‌گرداند.

(* re2ocaml  -o  *)
type state = {
    str: string;
    mutable cur: int;
    lim: int;
}
(* expect a string without terminating null *)
%{
    re2c:api = generic;
    re2c:YYFN = ["lex;int", "st;state", "count;int"];
    re2c:YYPEEK = "if st.cur < st.lim then st.str.[st.cur] else '\\x00'";
    re2c:YYSKIP = "st.cur <- st.cur + 1;";
    re2c:yyfill:enable = 0;
    *      { -1 }
    [\x00] { count }
    [a-z]+ { lex st (count + 1) }
    [ ]+   { lex st count }
%}
let test(str, count) =
    let st = {str = str; cur = 0; lim = String.length str}
    in if not (lex st 0 = count) then raise (Failure "error")
let main () =
    test("", 0);
    test("one two three", 3);
    test("f0ur", -1)
let _ = main ()

YYFILL با نگهبان (YYFILL with sentinel)

اگر از قاعده EOF استفاده شود، YYFILL یک اولیه شبه‌تابع است که هیچ آرگومانی نمی‌پذیرد و مقداری را بازمی‌گرداند که با صفر مقایسه می‌شود. فراخوانی YYFILL با شرط YYLIMIT <= YYCURSOR در API اشاره‌گر C و YYLESSTHAN() در API عمومی برانگیخته می‌شود. یک مقدار بازگشتی غیرصفر به این معنی است که YYFILL ناموفق بوده است. یک فراخوانی موفق YYFILL باید حداقل یک نویسه را فراهم کرده و موقعیت‌های ورودی را بر این اساس تنظیم کند. Limit همیشه باید روی یک موقعیت بعد از آخرین موقعیت ورودی در بافر تنظیم شود، و نویسه موجود در موقعیت limit باید نماد نگهبان مشخص‌شده توسط پیکربندی re2c:eof باشد. تصاویر زیر مکان‌های نسبی موقعیت‌های ورودی را در بافر قبل و بعد از فراخوانی YYFILL نشان می‌دهند (نماد نگهبان با # مشخص شده است، و تصویر دوم حالتی را نشان می‌دهد که ورودی کافی برای پر کردن کل بافر وجود ندارد).

               <-- 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

Here is an example of a program that reads input file input.txt in chunks of 4096 bytes and uses EOF rule.

(* re2ocaml $INPUT -o $OUTPUT *)
open Bytes
let bufsize = 4096
type state = {
    file: in_channel;
    yyinput: bytes;
    mutable yycursor: int;
    mutable yymarker: int;
    mutable yylimit: int;
    mutable token: int;
    mutable eof: bool;
}
type status = Ok | Eof | LongLexeme
let fill(st: state) : status =
    if st.eof then Eof else
    (* Error: lexeme too long. In real life could reallocate a larger buffer. *)
    if st.token < 1 then LongLexeme else (
    (* Shift buffer contents (discard everything up to the current token). *)
    blit st.yyinput st.token st.yyinput 0 (st.yylimit - st.token);
    st.yycursor <- st.yycursor - st.token;
    st.yymarker <- st.yymarker - st.token;
    st.yylimit <- st.yylimit - st.token;
    st.token <- 0;
    (* Fill free space at the end of buffer with new data from file. *)
    let n = input st.file st.yyinput st.yylimit (bufsize - st.yylimit - 1) in (* -1 for sentinel *)
    st.yylimit <- st.yylimit + n;
    if n = 0 then
        st.eof <- true; (* end of file *)
        set st.yyinput st.yylimit '\x00'; (* append sentinel *)
    Ok)
%{
    re2c:YYFN = ["lex;int", "yyrecord;state", "count;int"];
    re2c:YYFILL = "fill yyrecord = Ok";
    re2c:eof = 0;
    str = ['] ([^'\\] | [\\][^])* ['];
    *    { -1 }
    $    { count }
    str  { lex_loop yyrecord (count + 1) }
    [ ]+ { lex_loop yyrecord count }
%}
and lex_loop st count =
    st.token <- st.yycursor;
    lex st count
let main () =
    let fname = "input" in
    (* Prepare input file. *)
    Out_channel.with_open_bin fname
        (fun oc -> for i = 1 to bufsize do
            output_string oc "'qu\x00tes' 'are' 'fine: \\'' "
        done);
    (* Run lexer on the prepared file. *)
    In_channel.with_open_bin fname
        (fun ic ->
            let yylimit = bufsize - 1 in
            let st = {
                file = ic;
                yyinput = create bufsize;
                yycursor = yylimit;
                yymarker = yylimit;
                yylimit = yylimit;
                token = yylimit;
                eof = false;
            } in if not (lex_loop st 0 = 3 * bufsize) then
                raise (Failure "error"));
    (* Cleanup. *)
    Sys.remove fname
let _ = main ()

YYFILL with padding

In the default case (when EOF rule is not used) YYFILL is a function-like primitive that accepts a single argument and does not return any value. YYFILL invocation is triggered by condition (YYLIMIT - YYCURSOR) < n in C pointer API and YYLESSTHAN(n) in generic API. The argument passed to YYFILL is the minimal number of characters that must be supplied. If it fails to do so, YYFILL 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 YYFILL invocation the limit position must be set either to one after the last input position in buffer, or to the end of YYMAXFILL padding (in case YYFILL has successfully read at least n characters, but not enough to fill the entire buffer). The pictures below show the relative locations of input positions in buffer before and after YYFILL invocation (YYMAXFILL padding on the second picture is marked with # symbols).

               <-- 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 ->

Here is an example of a program that reads input file input.txt in chunks of 4096 bytes and uses bounds-checking with padding.

(* re2ocaml $INPUT -o $OUTPUT *)
open Bytes
%{max %}
let bufsize = 4096
exception Fill
type state = {
    file: in_channel;
    yyinput: bytes;
    mutable yycursor: int;
    mutable yymarker: int;
    mutable yylimit: int;
    mutable token: int;
    mutable eof: bool;
}
type status = Ok | Eof | LongLexeme
let fill (st: state) (need: int) : status =
    if st.eof then Eof else
    (* Error: lexeme too long. In real life could reallocate a larger buffer. *)
    if st.token < need then LongLexeme else (
    (* Shift buffer contents (discard everything up to the current token). *)
    blit st.yyinput st.token st.yyinput 0 (st.yylimit - st.token);
    st.yycursor <- st.yycursor - st.token;
    st.yymarker <- st.yymarker - st.token;
    st.yylimit <- st.yylimit - st.token;
    st.token <- 0;
    (* Fill free space at the end of buffer with new data from file. *)
    let n = input st.file st.yyinput st.yylimit (bufsize - st.yylimit - 1) in (* -1 for sentinel *)
    st.yylimit <- st.yylimit + n;
    (* If read zero characters, this is end of input => add zero padding
       so that the lexer can access characters at the end of buffer. *)
    if n = 0 then
        st.eof <- true; (* end of file *)
        for i = 0 to (yymaxfill - 1) do
            set st.yyinput (st.yylimit + i) '\x00';
            st.yylimit <- st.yylimit + yymaxfill
        done;
    Ok)
%{
    re2c:YYFN = ["lex;int", "yyrecord;state", "count;int"];
    re2c:YYFILL = "if not (fill yyrecord @@ = Ok) then raise Fill;";
    str = ['] ([^'\\] | [\\][^])* ['];
    [\x00] {
        (* check that it is the sentinel, not some unexpected null *)
        if yyrecord.token = yyrecord.yylimit - yymaxfill then count else -1
    }
    str  { lex_loop yyrecord (count + 1) }
    [ ]+ { lex_loop yyrecord count }
    *    { -1 }
%}
and lex_loop st count =
    st.token <- st.yycursor;
    try lex st count with Fill -> -1
let main () =
    let fname = "input" in
    (* Prepare input file. *)
    Out_channel.with_open_bin fname
        (fun oc -> for i = 1 to bufsize do
            output_string oc "'qu\x00tes' 'are' 'fine: \\'' "
        done);
    (* Run lexer on the prepared file. *)
    In_channel.with_open_bin fname
        (fun ic ->
            let yylimit = bufsize - yymaxfill in
            let st = {
                file = ic;
                yyinput = create bufsize;
                yycursor = yylimit;
                yymarker = yylimit;
                yylimit = yylimit;
                token = yylimit;
                eof = false;
            } in if not (lex_loop st 0 = 3 * bufsize) then
                raise (Failure "error"));
    (* Cleanup. *)
    Sys.remove fname
let _ = main ()

در ادامه مثالی از برنامه‌ای آمده است که فایل ورودی input.txt را در تکه‌های ۴۰۹۶ بایتی می‌خواند و از قاعده EOF استفاده می‌کند.

YYFILL با پدینگ (YYFILL with padding)

در حالت پیش‌فرض (زمانی که از قاعده EOF استفاده نمی‌شود)، YYFILL یک اولیه شبه‌تابع است که یک آرگومان منفرد می‌پذیرد و هیچ مقداری بازنمی‌گرداند. فراخوانی YYFILL با شرط (YYLIMIT - YYCURSOR) < n در API اشاره‌گر C و YYLESSTHAN(n) در API عمومی برانگیخته می‌شود. آرگومان ارسالی به YYFILL حداقل تعداد نویسه‌هایی است که باید تأمین شوند. اگر در انجام این کار ناموفق باشد، YYFILL نباید به تحلیل‌گر لغوی بازگردد (به همین دلیل بهتر است با بالا انداختن یک استثنا پیاده‌سازی شود). در صورت فراخوانی موفق YYFILL، موقعیت limit باید یا روی یک موقعیت پس از آخرین موقعیت ورودی در بافر تنظیم شود، یا در انتهای پدینگ YYMAXFILL قرار گیرد (در صورتی که YYFILL حداقل n نویسه را با موفقیت خوانده باشد، اما برای پر کردن کل بافر کافی نباشد). تصاویر زیر مکان‌های نسبی موقعیت‌های ورودی در بافر را قبل و بعد از فراخوانی YYFILL نشان می‌دهند (پدینگ YYMAXFILL در تصویر دوم با نمادهای # مشخص شده است).

در ادامه مثالی از برنامه‌ای آمده است که فایل ورودی input.txt را در تکه‌های ۴۰۹۶ بایتی می‌خواند و از بررسی مرز همراه با پدینگ استفاده می‌کند.

بلوک‌های چندگانه (Multiple blocks)

گاهی لازم است چندین تحلیل‌گر لغوی مرتبط با یکدیگر داشته باشیم (برای مثال، اگر یک ماشین حالت سطح‌بالا وجود داشته باشد که بین حالت‌های تحلیل‌گر لغوی جابه‌جا شود). این ساختار را می‌توان با استفاده از چندین بلوک متصل re2ocaml پیاده‌سازی کرد. گزینه دیگر استفاده از %شرایط شروع (start conditions) است.

پیاده‌سازی اتصالات بین بلوک‌ها به زبان مقصد بستگی دارد. در زبان‌هایی که دارای دستور goto هستند (مانند C/C++ و Go) می‌توان تمام بلوک‌ها را درون یک تابع قرار داد، به‌طوری که پیش از هر یک از آن‌ها یک برچسب (label) قرار گیرد. انتقال از یک بلوک به بلوک دیگر یک goto ساده است. در زبان‌هایی که فاقد دستور goto هستند، استفاده از یک حلقه همراه با switch روی یک متغیر وضعیت ضروری است، یا اینکه می‌توان هر بلوک را در یک تابع کپسوله‌سازی کرد و از فراخوانی توابع بهره برد.

مثال زیر از چندین بلوک برای تجزیه اعداد باینری (مبنای ۲)، اکتال (مبنای ۸)، ده‌دهی (مبنای ۱۰) و هگزادسیمال (مبنای ۱۶) استفاده می‌کند. هر مبنا بلوک مخصوص به خود را دارد. بلوک اولیه، مبنا را مشخص کرده و کار را به بلوک‌های دیگر ارجاع می‌دهد. پیکربندی‌های مشترک در یک بلوک مجزا در ابتدای برنامه تعریف شده‌اند؛ این پیکربندی‌ها توسط سایر بلوک‌ها به ارث برده می‌شوند.

(* re2ocaml $INPUT -o $OUTPUT -i *)
open Int64
open Option
open String
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
} 
let add (num: int option) (dgt: int) (base: int) : int option =
    match num with
        | None -> None
        | Some n ->
            let n' = add (mul (of_int n) (of_int base)) (of_int dgt)
            in if n' > (of_int32 Int32.max_int) then None else Some (to_int n')
%{
    re2c:yyrecord = "st";
    re2c:yyfill:enable = 0;
%}
%{local
    re2c:YYFN = ["parse_bin;int option", "st;state", "num;int option"];
    [01] { parse_bin st (add num (Char.code st.yyinput.[st.yycursor - 1] - 48) 2) }
    *    { num }
%}
%{local
    re2c:YYFN = ["parse_oct;int option", "st;state", "num;int option"];
    [0-7] { parse_oct st (add num (Char.code st.yyinput.[st.yycursor - 1] - 48) 8) }
    *     { num }
%}
%{local
    re2c:YYFN = ["parse_dec;int option", "st;state", "num;int option"];
    [0-9] { parse_dec st (add num (Char.code st.yyinput.[st.yycursor - 1] - 48) 10) }
    *     { num }
%}
%{local
    re2c:YYFN = ["parse_hex;int option", "st;state", "num;int option"];
    [0-9] { parse_hex st (add num (Char.code st.yyinput.[st.yycursor - 1] - 48) 16) }
    [a-f] { parse_hex st (add num (Char.code st.yyinput.[st.yycursor - 1] - 87) 16) }
    [A-F] { parse_hex st (add num (Char.code st.yyinput.[st.yycursor - 1] - 55) 16) }
    *     { num }
%}
%{local
    re2c:YYFN = ["parse;int option", "st;state"];
    '0b' / [01]        { parse_bin st (Some 0) }
    "0"                { parse_oct st (Some 0) }
    "" / [1-9]         { parse_dec st (Some 0) }
    '0x' / [0-9a-fA-F] { parse_hex st (Some 0) }
    *                  { None }
%}
let test (yyinput: string) (result: int option) =
    let st = {yyinput = yyinput; yycursor = 0; yymarker = 0} in
    if not (parse st = result) then raise (Failure "error")
let main () =
    test "\x00" None;
    test "1234567890\x00" (Some 1234567890);
    test "0b1101\x00" (Some 13);
    test "0x7Fe\x00" (Some 2046);
    test "0644\x00" (Some 420);
    test "9999999999\x00" None
let _ = main ()

شرایط شروع (Start conditions)

شرایط شروع با گزینه --start-conditions فعال می‌شوند. آن‌ها روشی برای کدگذاری چندین اتوماتای مرتبط با یکدیگر در یک بلوک re2ocaml یکسان ارائه می‌دهند.

هر شرط متناظر با یک اتوماتای منفرد است و یک نام یکتا دارد که توسط کاربر مشخص می‌شود و یک شماره داخلی یکتا که توسط re2ocaml تعریف می‌گردد. این شماره‌ها برای جابه‌جایی میان شرایط استفاده می‌شوند: کد تولیدشده از سازوکارهای اولیه YYGETCOND و YYSETCOND برای دریافت شرط کنونی یا تنظیم آن روی شماره داده‌شده استفاده می‌کند. برای تولید شناسه‌های عددی شرایط، از بلوک conditions، گزینه --header یا پیکربندی re2c:header استفاده کنید. پیکربندی re2c:cond:enumprefix پیشوند شناسه‌های تولیدشده را مشخص می‌کند.

در حالت شرط، هر قاعده باید پیشوندی از فهرستی از نام‌های شرایط جداشده با ویرگول در علامت‌های قلاب‌دار (< >)، یا نویسه عمومی <*> برای نشان دادن همه شرایط داشته باشد. ساختار دستوری قواعد به شرح زیر گسترش می‌یابد:

کدی که re2ocaml برای شرایط تولید می‌کند بستگی به این دارد که re2ocaml از رویکرد goto/label استفاده می‌کند یا رویکرد loop/switch برای کدگذاری اتوماتا.

در زبان‌هایی که دارای دستور goto هستند (مانند C/C++ و Go)، شرایط به‌طور طبیعی به صورت بلوک‌هایی از کد با پیشوند برچسب‌هایی به شکل yyc_<cond> پیاده‌سازی می‌شوند، که در آن cond نام شرط است (پیشوند برچسب را می‌توان با re2c:cond:prefix تغییر داد). جابه‌جایی‌ها میان شرایط با استفاده از goto و برچسب‌های شرط پیاده‌سازی می‌شوند. پیش از تمام شرایط، re2ocaml یک switch اولیه روی YYGETSTATE تولید می‌کند که به وضعیت شروع شرط کنونی پرش می‌کند. قواعد میان‌بر :=> از switch اولیه عبور کرده و مستقیماً به شرط مشخص‌شده پرش می‌کنند (می‌توان از re2c:cond:goto برای تغییر رفتار پیش‌فرض استفاده کرد). قواعد دارای کنش‌های معنایی به‌طور خودکار به شرط بعدی پرش نمی‌کنند؛ این کار باید توسط کد کنش تعریف‌شده توسط کاربر انجام شود.

در زبان‌هایی که دستور goto را ندارند (مانند Rust)، ابزار re2ocaml از متغیر yystate برای ذخیره شماره‌های شرایط استفاده مجدد می‌کند. هر شرط یک شناسه عددی برابر با شماره وضعیت شروع خود دریافت می‌کند، و جابه‌جایی بین شرایط هیچ تفاوتی با switch میان وضعیت‌های DFA در یک شرط واحد ندارد. نیازی به یک switch اولیه جداگانه برای شرایط وجود ندارد. (از آنجا که رویکرد یکسانی برای پیاده‌سازی وضعیت‌های قابل ذخیره استفاده می‌شود، در صورتی که هر دو قابلیت وضعیت‌های قابل ذخیره و شرایط استفاده شوند، YYGETCOND/YYSETCOND زائد خواهند بود).

برنامه زیر از شرایط شروع برای تجزیه اعداد دودویی، هشت‌هشتی، ده‌دهی و شانزده‌شانزدهی استفاده می‌کند. یک بلوک منفرد وجود دارد که در آن هر مبنا شرط مخصوص به خود را دارد و شرط اولیه به همه آن‌ها متصل است. متغیر تعریف‌شده توسط کاربر با نام cond شماره شرط کنونی را ذخیره می‌کند؛ این متغیر با شماره شرط اولیه که توسط بلوک conditions تولید شده است، مقداردهی اولیه می‌شود.

(* re2ocaml $INPUT -o $OUTPUT -ci *)
open Int64
open Option
open String
%{conditions %}
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
    mutable yycond: yycondtype;
} 
let add (num: int option) (dgt: int) (base: int) : int option =
    match num with
        | None -> None
        | Some n ->
            let n' = add (mul (of_int n) (of_int base)) (of_int dgt)
            in if n' > (of_int32 Int32.max_int) then None else Some (to_int n')
%{
    re2c:YYFN = ["parse;int option", "st;state", "num;int option"];
    re2c:yyrecord = "st";
    re2c:yyfill:enable = 0;
    <init> '0b' / [01]        :=> bin
    <init> "0"                :=> oct
    <init> "" / [1-9]         :=> dec
    <init> '0x' / [0-9a-fA-F] :=> hex
    <init> * { None }
    <bin> [01]  { yyfnbin st (add num (Char.code st.yyinput.[st.yycursor - 1] - 48) 2) }
    <oct> [0-7] { yyfnoct st (add num (Char.code st.yyinput.[st.yycursor - 1] - 48) 8) }
    <dec> [0-9] { yyfndec st (add num (Char.code st.yyinput.[st.yycursor - 1] - 48) 10) }
    <hex> [0-9] { yyfnhex st (add num (Char.code st.yyinput.[st.yycursor - 1] - 48) 16) }
    <hex> [a-f] { yyfnhex st (add num (Char.code st.yyinput.[st.yycursor - 1] - 87) 16) }
    <hex> [A-F] { yyfnhex st (add num (Char.code st.yyinput.[st.yycursor - 1] - 55) 16) }
    <bin, oct, dec, hex> * { num }
%}
let test (yyinput: string) (result: int option) =
    let st = {yyinput = yyinput; yycursor = 0; yymarker = 0; yycond = YYC_init} in
    if not (parse st (Some 0) = result) then raise (Failure "error")
let main () =
    test "\x00" None;
    test "1234567890\x00" (Some 1234567890);
    test "0b1101\x00" (Some 13);
    test "0x7Fe\x00" (Some 2046);
    test "0644\x00" (Some 420);
    test "9999999999\x00" None
let _ = main ()

وضعیت قابل ذخیره‌سازی (Storable state)

با گزینه --storable-state، ابزار re2ocaml تحلیل‌گر لغوی‌ای تولید می‌کند که می‌تواند وضعیت فعلی خود را ذخیره کند، به فراخواننده بازگردد، و بعداً عملیات را دقیقاً از همان‌جایی که متوقف شده بود از سر بگیرد. حالت پیش‌فرض عملکرد در re2ocaml یک مدل «کششی» ("pull") است که در آن تحلیل‌گر لغوی هر زمان که نیاز داشته باشد، ورودی بیشتری را «می‌کشد» (دریافت می‌کند). این امر ممکن است در مواردی که ورودی به‌صورت تکه‌تکه در دسترس قرار می‌گیرد غیرقابل قبول باشد (برای مثال، اگر تحلیل‌گر لغوی توسط تجزیه‌کننده (parser) فراخوانی شود، یا اگر برنامه تحلیل‌گر لغوی از طریق پروتکل سوکت با برنامه دیگری ارتباط برقرار کند که باید پیش از ارسال پیام بعدی، منتظر پاسخ از سوی تحلیل‌گر لغوی بماند). ویژگی وضعیت ذخیره‌پذیر دقیقاً برای چنین مواردی در نظر گرفته شده است: این ویژگی امکان تولید تحلیل‌گرهای لغوی را فراهم می‌کند که در یک مدل «رانشی» ("push") کار می‌کنند. هنگامی که تحلیل‌گر لغوی به ورودی بیشتری نیاز دارد، وضعیت خود را ذخیره کرده و به فراخواننده بازمی‌گردد. بعداً، زمانی که ورودی بیشتری در دسترس قرار گرفت، فراخواننده تحلیل‌گر لغوی را دقیقاً از جایی که متوقف شده بود از سر می‌گیرد. در مقایسه با مدل «کششی»، چند تغییر ضروری است:

در اینجا مثالی از یک تحلیل‌گر لغوی مدل «رانشی» آورده شده است که خواندن بسته‌ها از یک سوکت را شبیه‌سازی می‌کند. تحلیل‌گر لغوی تا زمانی که با پایان ورودی مواجه شود حلقه می‌زند و به تابع فراخواننده بازمی‌گردد. تابع فراخواننده با «ارسال» بسته بعدی، ورودی بیشتری فراهم کرده و تحلیل لغوی را از سر می‌گیرد. این فرایند زمانی که تمام بسته‌ها ارسال شوند، یا خطایی رخ دهد، متوقف می‌شود.

(* re2ocaml $INPUT -o $OUTPUT -fi *)
open Bytes
(* Use a small buffer to cover the case when a lexeme doesn't fit.
   In real world use a larger buffer. *)
let bufsize = 10
let debug = false
let log format = (if debug then Printf.eprintf else Printf.ifprintf stderr) format
type state = {
    file: in_channel;
    yyinput: bytes;
    mutable yycursor: int;
    mutable yymarker: int;
    mutable yylimit: int;
    mutable token: int;
    mutable yystate: int;
    mutable recv: int;
}
type status = End | Ready | Waiting | BadPacket | BigPacket
let fill(st: state) : status =
    (* Error: lexeme too long. In real life could reallocate a larger buffer. *)
    if st.token < 1 then BigPacket else (
    (* Shift buffer contents (discard everything up to the current token). *)
    blit st.yyinput st.token st.yyinput 0 (st.yylimit - st.token);
    st.yycursor <- st.yycursor - st.token;
    st.yymarker <- st.yymarker - st.token;
    st.yylimit <- st.yylimit - st.token;
    st.token <- 0;
    (* Fill free space at the end of buffer with new data from file. *)
    let n = In_channel.input st.file st.yyinput st.yylimit (bufsize - st.yylimit - 1) in
    st.yylimit <- st.yylimit + n;
    set st.yyinput st.yylimit '\x00'; (* append sentinel *)
    Ready)
%{
    re2c:YYFN = ["lex;status", "yyrecord;state"];
    re2c:YYFILL = "Waiting";
    re2c:eof = 0;
    packet = [a-z]+[;];
    *      { BadPacket }
    $      { End }
    packet { yyrecord.recv <- yyrecord.recv + 1; lex_loop yyrecord }
%}
and lex_loop st =
    st.token <- st.yycursor;
    lex st
let test (packets: string list) (sts: status) =
    let fname = "pipe" in
    let oc = Out_channel.open_bin fname in
    let ic = In_channel.open_bin fname in
    let yylimit = bufsize - 1 in
    let st = {
        file = ic;
        (* Sentinel (at `yylimit` offset) is set to null, which triggers YYFILL. *)
        yyinput = create bufsize;
        yycursor = yylimit;
        yymarker = yylimit;
        yylimit = yylimit;
        token = yylimit;
        yystate = -1;
        recv = 0;
    } in
    let rec loop packets = match lex_loop st with
        | End ->
            log "done: got %d packets\n" st.recv;
            End
        | Waiting ->
            log "waiting...\n";
            let packets' = match packets with
                | [] -> []
                | p :: ps ->
                    log "sent packet '%s'\n" p;
                    Out_channel.output_string oc p;
                    Out_channel.flush oc; (* without `flush` write happens too late *)
                    ps
            in (match fill st with
                | BigPacket ->
                    log "error: packet too big\n";
                    BigPacket
                | Ready -> loop packets'
                | _ -> raise (Failure "unexpected status after fill"))
        | BadPacket ->
            log "error: ill-formed packet\n";
            BadPacket
        | _ -> raise (Failure "unexpected status")
    in if not (loop packets = sts) then
        raise (Failure "error");
    In_channel.close ic;
    Out_channel.close oc;
    Sys.remove fname
let main () =
    test [] End;
    test ["zero;"; "one;"; "two;"; "three;"; "four;"] End;
    test ["zer0;"] BadPacket;
    test ["goooooooooogle;"] BigPacket
let _ = main ()

بلوک‌های قابل استفاده مجدد (Reusable blocks)

بلوک‌های قابل استفاده مجدد با ساختار /*!rules:re2c[:<name>] ... */ یا %{rules[:<name>] ... %} می‌توانند به هر تعداد بار مجدداً استفاده شوند و با سایر بلوک‌های re2ocaml ترکیب گردند. بخش <name> اختیاری است. یک بلوک قوانین (rules block) می‌تواند در یک بلوک یا دستور use به کار گرفته شود. کد مربوط به یک بلوک قوانین، در هر نقطه استفاده تولید می‌شود.

بلوک‌های use با /*!use:re2c[:<name>] ... */ یا %{use[:<name>] ... %} تعریف می‌شوند. شناسه <name> اختیاری است: اگر مشخص نشده باشد، بلوک قوانین مرتبط، نزدیک‌ترین بلوک قبلی خواهد بود (خواه نام‌گذاری‌شده یا بدون نام). یک بلوک use می‌تواند تعاریف نام‌گذاری‌شده، پیکربندی‌ها و قوانین اختصاصی خود را اضافه کند. یک کاربرد مهم برای بلوک‌های use، تحلیل‌گر لغوی (lexer) با پشتیبانی از چندین کدگذاری ورودی است: همان بلوک قوانین چندین بار با پیکربندی‌های مختص هر کدگذاری مجدداً استفاده می‌شود (مثال زیر را ببینید).

دستور درون‌بلوکی !use:<name>; می‌تواند از داخل یک بلوک re2ocaml استفاده شود. این دستور، بلوک ارجاع‌داده‌شده <name> را با بلوک فعلی ادغام می‌کند. اگر برخی از قوانین و پیکربندی‌های ادغام‌شده با موارد تعریف‌شده قبلی هم‌پوشانی داشته باشند، تداخل‌ها به روش معمول حل می‌شوند: نخستین قاعده اولویت دارد، و آخرین پیکربندی بر موارد پیشین ارجحیت می‌یابد (آن‌ها را رونویسی می‌کند). یک استثنا قوانین ویژه *، $ و (در حالت شرطی) <!> هستند که برای آن‌ها تعریف محلی بلوک بر هرگونه تعریف به ارث‌رسیده برتری دارد. دستور use امکان ترکیب بلوک‌های مختلف re2ocaml را با یکدیگر در یک بلوک واحد فراهم می‌سازد (مثال زیر را ببینید).

بلوک‌های نام‌گذاری‌شده و دستور درون‌بلوکی use در نگارش 2.2 از re2ocaml اضافه شدند. از آن نگارش به بعد، استفاده از بلوک‌های قابل استفاده مجدد به‌طور پیش‌فرض مجاز است (نیازی به گزینه خاصی نیست). پیش از نگارش 2.2، حالت استفاده مجدد با گزینه -r --reusable فعال می‌شد. پیش از نگارش 1.2، بلوک‌های قابل استفاده مجدد نمی‌توانستند با بلوک‌های معمولی ترکیب شوند.

مثالی از دستورالعمل !use

(* re2ocaml $INPUT -o $OUTPUT *)
(* This example shows how to combine reusable re2c blocks: two blocks
   ('colors' and 'fish') are merged into one. The 'salmon' rule occurs
   in both blocks; the 'fish' block takes priority because it is used
   earlier. Default rule * occurs in all three blocks; the local (not
   inherited) definition takes priority. *)
open String
type answer = Color | Fish | Dunno
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
}
%{rules:colors
    *                            { raise (Failure "ah"); }
    "red" | "salmon" | "magenta" { Color }
%}
%{rules:fish
    *                            { raise (Failure "oh"); }
    "haddock" | "salmon" | "eel" { Fish }
%}
%{
    re2c:YYFN = ["lex;answer", "yyrecord;state"];
    re2c:yyfill:enable = 0;
    !use:fish;
    !use:colors;
    * { Dunno } // overrides inherited '*' rules
%}
let test(str, ans) =
    let st = {yyinput = str; yycursor = 0; yymarker = 0}
    in if not (lex st = ans) then raise (Failure "error")
let main () =
    test("salmon", Fish);
    test("what?", Dunno)
let _ = main ()

مثالی از یک بلوک /*!use:re2c ... */

(* re2ocaml $INPUT -o $OUTPUT --input-encoding utf8 *)
(* 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. *)
open Array
type 'a state = {
    yyinput: 'a array;
    mutable yycursor: int;
    mutable yymarker: int;
}
%{rules
    re2c:yyfill:enable = 0;
    "∀x ∃y" { Some yyrecord.yycursor }
    *       { None }
%}
%{use
    re2c:YYFN = ["lex8;int option", "yyrecord;char state"];
    re2c:encoding:utf8 = 1;
%}
%{use
    re2c:YYFN = ["lex32;int option", "yyrecord;int state"];
    re2c:encoding:utf32 = 1;
%}
let main() =
    let st8 = {
        yyinput = [|'\xe2'; '\x08'; '\x80'; '\x78'; '\x20'; '\xe2'; '\x88'; '\x83'; '\x79'|];
        yycursor = 0;
        yymarker = 0;
    } in if not (lex8 st8 = Some (Array.length st8.yyinput)) then raise (Failure "error");
    let st32 = {
        yycursor = 0;
        yymarker = 0;
        yyinput = [|0x2200; 0x78; 0x20; 0x2203; 0x79|];
    } in if not (lex32 st32 = Some (Array.length st32.yyinput)) then raise (Failure "error");

استخراج زیرتطابق (Submatch extraction)

ابزار re2ocaml دو گزینه برای استخراج زیرتطابق دارد.

در پشت صحنه، تمام این گزینه‌ها به برچسب‌ها و Tagged Deterministic Finite Automata with Lookahead ترجمه می‌شوند. ایدهٔ اصلی TDFA به حداقل رساندن بار اضافی (overhead) در استخراج زیرتطابق است. در حالت فرین (حد نهایی)، اگر هیچ برچسب یا گروه ضبطی در عبارت منظم نباشد، TDFA صرفاً یک DFA معمولی است. اگر تعداد برچسب‌ها در حد معتدل باشد، بار اضافی به سختی محسوس خواهد بود. اتوماتای TDFA تولیدشده از تعدادی tag variables (متغیرهای برچسب) استفاده می‌کند که مستقیماً به برچسب‌ها نگاشت نمی‌شوند: یک متغیر واحد ممکن است برای برچسب‌های متفاوتی استفاده شود، و یک برچسب ممکن است برای نگه‌داشتن تمام مقادیر ممکن خود به چندین متغیر نیاز داشته باشد. در نهایت، ابهام برطرف می‌شود و برای هر برچسب تنها یک متغیر نهایی باقی می‌ماند. متغیرهای برچسب باید با استفاده از بلوک‌های stags یا mtags تعریف شوند. اگر وضعیت تحلیل‌گر لغوی ذخیره شود، متغیرهای برچسب نیز باید بخشی از آن باشند. آن‌ها همچنین باید توسط YYFILL به‌روزرسانی شوند.

برچسب‌های S-tags از عملیات زیر پشتیبانی می‌کنند:

برچسب‌های M-tags از عملیات زیر پشتیبانی می‌کنند:

برچسب‌های S-tag را می‌توان به صورت مقادیر اسکالر (اشاره‌گرها یا آفست‌ها) پیاده‌سازی کرد. برچسب‌های M-tag به نمایش پیچیده‌تری نیاز دارند، زیرا باید دنباله‌ای از مقادیر برچسب را ذخیره کنند. ابتدایی‌ترین و ناکارآمدترین نمایش برای یک m-tag، یک لیست (آرایه، بردار) از مقادیر برچسب است؛ نمایشی کارآمدتر، ذخیرهٔ تمام m-tagها در یک درخت پیشوندی (prefix-tree) است که به صورت آرایه‌ای از گره‌های (v, p) نشان داده می‌شود، که در آن v مقدار برچسب و p اشاره‌گری به گره والد است.

در اینجا یک مثال ساده از به‌کارگیری s-tagها برای تجزیهٔ نگارش‌های معنایی (semantic versions) متشکل از سه جزء عددی آورده شده است: major، minor، patch (مورد آخر اختیاری است). برای یک مثال پیچیده‌تر که از YYFILL استفاده می‌کند، بخش زیر را ببینید.

(* re2ocaml $INPUT -o $OUTPUT *)
open String
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
    (* Final tag variables available in semantic action. *)
    %{svars format = "\n\tmutable @@{tag}: int;"; %}
    (* Intermediate tag variables used by the lexer (must be autogenerated). *)
    %{stags format = "\n\tmutable @@{tag}: int;"; %}
}
type semver = {
    major: int;
    minor: int;
    patch: int;
}
let s2n (str: string) (i1: int) (i2: int) : int =
    let rec f s i j n =
        if i >= j then n else f s (i + 1) j (n * 10 + Char.code s.[i] - 48)
    in f str i1 i2 0
%{local
    re2c:YYFN = ["parse;semver option", "st;state"];
    re2c:yyrecord = "st";
    re2c:tags = 1;
    re2c:yyfill:enable = 0;
    num = [0-9]+;
    @t1 num @t2 "." @t3 num @t4 ("." @t5 num)? [\x00] {
        Some {
            major = s2n st.yyinput st.t1 st.t2;
            minor = s2n st.yyinput st.t3 st.t4;
            patch = if st.t5 = -1 then 0 else s2n st.yyinput st.t5 (st.yycursor - 1)
        }
    }
    * { None }
%}
let test (str: string) (result: semver option) =
    let st = {
        yyinput = str;
        yycursor = 0;
        yymarker = 0;
        %{svars format = "\n\t\t@@{tag} = -1;"; %}
        %{stags format = "\n\t\t@@{tag} = -1;"; %}
    }
    in if not (parse st = result) then raise (Failure "error")
let main () =
    test "23.34" (Some {major = 23; minor = 34; patch = 0});
    test "1.2.99999" (Some {major = 1; minor = 2; patch = 99999});
    test "1.a" None
let _ = main ()

در اینجا مثالی پیچیده‌تر از استفاده از s-tagها با YYFILL برای تجزیهٔ فایلی با نگارش‌های معنایی جداشده با خط جدید آمده است. متغیرهای برچسب بخشی از وضعیت تحلیل‌گر لغوی هستند، و همانند سایر موقعیت‌های ورودی در YYFILL تنظیم می‌شوند. توجه داشته باشید که این امر برای s-tagها ضروری است زیرا مقادیر آن‌ها پس از جابه‌جایی محتویات بافر باطل می‌شوند. این کار ممکن است در پیاده‌سازی‌های سفارشی که در آن‌ها متغیرهای برچسب آفست‌ها را به‌جای بافر، نسبت به ابتدای رشتهٔ ورودی ذخیره می‌کنند (که ممکن است در مورد m-tagها چنین باشد)، ضروری نباشد.

(* re2ocaml $INPUT -o $OUTPUT *)
open Bytes
let bufsize = 4096
type state = {
    file: in_channel;
    yyinput: bytes;
    mutable yycursor: int;
    mutable yymarker: int;
    mutable yylimit: int;
    mutable token: int;
    mutable eof: bool;
    (* Final tag variables available in semantic action. *)
    %{svars format = "\n\tmutable @@{tag}: int;"; %}
    (* Intermediate tag variables used by the lexer (must be autogenerated). *)
    %{stags format = "\n\tmutable @@{tag}: int;"; %}
}
type status = Ok | Eof | LongLexeme
type semver = {
    major: int;
    minor: int;
    patch: int;
}
let s2n (str: bytes) (i1: int) (i2: int) : int =
    let rec f s i j n =
        if i >= j then n else f s (i + 1) j (n * 10 + Char.code (get s i) - 48)
    in f str i1 i2 0
let fill(st: state) : status =
    if st.eof then Eof else
    (* Error: lexeme too long. In real life could reallocate a larger buffer. *)
    if st.token < 1 then LongLexeme else (
    (* Shift buffer contents (discard everything up to the current token). *)
    blit st.yyinput st.token st.yyinput 0 (st.yylimit - st.token);
    st.yycursor <- st.yycursor - st.token;
    st.yymarker <- st.yymarker - st.token;
    st.yylimit <- st.yylimit - st.token;
    %{stags format = "\n\tst.@@ <- if st.@@ = -1 then -1 else st.@@ - st.token;"; %}
    st.token <- 0;
    (* Fill free space at the end of buffer with new data from file. *)
    let n = input st.file st.yyinput st.yylimit (bufsize - st.yylimit - 1) in (* -1 for sentinel *)
    st.yylimit <- st.yylimit + n;
    if n = 0 then
        st.eof <- true; (* end of file *)
        set st.yyinput st.yylimit '\x00'; (* append sentinel *)
    Ok)
%{
    re2c:YYFN = ["lex;(semver list) option", "st;state", "vers;semver list"];
    re2c:YYFILL = "fill st = Ok";
    re2c:yyrecord = "st";
    re2c:tags = 1;
    re2c:eof = 0;
    num = [0-9]+;
    @t1 num @t2 "." @t3 num @t4 ("." @t5 num)? [\n] {
        let ver = {
            major = s2n st.yyinput st.t1 st.t2;
            minor = s2n st.yyinput st.t3 st.t4;
            patch = if st.t5 = -1 then 0 else s2n st.yyinput st.t5 (st.yycursor - 1)
        } in lex_loop st (ver :: vers)
    }
    $ { Some (List.rev vers) }
    * { None }
%}
and lex_loop st vers =
    st.token <- st.yycursor;
    lex st vers
let main () =
    let fname = "input" in
    (* Prepare input file. *)
    Out_channel.with_open_bin fname
        (fun oc -> for i = 1 to bufsize do
            output_string oc "1.22.333\n"
        done);
    (* Construct the expected result to compare against. *)
    let expect = Some (List.init bufsize
            (fun _ -> {major = 1; minor = 22; patch = 333;})) in
    (* Run lexer on the prepared file. *)
    In_channel.with_open_bin fname
        (fun ic ->
            let yylimit = bufsize - 1 in
            let st = {
                file = ic;
                yyinput = create bufsize;
                yycursor = yylimit;
                yymarker = yylimit;
                yylimit = yylimit;
                token = yylimit;
                eof = false;
                %{svars format = "\n\t\t@@{tag} = -1;"; %}
                %{stags format = "\n\t\t@@{tag} = -1;"; %}
            } in if (lex_loop st [] <> expect) then
                raise (Failure "error"));
    (* Cleanup. *)
    Sys.remove fname
let _ = main ()

در اینجا مثالی از به‌کارگیری گروه‌های تسخیر (capturing groups) برای تجزیهٔ نگارش‌های معنایی (semantic versions) آورده شده است.

(* re2ocaml $INPUT -o $OUTPUT *)
open String
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
    (* Final tag variables available in semantic action. *)
    %{svars format = "\n\tmutable @@{tag}: int;"; %}
    (* Intermediate tag variables used by the lexer (must be autogenerated). *)
    %{stags format = "\n\tmutable @@{tag}: int;"; %}
}
type semver = {
    major: int;
    minor: int;
    patch: int;
}
let s2n (str: string) (i1: int) (i2: int) : int =
    let rec f s i j n =
        if i >= j then n else f s (i + 1) j (n * 10 + Char.code s.[i] - 48)
    in f str i1 i2 0
%{local
    re2c:YYFN = ["parse;semver option", "st;state"];
    re2c:yyrecord = "st";
    re2c:captvars = 1;
    re2c:yyfill:enable = 0;
    num = [0-9]+;
    (num) "." (num) ("." num)? [\x00] {
        Some {
            major = s2n st.yyinput st.yytl1 st.yytr1;
            minor = s2n st.yyinput st.yytl2 st.yytr2;
            patch = if st.yytl3 = -1 then 0 else s2n st.yyinput (st.yytl3 + 1) st.yytr3
        }
    }
    * { None }
%}
let test (str: string) (result: semver option) =
    let st = {
        yyinput = str;
        yycursor = 0;
        yymarker = 0;
        %{svars format = "\n\t\t@@{tag} = -1;"; %}
        %{stags format = "\n\t\t@@{tag} = -1;"; %}
    }
    in if not (parse st = result) then raise (Failure "error")
let main () =
    test "23.34" (Some {major = 23; minor = 34; patch = 0});
    test "1.2.99999" (Some {major = 1; minor = 2; patch = 99999});
    test "1.a" None
let _ = main ()

در اینجا مثالی از به‌کارگیری m-tags برای تجزیهٔ نگارشی با تعداد متغیر مؤلفه‌ها آورده شده است. متغیرهای برچسب در یک trie ذخیره می‌شوند.

(* re2ocaml $INPUT -o $OUTPUT *)
open String
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
    (* Final tag variables available in semantic action. *)
    %{svars format = "\n\tmutable @@{tag}: int;"; %}
    %{mvars format = "\n\tmutable @@{tag}: int list;"; %}
    (* Intermediate tag variables used by the lexer (must be autogenerated). *)
    %{stags format = "\n\tmutable @@{tag}: int;"; %}
    %{mtags format = "\n\tmutable @@{tag}: int list;"; %}
}
let s2n (str: string) (i1: int) (i2: int) : int =
    let rec f s i j n =
        if i >= j then n else f s (i + 1) j (n * 10 + Char.code s.[i] - 48)
    in f str i1 i2 0
%{local
    re2c:YYFN = ["parse;(int list) option", "st;state"];
    re2c:YYMTAGP = "@@ <- st.yycursor :: @@;";
    re2c:YYMTAGN = ""; // alternatively could add `-1` to the list
    re2c:yyrecord = "st";
    re2c:tags = 1;
    re2c:yyfill:enable = 0;
    num = [0-9]+;
    @t1 num @t2 ("." #t3 num #t4)* [\x00] {
        let x = s2n st.yyinput st.t1 st.t2 in
        let xs = List.rev (List.map2 (fun x y -> s2n st.yyinput x y) st.t3 st.t4) in
        Some (x :: xs)
    }
    * { None }
%}
let test (str: string) (result: (int list) option) =
    let st = {
        yyinput = str;
        yycursor = 0;
        yymarker = 0;
        %{svars format = "\n\t\t@@{tag} = -1;"; %}
        %{mvars format = "\n\t\t@@{tag} = [];"; %}
        %{stags format = "\n\t\t@@{tag} = -1;"; %}
        %{mtags format = "\n\t\t@@{tag} = [];"; %}
    }
    in if not (parse st = result) then raise (Failure "error")
let main () =
    test "1" (Some [1]);
    test "1.2.3.4.5.6.7" (Some [1; 2; 3; 4; 5; 6; 7;]);
    test "1.2." None
let _ = main ()

پشتیبانی از کدگذاری (Encoding support)

درک تفاوت بین نقطه‌های کد (code points) و واحدهای کد (code units) ضروری است. یک نقطه کد، شناسه عددی یک نماد است. یک واحد کد، کوچک‌ترین واحد ذخیره‌سازی در متن کدگذاری‌شده است. یک نقطه کد تکی ممکن است با یک یا چند واحد کد نمایش داده شود. در یک کدگذاری با طول ثابت، تمام نقطه‌های کد با تعداد یکسانی از واحدهای کد نشان داده می‌شوند. در یک کدگذاری با طول متغیر، نقطه‌های کد ممکن است با تعداد متفاوتی از واحدهای کد نمایش داده شوند. توجه داشته باشید که قاعده "any" یعنی [^] با هر نقطه کدی تطابق دارد، اما لزوماً با هر واحد کدی تطابق ندارد (تنها راه تطبیق با هر واحد کد صرف‌نظر از نوع کدگذاری، قاعده پیش‌فرض * است). تحلیل‌گر لغوی تولیدشده با جریانی از واحدهای کد کار می‌کند: yych یک واحد کد را ذخیره می‌کند و YYCTYPE نوع واحد کد است. از سوی دیگر، عبارت‌های منظم برحسب نقطه‌های کد مشخص می‌شوند. هنگامی که re2ocaml عبارت‌های منظم را به اتوماتا کامپایل می‌کند، نقطه‌های کد را به واحدهای کد ترجمه می‌نماید. این کار معمولاً یک نگاشت ساده نیست: در کدگذاری‌های با طول متغیر، ممکن است یک بازه از یک نقطه کد منفرد به یک گراف پیچیده از واحدهای کد ترجمه شود. کدگذاری‌های زیر پشتیبانی می‌شوند:

فایل‌های ضمیمه include/unicode_blocks.re، include/unicode_categories.re و include/unicode_properties.re تعاریف re2ocaml را برای بلوک‌ها، دسته‌ها و ویژگی‌های شرح‌داده‌شده در استاندارد Unicode ارائه می‌دهند.

گزینه --input-encoding کدگذاری فایل منبع را مشخص می‌کند، که می‌تواند برای فعال‌سازی لیترال‌های Unicode در عبارت‌های منظم استفاده شود. برای مثال، --input-encoding utf8 به re2ocaml اعلام می‌کند که فایل منبع به فرمت UTF8 است (این با --utf8 که کدگذاری متن ورودی را تنظیم می‌کند متفاوت است). گزینه --encoding-policy نحوه مدیریت جانشین‌های یونیکد (Unicode surrogates؛ نقطه‌های کد در محدوده [0xD800-0xDFFF]) را توسط re2ocaml تعیین می‌کند.

در زیر نمونه‌ای از یک تحلیل‌گر لغوی برای شناسه‌های Unicode با کدگذاری UTF8 آورده شده است.

(* re2ocaml $INPUT -o $OUTPUT --utf8 -i *)
open String
%{include "unicode_categories.re" %}
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
    mutable yyaccept: int;
}
%{
    re2c:YYFN = ["lex;bool", "yyrecord;state"];
    re2c:yyfill:enable = 0;
    // Simplified "Unicode Identifier and Pattern Syntax"
    // (see https://unicode.org/reports/tr31)
    id_start    = L | Nl | [$_];
    id_continue = id_start | Mn | Mc | Nd | Pc | [\u200D\u05F3];
    identifier  = id_start id_continue*;
    identifier { true }
    *          { false }
%}
let main () =
    let st = {
        yyinput = "_Ыдентификатор";
        yycursor = 0;
        yymarker = 0;
        yyaccept = 0;
    }
    in if not (lex st) then raise (Failure "error")
let _ = main ()

فایل‌های ضمیمه (Include files)

ابزار re2ocaml به شما اجازه می‌دهد فایل‌های دیگر را با استفاده از بلوکی به شکل /*!include:re2c FILE */ یا %{include FILE %}، یا دستور درون‌بلوکی !include FILE ; ضمیمه کنید، که در آن FILE مسیر فایلی است که باید ضمیمه شود. re2ocaml فایل‌های ضمیمه را در دایرکتوریِ فایلِ دربرگیرنده و در مکان‌های include (که می‌توان با گزینه -I مشخص کرد) جستجو می‌کند. بلوک‌ها/دستورهای ضمیمه‌سازی در re2ocaml به همان شیوه #include در C/C++ عمل می‌کنند: محتویات FILE عیناً به جای بلوک/دستور کپی و جای‌گذاری می‌شوند. فایل‌های ضمیمه می‌توانند خود دارای includeهای بیشتری باشند. از گزینه --depfile برای ردیابی وابستگی‌های ساخت فایل خروجی نسبت به فایل‌های ضمیمه استفاده کنید. ابزار re2ocaml تعدادی فایل ضمیمه از پیش تعریف‌شده ارائه می‌دهد که در زیردایرکتوری include/ از پروژه قرار دارند. این فایل‌ها شامل تعاریفی هستند که ممکن است برای پروژه‌های دیگر نیز مفید باشند (مانند دسته‌بندی‌های Unicode) و چیزی شبیه به یک کتابخانه استاندارد را برای re2ocaml تشکیل می‌دهند. در ادامه مثالی از به‌کارگیری فایل‌های ضمیمه آورده شده است.

فایل ضمیمه ۱ (definitions.ml)

type number = Int | Float | NaN
%{
    number = [1-9][0-9]*;
%}

فایل ضمیمه ۲ (extra_rules.re.inc)

// floating-point numbers
frac  = [0-9]* "." [0-9]+ | [0-9]+ ".";
exp   = 'e' [+-]? [0-9]+;
float = frac exp? | [0-9]+ exp;
float { Float }

فایل ورودی (Input file)

(* re2ocaml $INPUT -o $OUTPUT -i *)
open String
%{include "definitions.ml" %}
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable yymarker: int;
    mutable yyaccept: int;
}
%{
    re2c:YYFN = ["lex;number", "yyrecord;state"];
    re2c:yyfill:enable = 0;
    *      { NaN }
    number { Int }
    !include "extra_rules.re.inc";
%}
let test(str, num) =
    let st = {yyinput = str; yycursor = 0; yymarker = 0; yyaccept = 0}
    in if not (lex st = num) then raise (Failure "error")
let main () =
    test("123", Int);
    test("123.4567", Float)
let _ = main ()

فایل‌های سرآیند (Header files)

ابزار re2ocaml به کاربر امکان می‌دهد تا با استفاده از گزینه --header یا پیکربندی re2c:header و جفت‌بلوک‌هایی به شکل /*!header:re2c:on*/ و /*!header:re2c:off*/، یا %{header:on%} و %{header:off%}، از فایل ورودی یک فایل سرآیند تولید کند. بلوک نخست آغاز فایل سرآیند و بلوک دوم پایان آن را مشخص می‌سازد. هر آنچه میان این دو بلوک قرار گیرد توسط re2ocaml پردازش شده و کد تولیدشده در فایلی که با گزینه --header یا پیکربندی re2c:header مشخص شده نوشته می‌شود (یا در صورت عدم استفاده از گزینه یا پیکربندی، در stdout نوشته خواهد شد). فایل سرآیند تولیدشده خودکار ممکن است در مواردی نیاز باشد که از re2ocaml برای ایجاد تعاریفی استفاده می‌شود که باید از سایر واحدهای ترجمه قابل مشاهده باشند.

در ادامه مثالی از تولید یک فایل سرآیند آورده شده است که شامل تعریف وضعیت تحلیل‌گر لغوی به همراه متغیرهای برچسب (tag variables) است (تعداد متغیرها به دستور زبان باقاعده بستگی داشته و برای برنامه‌نویس نامشخص است).

فایل ورودی (Input file)

(* re2ocaml $INPUT -o $OUTPUT --header lexer/state.ml -i *)
open State
open String
%{header:on %}
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable tag: int;
    %{stags format = "mutable @@: int;"; %}
}
%{header:off %}
%{
    re2c:YYFN = ["lex;int", "yyrecord;State.state"];
    re2c:tags = 1;
    re2c:yyfill:enable = 0;
    re2c:header = "lexer/state.ml";
    [a]* @tag [b]* { yyrecord.tag }
%}
let main () =
    let st = {
        yyinput = "ab";
        yycursor = 0;
        tag = 0;
        %{stags format = "\n\t@@ = 0;"; %}
    }
    in if not (lex st = 1) then raise (Failure "error")
let _ = main ()

فایل سرآیند (Header file)

(* Generated by re2c *)
type state = {
    yyinput: string;
    mutable yycursor: int;
    mutable tag: int;
mutable yyt1: int;
}

برنامه‌های اسکلت (Skeleton programs)

با استفاده از گزینه -S, --skeleton، ابزار re2ocaml تمام کدهای غیر re2ocaml را نادیده گرفته و یک برنامه خودکفای C تولید می‌کند که می‌تواند در ادامه کامپایل و اجرا شود. این برنامه از کد تحلیل‌گر لغوی و داده‌های ورودی تشکیل شده است. به ازای هر DFA (بلوک یا شرط) ساخته‌شده، re2ocaml یک تحلیل‌گر لغوی مستقل و دو فایل تولید می‌کند: یک فایل &.input شامل رشته‌های مشتق‌شده از DFA و یک فایل &.keys با نتایج تطابق مورد انتظار. برنامه هر تحلیل‌گر را روی فایل &.input متناظر اجرا کرده و نتایج را با موارد مورد انتظار مقایسه می‌کند. برنامه‌های اسکلت به دلایل متعددی بسیار سودمند هستند:

دشواری تولید داده‌های ورودی در این است که برای تمامی موارد به جز ساده‌ترین حالت‌ها، تعداد رشته‌های ورودی ممکن بیش از حد زیاد است (حتی در حالتی که طول رشته محدود باشد). ابزار re2ocaml این مشکل را با تولید رشته‌های کافی به منظور پوشش تقریباً تمام گذارهای DFA حل می‌کند. این ابزار از الگوریتم زیر بهره می‌برد: نخست، اسکلتی از DFA می‌سازد. برای کدگذاری‌هایی با اندازه واحد کد ۱ بایتی (مانند ASCII، UTF-8 و EBCDIC) اسکلت تنها یک رونوشت دقیق از DFA اولیه است. برای کدگذاری‌هایی با واحدهای کد چندبایتی، اسکلت رونوشتی از DFA با حذف برخی گذارهاست: به این صورت که re2ocaml برای هر بازه پیوسته و مجزا که با یک گذار DFA مطابقت دارد، حداکثر ۲۵۶ واحد کد برمی‌گزیند. مقادیر انتخاب‌شده به‌طور یکنواخت توزیع شده‌اند و شامل کران‌های بازه نیز می‌شوند. re2ocaml به جای تلاش برای پوشش تمام مسیرهای ممکن در اسکلت (که امری ناشدنی است)، مسیرهای کافی را برای پوشش تمامی گذارهای اسکلت ایجاد می‌کند و بدین ترتیب پرش‌های شرطی متناظر را در تحلیل‌گر فعال می‌سازد. پیاده‌سازی این الگوریتم به حدود ۱ گیگابایت گذار محدود شده است و مقدار ثابتی از حافظه را مصرف می‌کند (re2ocaml داده‌ها را به محض تولید، در فایل می‌نویسد).

مصورسازی و اشکال‌زدایی (Visualization and debug)

با گزینه -D, --emit-dot، برنامه re2ocaml کدی تولید نمی‌کند. در عوض، DFA تولیدشده را در قالب DOT خروجی می‌دهد. می‌توان این خروجی را با استفاده از Graphviz یا کتابخانه‌ای دیگر به تصویری از DFA تبدیل کرد. توجه داشته باشید که این گزینه، DFA نهایی را پس از اعمال چندین مرحله بهینه‌سازی و تبدیل نمایش می‌دهد. مراحل پیشین را می‌توان با گزینه‌های گوناگون اشکال‌زدایی، مانند --dump-nfa، --dump-dfa-raw و غیره خروجی گرفت (فهرست کامل گزینه‌ها را ببینید).