doc/RELEASE_NOTES_V5

   1
   2                       RELEASE NOTES Ragel 5.X
   3
   4 This file describes the changes in Ragel version 5.X that are not backwards
   5 compatible. For a list of all the changes see the ChangeLog file.
   6
   7
   8 Interface to Host Programming Language
   9 ======================================
  10
  11 In version 5.0 there is a new interface to the host programming language.
  12 There are two major changes: the way Ragel specifications are embedded in the
  13 host program text, and the way that the host program interfaces with the
  14 generated code.
  15
  16 Multiline Ragel specifications begin with '%%{' and end with '}%%'. Single line
  17 specifications start with '%%' and end at the first newline. Machine names are
  18 given with the machine statement at the very beginning of a machine spec. This
  19 change was made in order to make the task of separating Ragel code from the
  20 host code as straightforward as possible. This will ease the addition of more
  21 supported host languages.
  22
  23 Ragel no longer parses structure and class names in order to infer machine
  24 names.  Parsing structures and clases requires knowledge of the host language
  25 hardcoded into Ragel. Since Ragel is moving towards language independence, this
  26 feature has been removed.
  27
  28 If a machine spec does not have a name then the previous spec name is used. If
  29 there is no previous specification then this is an error.
  30
  31 The second major frontend change in 5.0 is doing away with the init(),
  32 execute() and finish() routines. Instead of generating these functions Ragel
  33 now only generates their contents. This scheme is more flexible, allowing the
  34 user to use a single function to drive the machine or separate out the
  35 different tasks if desired. It also frees the user from having to build the
  36 machine around a structure or a class.
  37
  38 An example machine is:
  39
  40 --------------------------
  41
  42 %%{
  43     machine fsm;
  44     main := 'hello world';
  45 }%%
  46
  47 %% write data;
  48
  49 int parse( char *p )
  50 {
  51     int cs;
  52     char *pe = p + strlen(p);
  53     %%{
  54         write init;
  55         write exec;
  56     }%%
  57     return cs;
  58 };
  59
  60 --------------------------
  61
  62 The generated code expects certain variables to be available. In some cases
  63 only if the corresponding features are used.
  64
  65   el* p:         A pointer to the data to parse.
  66   el* pe:        A pointer to one past the last item.
  67   int cs:        The current state.
  68   el* tokstart:  The beginning of current match of longest match machines.
  69   el* tokend:    The end of the current match.
  70   int act:       The longest match pattern that has been matched.
  71   int stack[n]:  The stack for machine call statements
  72   int top:       The top of the stack for machine call statements
  73
  74 It is possible to specify to Ragel how the generated code should access all the
  75 variables except p and pe by using the access statement.
  76
  77   access some_pointer->;
  78   access variable_name_prefix;
  79
  80 The writing statments are:
  81
  82   write data;
  83   write init;
  84   write exec;
  85   write eof;
  86
  87 There are some options available:
  88
  89   write data noerror nofinal noprefix;
  90   write exec noend
  91
  92   noerror:   Do not write the id of the error state.
  93   nofinal:   Do not write the id of the first_final state.
  94   noprefix:  Do not prefix the variable with the name of the machine
  95   noend:     Do not test if the current character has reached pe. This is
  96              useful if one wishes to break out of the machine using fbreak
  97              when hitting some marker, such as the null character.
  98
  99 The fexec Action Statement Changed
 100 ==================================
 101
 102 The fexec action statement has been changed to take only the new position to
 103 move to. This statement is more useful for moving backwards and reparsing input
 104 than for specifying a whole new buffer entirely and has been shifted to this
 105 new use. Also, using only a single argument simplifies the parsing of Ragel
 106 input files and will ease the addition of other host languages.
 107
 108 Context Embedding Has Been Dropped
 109 ==================================
 110
 111 The context embedding operators were not carried over from version 4.X. Though
 112 interesting, they have not found any real practical use.