doc/RELEASE_NOTES_V6

   1
   2                       RELEASE NOTES Ragel 6.X
   3
   4 This file describes the changes in Ragel version 6.X that are not backwards
   5 compatible. For a list of all the changes see the ChangeLog file.
   6
   7 Leaving Actions in Scanners (new in 6.1)
   8 ========================================
   9
  10 Scanners now ensure that any leaving actions at the end of a pattern are
  11 executed. They are always executed before the pattern action.
  12
  13 The EOF Event
  14 =============
  15
  16 There is a new execution variable called "eof". This should be set to pe on the
  17 execution of the last buffer block. When p == eof the state machine's EOF
  18 actions are executed. The variable is required only when EOF actions have been
  19 embedded.
  20
  21 The advantage of this over "write eof" is that EOF actions are now executed in
  22 the same context as regular actions. They are free to manipulate p, and jump to
  23 a new portion of the machine to reprocess input. This was not possible with
  24 "write eof".
  25
  26 The "write eof" directive was consequently removed.
  27
  28 Scanners now use EOF actions to to flush out the last token, if needed. This
  29 eliminates the need to manually flush the last token.
  30
  31 Semantics of > % and Error Actions
  32 ==================================
  33
  34 Ragel has gone back to the 3.X semantics for >, % and error actions.
  35
  36 Those that have been using Ragel since the 3.X days will remember that the
  37 entering operator > embedded a leaving action/priority into the start state
  38 when it was final. The leaving operator % would embed EOF actions when the
  39 final states stayed final all the way to the end of compilation. Also, error
  40 actions would embed EOF actions when at the end of compilation the states the
  41 error actions were embedded into were not final.
  42
  43 The problem before was that EOF actions and regular actions were executed in
  44 different contexts ("write exec" and "write eof"), and a single action block
  45 could easily end up in two different functions. This could lead to compile
  46 errors and other subtle errors. Now that all actions are executed in the same
  47 context ("write exec") these problems go away. The original semantics has been
  48 restored.
  49
  50 Backend Automatically Executed
  51 ==============================
  52
  53 The "ragel" program now automatically executes the appropriate backend. If you
  54 need the intermediate XML format you can use the -x option.
  55
  56 The fbreak Statement
  57 ====================
  58
  59 The fbreak statement now advances p. It is now possible to break out of the
  60 machine and restart it without having to fix p first. Originally, fbreak did
  61 not advance p because it was intended to be used to terminate processing.
  62 Advancing p was more work than necessary in that case. But fbreak turns out to
  63 be useful for stopping to return a token as well. In this case the failure to
  64 advance p is an inconvenience.
  65
  66 Guarded Concatenation Operators are Stronger
  67 ============================================
  68
  69 The :> :>> and <: guarded concatenation operators have been strengthened. In
  70 the previous version of Ragel is was possible for the priority assignments to
  71 be bypassed via the the zero length string. Running the following examples
  72 through 5.25 you will see that the a and b actions are executed on a single
  73 transition, showing the guard fails. This happens because the operators did not
  74 consider that the middle machine might have a start state that is final. In 6.0
  75 these cases have been fixed.
  76
  77     (' '@a)* <: 'x'* . ' '@b;
  78     (' '@a)* :> 'x'? . ' '@b;
  79     (' '@a)* :>> 'xyz'? . ' '@b;
  80
  81 The tokstart and tokend Variables Renamed
  82 =========================================
  83
  84 The "tokstart" and "tokend" variables were changed to "ts" and "te". These
  85 variables get referenced a lot in scanner actions. They should be shorter.
  86
  87 To update your code simply search and replace:
  88     tokstart => ts
  89     tokend => te
  90
  91 Options
  92 =======
  93
  94 The -l option in rlgen-cd was changed to -L because -l is used in the frontend,
  95 which now must pass options through.