diff options
Diffstat (limited to 'doc/ragel/RELEASE_NOTES_V5')
| -rw-r--r-- | doc/ragel/RELEASE_NOTES_V5 | 112 |
1 files changed, 0 insertions, 112 deletions
diff --git a/doc/ragel/RELEASE_NOTES_V5 b/doc/ragel/RELEASE_NOTES_V5 deleted file mode 100644 index 15147d8a..00000000 --- a/doc/ragel/RELEASE_NOTES_V5 +++ /dev/null @@ -1,112 +0,0 @@ - - RELEASE NOTES Ragel 5.X - -This file describes the changes in Ragel version 5.X that are not backwards -compatible. For a list of all the changes see the ChangeLog file. - - -Interface to Host Programming Language -====================================== - -In version 5.0 there is a new interface to the host programming language. -There are two major changes: the way Ragel specifications are embedded in the -host program text, and the way that the host program interfaces with the -generated code. - -Multiline Ragel specifications begin with '%%{' and end with '}%%'. Single line -specifications start with '%%' and end at the first newline. Machine names are -given with the machine statement at the very beginning of a machine spec. This -change was made in order to make the task of separating Ragel code from the -host code as straightforward as possible. This will ease the addition of more -supported host languages. - -Ragel no longer parses structure and class names in order to infer machine -names. Parsing structures and clases requires knowledge of the host language -hardcoded into Ragel. Since Ragel is moving towards language independence, this -feature has been removed. - -If a machine spec does not have a name then the previous spec name is used. If -there is no previous specification then this is an error. - -The second major frontend change in 5.0 is doing away with the init(), -execute() and finish() routines. Instead of generating these functions Ragel -now only generates their contents. This scheme is more flexible, allowing the -user to use a single function to drive the machine or separate out the -different tasks if desired. It also frees the user from having to build the -machine around a structure or a class. - -An example machine is: - --------------------------- - -%%{ - machine fsm; - main := 'hello world'; -}%% - -%% write data; - -int parse( char *p ) -{ - int cs; - char *pe = p + strlen(p); - %%{ - write init; - write exec; - }%% - return cs; -}; - --------------------------- - -The generated code expects certain variables to be available. In some cases -only if the corresponding features are used. - - el* p: A pointer to the data to parse. - el* pe: A pointer to one past the last item. - int cs: The current state. - el* tokstart: The beginning of current match of longest match machines. - el* tokend: The end of the current match. - int act: The longest match pattern that has been matched. - int stack[n]: The stack for machine call statements - int top: The top of the stack for machine call statements - -It is possible to specify to Ragel how the generated code should access all the -variables except p and pe by using the access statement. - - access some_pointer->; - access variable_name_prefix; - -The writing statments are: - - write data; - write init; - write exec; - write eof; - -There are some options available: - - write data noerror nofinal noprefix; - write exec noend - - noerror: Do not write the id of the error state. - nofinal: Do not write the id of the first_final state. - noprefix: Do not prefix the variable with the name of the machine - noend: Do not test if the current character has reached pe. This is - useful if one wishes to break out of the machine using fbreak - when hitting some marker, such as the null character. - -The fexec Action Statement Changed -================================== - -The fexec action statement has been changed to take only the new position to -move to. This statement is more useful for moving backwards and reparsing input -than for specifying a whole new buffer entirely and has been shifted to this -new use. Also, using only a single argument simplifies the parsing of Ragel -input files and will ease the addition of other host languages. - -Context Embedding Has Been Dropped -================================== - -The context embedding operators were not carried over from version 4.X. Though -interesting, they have not found any real practical use. |