[ragel-users] The meaning of Figure 2.1 in the manual

[Nate]

Something like this doesn't necessarily need to go in the manual. Ragel
would benefit from tutorial-style articles that show how to use Ragel to
parse something simple and then progressively introduce more Ragel
features. Eg, how to use Ragel to parse C-style single line comments, then
how to add multi-line comments to that, etc. It's a lot easier to toy with
executable example code that is similar to the problem you need to solve
yourself than it is to create your own learning examples solely by reading
the manual.

Note that this is a great candidate for community contribution. Ragel is
great so if you have the time and inkling, writing such articles is a good
way to give back -- the beauty of open source!


On Sat, Feb 23, 2019 at 12:59 PM Peng Yu <pengyu.ut at gmail.com> wrote:

> Can I recommend adding more examples (not just ragel code snippet, but
> complete recipes of minimal working examples, including command line
> commands, meanings of input and output, how the generated C code structure
> and works, etc). It must be both minimal and working. “Minimal” means, to
> show a point, don’t show any code more than necessary to demonstrate the
> point. Working means the recipe should just work, it should not require use
> to first understand it meaning then add some missing pieces to make it work.
>
> I graduately get what it means in the manual by fill in these holes
> myself. But It is too slow. It should not be in this way had the manual
> were written in a more new-user friendly manner.
>
> In this specific case, my understanding of its purpose is to just show
> some simple ragel code that will run. I’d suggest that you don’t show the
> “0”. If you must show it, explain what it means right after showing the
> example. What it should not be done is to use it but not explain it. Things
> like this just make the manual hard to understand, at it causes cyclic
> dependency.
>
> Dose it make sense?
>
>
> On Sat, Feb 23, 2019 at 3:39 AM Adrian Thurston <thurston at colm.net> wrote:
>
>> Hi Peng, I recommend you read a bit more of the manual. You'll find all
>> the answers there. Thanks!
>>
>> On 2019-02-22 08:35, Peng Yu wrote:
>> > Hi,
>> >
>> > I have a hard time to understand the exact meaning of Figure 2.1. I
>> > understand the regex part.
>> >
>> > But what `0 @{ res = 1; };` means.
>> >
>> > How p and pe are used in `write init` and `write exec`?
>> >
>> > char *p = argv[1];
>> > char *pe = p + strlen(p) + 1;
>> > %% write init;
>> > %% write exec;
>> >
>> > How to make the example on the right-hand-side of Figure 2.1 compiled?
>> > Thanks.
>> >
>> > #include <string.h>
>> > #include <stdio.h>
>> > %%{
>> > machine foo;
>> > main :=
>> > ( 'foo' | 'bar' )
>> > 0 @{ res = 1; };
>> > }%%
>> > %% write data;
>> > int main( int argc, char **argv )
>> > {
>> > int cs, res = 0;
>> > if ( argc > 1 ) {
>> > char *p = argv[1];
>> > char *pe = p + strlen(p) + 1;
>> > %% write init;
>> > %% write exec;
>> > }
>> > printf("result = %i\n", res );
>> > return 0;
>> > }
>>
>> _______________________________________________
>> ragel-users mailing list
>> ragel-users at colm.net
>> http://www.colm.net/cgi-bin/mailman/listinfo/ragel-users
>
> --
> Regards,
> Peng
> _______________________________________________
> ragel-users mailing list
> ragel-users at colm.net
> http://www.colm.net/cgi-bin/mailman/listinfo/ragel-users
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.colm.net/pipermail/ragel-users/attachments/20190223/4d93548b/attachment.html>