NAME

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

SYNOPSIS

use Inline::Filters::Ragel;

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

DESCRIPTION

This module is designed to be used with the Inline modules that provide the FILTERS feature. It provides a "factory" function, filters. This function returns an anonymous function that accepts a string input, pre-processes it with the ragel binary, and returns the output. The filters "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: You will need to download and install Ragel before this module will work. Additionally, for the FILTERS syntax in the synopsis you will need Inline::C version 0.72 or higher.

This module itself does not actually depend on any Inline stuff so it may be useful as a stand-alone ragel invoker module. Note that an alias for filters called ragel is exported for backwards compatibility.

DEBUGGING

If you set the INLINE_FILTERS_RAGEL_DEBUG environment variable, the filter will produce the following output and will not clean-up the directory mentioned:

Inline::Filters::Ragel args: $VAR1 = '-C -G2';
  --> See input/output files in /tmp/3QJBxyCy9m

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 => '-C -G2' ] ];
     %%{
       machine utf8_checker;

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

       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 := 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.