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
    <http://www.colm.net/open-source/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 <http://www.colm.net/open-source/ragel/>

    Inline-Filters-Ragel github repo
    <https://github.com/hoytech/Inline-Filters-Ragel>

AUTHOR
    Doug Hoyte, "<doug@hcsw.org>"

COPYRIGHT & LICENSE
    Copyright 2014 Doug Hoyte.

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