NAME

Inline::Filters::Ragel - Run ragel when compiling your Inline modules

SYNOPSIS

    use Inline::Filters::Ragel;

    use Inline C => <<'END', filters => [ ragel ];
      // ragel/C code goes here
    END

DESCRIPTION

This module exports one "factory" function, ragel. This function returns an anonymous function that accepts a string input, pre-processes it with the ragel binary, and returns the output. The ragel "factory" function can optionally take a string or multiple strings which will be passed along to the ragel binary. You will need to do this if you are compiling a language other than the default (C/C++), or if you wish to change the ragel state-machine compilation type.

Note that you will need to download and install Ragel before this module will work. It is my hope that modules will not require ragel at distribution time since we now have Inline::Module (but I haven't tested that yet).

This module itself does not actually depend on any Inline stuff so it may be useful as a stand-alone ragel invoker module.

FULL EXAMPLE

As an example, here is the definition of an is_valid_utf8 function which uses ragel. When passed a string, this function will determine whether the string in question contains a valid UTF-8 sequence or not:

    use Inline::Filters::Ragel;

    use Inline C => <<'END', FILTERS => [ ragel('-G2') ];
      %%{
        machine utf8_checker;

        ## Adapted from: http://www.w3.org/International/questions/qa-forms-utf-8

        utf8_codepoint = (0x09 | 0x0A | 0x0D | 0x20..0x7E)            | # ASCII
                         (0xC2..0xDF 0x80..0xBF)                      | # non-overlong 2-byte
                         (0xE0 0xA0..0xBF 0x80..0xBF)                 | # excluding overlongs
                         ((0xE1..0xEC | 0xEE | 0xEF) (0x80..0xBF){2}) | # straight 3-byte
                         (0xED 0x80..0x9F 0x80..0xBF)                 | # excluding surrogates
                         (0xF0 0x90..0xBF (0x80..0xBF){2})            | # planes 1-3
                         (0xF1..0xF3 (0x80..0xBF){3})                 | # planes 4-15
                         (0xF4 0x80..0x8F (0x80..0xBF){2});             # plane 16

        main := utf8_codepoint*;

        write data;
      }%%
 
      int is_valid_utf8(SV* string) {
        size_t len;
        char *p, *pe;
        int cs;

        SvUPGRADE(string, SVt_PV);
        if (!SvPOK(string)) croak("non-string object passed to is_valid_utf8");

        len = SvCUR(string);
        p = SvPV(string, len);
        pe = p + len;

        %% write init;
        %% write exec;

        if (cs < utf8_checker_first_final) return 0;

        return 1;
      }
    END

SEE ALSO

Inline and Inline::Filters

Ragel State Machine Compiler

Inline-Filters-Ragel github repo

AUTHOR

Doug Hoyte, <doug@hcsw.org>

COPYRIGHT & LICENSE

Copyright 2014 Doug Hoyte.

This module is licensed under the same terms as perl itself.