diff options
| author | Adrian Thurston <thurston@colm.net> | 2020-03-14 11:27:58 +0200 |
|---|---|---|
| committer | Adrian Thurston <thurston@colm.net> | 2020-03-14 11:27:58 +0200 |
| commit | 2ba036ed94c826a0b814cf15181a4a9e6f89b178 (patch) | |
| tree | 7a778c2b06c3d4a059cd8806ff4cdccf4a07b475 /doc | |
| parent | 78e7949ca590b273c2c152a0abe0d51e590a52fd (diff) | |
| download | colm-2ba036ed94c826a0b814cf15181a4a9e6f89b178.tar.gz | |
removed ragel docs, old makefiles, todo, vim, etc
Diffstat (limited to 'doc')
52 files changed, 1 insertions, 12491 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 2f858ab4..336609b9 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1 +1 @@ -SUBDIRS = colm ragel +SUBDIRS = colm diff --git a/doc/ragel/.gitignore b/doc/ragel/.gitignore deleted file mode 100644 index 485d9670..00000000 --- a/doc/ragel/.gitignore +++ /dev/null @@ -1,99 +0,0 @@ -/Makefile -/Makefile.in -/version.tex -/ragel-guide.tex -/ragel-guide.aux -/ragel-guide.dvi -/ragel-guide.log -/ragel-guide.pdf -/ragel-guide.out -/ragel-guide.toc -/ragel.1 -/exstact.pdf -/explus.pdf -/exallact.pdf -/exstar.pdf -/opconcat.pdf -/exaction.pdf -/exor.pdf -/lmkleene.pdf -/entryguard.pdf -/bmor.pdf -/finguard.pdf -/bmnum.pdf -/exinter.pdf -/exallpri.pdf -/stembed.pdf -/exsubtr.pdf -/exconcat.pdf -/opstar.pdf -/bmrange.pdf -/opor.pdf -/bmconcat.pdf -/bmnull.pdf -/bmregex.pdf -/exstrongsubtr.pdf -/exdonepri.pdf -/exnegate.pdf -/exfinact.pdf -/exoption.pdf -/exoutact1.pdf -/exoutact2.pdf -/lmkleene.pdf -/ChangeLog.gz -/smallscanner.pdf -/lines1.pdf -/lines2.pdf -/comments1.pdf -/comments2.pdf -/leftguard.pdf -/exdoneact.pdf -/dropdown.pdf -/conds1.pdf -/conds2.pdf -/generate -/generate.c - -/exstact.png -/explus.png -/exallact.png -/exstar.png -/opconcat.png -/exaction.png -/exor.png -/lmkleene.png -/entryguard.png -/bmor.png -/finguard.png -/bmnum.png -/exinter.png -/exallpri.png -/stembed.png -/exsubtr.png -/exconcat.png -/opstar.png -/bmrange.png -/opor.png -/bmconcat.png -/bmnull.png -/bmregex.png -/exstrongsubtr.png -/exdonepri.png -/exnegate.png -/exfinact.png -/exoption.png -/exoutact1.png -/exoutact2.png -/lmkleene.png -/smallscanner.png -/lines1.png -/lines2.png -/comments1.png -/comments2.png -/leftguard.png -/exdoneact.png -/dropdown.png -/conds1.png -/conds2.png - -/ragel-guide.html diff --git a/doc/ragel/Makefile.am b/doc/ragel/Makefile.am deleted file mode 100644 index 9a1e2c9d..00000000 --- a/doc/ragel/Makefile.am +++ /dev/null @@ -1,60 +0,0 @@ -# -# Copyright 2001-2016 Adrian Thurston <thurston@colm.net> -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to -# deal in the Software without restriction, including without limitation the -# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -# sell copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. -# - -man_MANS = ragel.1 - -EXTRA_DIST = ragel-guide.txt ragel.1.in \ - bmconcat.fig bmregex.fig dropdown.fig exdoneact.fig \ - exoutact1.fig exstrongsubtr.fig lines2.fig smallscanner.fig bmnull.fig \ - comments1.fig entryguard.fig exinter.fig exoutact2.fig exsubtr.fig \ - lmkleene.fig stembed.fig bmnum.fig comments2.fig exaction.fig \ - exnegate.fig explus.fig finguard.fig opconcat.fig bmor.fig conds1.fig \ - exallact.fig exoption.fig exstact.fig leftguard.fig opor.fig \ - bmrange.fig conds2.fig exconcat.fig exor.fig exstar.fig lines1.fig \ - opstar.fig - -ragel.1: ragel.1.in - @$(top_srcdir)/sedsubst $< $@ -w,+x $(SED_SUBST) - -if BUILD_MANUAL - -doc_DATA = ragel-guide.html ragel-guide.pdf - -.fig.png: - fig2dev -L png -S 4 $< $@ - -ragel-guide.html: ragel-guide.txt - asciidoc -d book $< - -ragel-guide.html: bmconcat.png bmregex.png dropdown.png exdoneact.png \ - exoutact1.png exstrongsubtr.png lines2.png smallscanner.png bmnull.png \ - comments1.png entryguard.png exinter.png exoutact2.png exsubtr.png \ - lmkleene.png stembed.png bmnum.png comments2.png exaction.png \ - exnegate.png explus.png finguard.png opconcat.png bmor.png conds1.png \ - exallact.png exoption.png exstact.png leftguard.png opor.png \ - bmrange.png conds2.png exconcat.png exor.png exstar.png lines1.png \ - opstar.png - -ragel-guide.pdf: ragel-guide.txt - a2x --verbose -f pdf -d book $< - -endif diff --git a/doc/ragel/RELEASE_NOTES_V2 b/doc/ragel/RELEASE_NOTES_V2 deleted file mode 100644 index 1d03eda8..00000000 --- a/doc/ragel/RELEASE_NOTES_V2 +++ /dev/null @@ -1,86 +0,0 @@ - Porting Ragel Programs to Version 2 - =================================== - - -1. Move all ?, +, and * operators to the right hand side of the operand. - - float = *digit ?('.' +digit); - - float = digit* ('.' digit+)?; - -2. Change all assignments to main from a definition using the = operator to an -instantiation using the := operator. - - main = 'hello'; - - main := 'hello'; - -3. Remove $0 %! operations for clearing priorities. - -4. Anywhere implicit default priorities of zero are used to interact with -explicitly set non-zero transitions, set the priorities to zero explicitly. - - main := any* 'FIN' :1; - - main := ( any $0 )* 'FIN' :1; - -5. If priorities need to interact across different machines, use a common name. -Note that priority names default to the name of the machine they are assigned -to. - - wild = any*; - main := wild 'FIN' :1; - - wild = ( any $0 )*; - main := wild 'FIN' :wild,1; - -6. If using clear keyword or operators modified with ^, duplicate the operand -machines and rewrite them such that the cleared actions and suppressed out -transitions and out priorities are removed. - -7. Change func keyword to action. - -8. Escape any - symbols and initial ^ symbol in or literals ([] outside of -regular expressions). - - main := [^#$-+*]; - - main := [\^#$\-+*]; - -9. In C output, lowercase init, execute and finish routines and put an -underscore in between the fsm name and the function name. Also qualify -references to the fsm structure with the struct keyword. - - fsm f; - fsmInit( &f ); - fsmExecute( &f, buf, len ); - fsmFinish( &f ); - - struct fsm f; - fsm_init( &f ); - fsm_execute( &f, buf, len ); - fsm_finish( &f ); - -10. In C++ output, lowercase the init, execute and finish routines. Also make -sure that the init routine is explicitly called. - - fsm f; - f.Init(); - f.Execute( buf, len ); - f.Finish(); - - fsm f; - f.init(); - f.execute( buf, len ); - f.finish(); - -11. Remove calls to the accept routine, instead examine the return value of the -finish routine. If the machine does not accept then finish returns -1 or 0, if -the machine accepts then finish returns 1. - - f.finish(); - if ( f.accept() ) - cout << "ACCEPT" << endl; - - if ( f.finish() > 0 ) - cout << "ACCEPT" << endl; diff --git a/doc/ragel/RELEASE_NOTES_V3 b/doc/ragel/RELEASE_NOTES_V3 deleted file mode 100644 index 64dd2f11..00000000 --- a/doc/ragel/RELEASE_NOTES_V3 +++ /dev/null @@ -1,8 +0,0 @@ - Porting Ragel Version 2 Programs to Version 3 - ============================================= - -1. Replace all instances of *p in action code with the keyword fc. - -2. Replace all instances of : used to set actions or priorities with @. - -3. Wrap named priorities in parentheses so they are of the form @(name,1). diff --git a/doc/ragel/RELEASE_NOTES_V4 b/doc/ragel/RELEASE_NOTES_V4 deleted file mode 100644 index a142f368..00000000 --- a/doc/ragel/RELEASE_NOTES_V4 +++ /dev/null @@ -1,361 +0,0 @@ - - RELEASE NOTES Ragel 4.X - - -To-State and From-State Action Embedding Operators Added (4.2) -============================================================== - -Added operators for embedding actions into all transitions into a state and all -transitions out of a state. These embeddings stay with the state, and are -irrespective of what the current transitions are and any future transitions -that may be added into or out of the state. - -In the following example act is executed on the transitions for 't' and 'y'. -Even though it is only embedded in the context of the first alternative. This -is because after matching 'hi ', the machine has not yet distinguished beween -the two threads. The machine is simultaneously in the state expecting 'there' -and the state expecting 'you'. - - action act {} - main := - 'hi ' %*act 'there' | - 'hi you'; - -The to-state action embedding operators embed into transitions that go into: ->~ the start state -$~ all states -%~ final states -<~ states that are not the start -@~ states that are not final -<@~ states that are not the start AND not final - -The from-state action embedding operators embed into transitions that leave: ->* the start state -$* all states -%* final states -<* states that are not the start -@* states that are not final -<@* states that are not the start AND not final - -Changed Operators for Embedding Context/Actions Into States (4.2) -================================================================= - -The operators used to embed context and actions into states have been modified. -The purpose of the modification is to make it easier to distribute actions to -take among the states in a chain of concatenations such that each state has -only a single action embedded. An example follows below. - -Now Gone: - -1. The use of >@ for selecting the states to modfiy (as in >@/ to embed eof - actions, etc) has been removed. This prefix meant start state OR not start AND - not final. - -2. The use of @% for selecting states to modify (as in @%/ to embed eof - actions, etc) has been removed. This prefix previously meant not start AND not - final OR final. - -Now Added: - -1. The prefix < which means not start. -2. The prefix @ which means not final. -3. The prefix <@ which means not start & not final" - -The new matrix of operators used to embed into states is: - ->: $: %: <: @: <@: - context ->~ $~ %~ <~ @~ <@~ - to state action ->* $* %* <* @* <@* - from state action ->/ $/ %/ </ @/ <@/ - eof action ->! $! %! <! @! <@! - error action ->^ $^ %^ <^ @^ <@^ - local error action - -| | | | | | -| | | | | *- not start & not final -| | | | | -| | | | *- not final -| | | | -| | | *- not start -| | | -| | *- final -| | -| *- all states -| -*- start state - -This example shows one way to use the new operators to cover all the states -with a single action. The embedding of eof2 covers all the states in m2. The -embeddings of eof1 and eof3 avoid the boundaries that m1 and m3 both share with -m2. - - action eof1 {} - action eof2 {} - action eof3 {} - m1 = 'm1'; - m2 = ' '+; - m3 = 'm3'; - - main := m1 @/eof1 . m2 $/eof2 . m3 </eof3; - -Verbose Action, Priority and Context Embedding Added (4.2) -========================================================== - -As an alternative to the symbol-based action, priority and context embedding -operators, a more verbose form of embedding has been added. The general form of -the verbose embedding is: - - machine <- location [modifier] embedding_type value - -For embeddings into transitions, the possible locations are: - enter -- entering transitions - all -- all transitions - finish -- transitions into a final state - leave -- pending transitions out of the final states - -For embeddings into states, the possible locations are: - start -- the start state - all -- all states - final -- final states - !start -- all states except the start - !final -- states that are not final - !start !final -- states that are not the start and not final - -The embedding types are: - exec -- an action into transitions - pri -- a priority into transitions - ctx -- a named context into a state - into -- an action into all transitions into a state - from -- an action into all transitions out of a state - err -- an error action into a state - lerr -- a local error action into a state - -The possible modfiers: - on name -- specify a name for priority and local error embedding - -Character-Level Negation '^' Added (4.1) -======================================== - -A character-level negation operator ^ was added. This operator has the same -precedence level as !. It is used to match single characters that are not -matched by the machine it operates on. The expression ^m is equivalent to -(any-(m)). This machine makes sense only when applied to machines that match -single characters. Since subtraction is essentially a set difference, any -strings matched by m that are not of length 1 will be ignored by the -subtraction and have no effect. - -Discontinued Plus Sign To Specifify Positive Literal Numbers (4.1) -================================================================== - -The use of + to specify a literal number as positive has been removed. This -notation is redundant because all literals are positive by default. It was -unlikely to be used but was provided for consistency. This notation caused an -ambiguity with the '+' repetition operator. Due to this ambibuity, and the fact -that it is unlikely to be used and is completely unnecessary when it is, it has -been removed. This simplifies the design. It elimnates possible confusion and -removes the need to explain why the ambiguity exists and how it is resolved. - -As a consequence of the removal, any expression (m +1) or (m+1) will now be -parsed as (m+ . 1) rather then (m . +1). This is because previously the scanner -handled positive literals and therefore they got precedence over the repetition -operator. - -Precedence of Subtraction Operator vs Negative Literals Changed (4.1) -===================================================================== - -Previously, the scanner located negative numbers and therefore gave a higher -priority to the use of - to specify a negative literal number. This has -changed, precedence is now given to the subtraction operator. - -This change is for two reasons: A) The subtraction operator is far more common -than negative literal numbers. I have quite often been fooled by writing -(any-0) and having it parsed as ( any . -0 ) rather than ( any - 0 ) as I -wanted. B) In the definition of concatentation I want to maintain that -concatenation is used only when there are no other binary operators separating -two machines. In the case of (any-0) there is an operator separating the -machines and parsing this as the concatenation of (any . -0) violates this -rule. - -Duplicate Actions are Removed From Action Lists (4.1) -===================================================== - -With previous versions of Ragel, effort was often expended towards ensuring -identical machines were not uniononed together, causing duplicate actions to -appear in the same action list (transition or eof perhaps). Often this required -factoring out a machine or specializing a machine's purpose. For example, -consider the following machine: - - word = [a-z]+ >s $a %l; - main := - ( word ' ' word ) | - ( word '\t' word ); - -This machine needed to be rewritten as the following to avoid duplicate -actions. This is essentially a refactoring of the machine. - - main := word ( ' ' | '\t' ) word; - -An alternative was to specialize the machines: - - word1 = [a-z]+ >s $a %l; - word2 = [a-z]+; - main := - ( word1 ' ' word1 ) | - ( word2 '\t' word1 ); - -Since duplicating an action on a transition is never (in my experience) desired -and must be manually avoided, sometimes to the point of obscuring the machine -specification, it is now done automatically by Ragel. This change should have -no effect on existing code that is properly written and will allow the -programmer more freedom when writing new code. - -New Frontend (4.0) -================== - -The syntax for embedding Ragel statements into the host language has changed. -The primary motivation is a better interaction with Objective-C. Under the -previous scheme Ragel generated the opening and closing of the structure and -the interface. The user could inject user defined declarations into the struct -using the struct {}; statement, however there was no way to inject interface -declarations. Under this scheme it was also awkward to give the machine a base -class. Rather then add another statement similar to struct for including -declarations in the interface we take the reverse approach, the user now writes -the struct and interface and Ragel statements are injected as needed. - -Machine specifications now begin with %% and are followed with an optional name -and either a single ragel statement or a sequence of statements enclosed in {}. -If a machine specification does not have a name then Ragel tries to find a name -for it by first checking if the specification is inside a struct or class or -interface. If it is not then it uses the name of the previous machine -specification. If still no name is found then an error is raised. - -Since the user now specifies the fsm struct directly and since the current -state and stack variables are now of type integer in all code styles, it is -more appropriate for the user to manage the declarations of these variables. -Ragel no longer generates the current state and the stack data variables. This -also gives the user more freedom in deciding how the stack is to be allocated, -and also permits it to be grown as necessary, rather than allowing only a fixed -stack size. - -FSM specifications now persist in memory, so the second time a specification of -any particular name is seen the statements will be added to the previous -specification. Due to this it is no longer necessary to give the element or -alphabet type in the header portion and in the code portion. In addition there -is now an include statement that allows the inclusion of the header portion of -a machine it it resides in a different file, as well as allowing the inclusion -of a machine spec of a different name from the any file at all. - -Ragel is still able to generate the machine's function declarations. This may -not be required for C code, however this will be necessary for C++ and -Objective-C code. This is now accomplished with the interface statement. - -Ragel now has different criteria for deciding what to generate. If the spec -contains the interface statement then the machine's interface is generated. If -the spec contains the definition of a main machine, then the code is generated. -It is now possible to put common machine definitions into a separate library -file and to include them in other machine specifications. - -To port Ragel 3.x programs to 4.x, the FSM's structure must be explicitly coded -in the host language and it must include the declaration of current state. This -should be called 'curs' and be of type int. If the machine uses the fcall -and fret directives, the structure must also include the stack variables. The -stack should be named 'stack' and be of type int*. The stack top should be -named 'top' and be of type int. - -In Objective-C, the both the interface and implementation directives must also -be explicitly coded by the user. Examples can be found in the section "New -Interface Examples". - -Action and Priority Embedding Operators (4.0) -============================================= - -In the interest of simplifying the language, operators now embed strictly -either on characters or on EOF, but never both. Operators should be doing one -well-defined thing, rather than have multiple effects. This also enables the -detection of FSM commands that do not make sense in EOF actions. - -This change is summarized by: - -'%' operator embeds only into leaving characters. - -All global and local error operators only embed on error character - transitions, their action will not be triggerend on EOF in non-final states. - -Addition of EOF action embedding operators for all classes of states to make - up for functionality removed from other operators. These are >/ $/ @/ %/. - -Start transition operator '>' does not imply leaving transtions when start - state is final. - -This change results in a simpler and more direct relationship between the -operators and the physical state machine entities they operate on. It removes -the special cases within the operators that require you to stop and think as -you program in Ragel. - -Previously, the pending out transition operator % simultaneously served two -purposes. First, to embed actions to that are to get transfered to transitions -made going out of the machine. These transitions are created by the -concatentation and kleene star operators. Second, to specify actions that get -executed on EOF should the final state in the machine to which the operator is -applied remain final. - -To convert Ragel 3.x programs: Any place where there is an embedding of an -action into pending out transitions using the % operator and the final states -remain final in the end result machine, add an embedding of the same action -using the EOF operator %/action. - -Also note that when generating dot file output of a specific component of a -machine that has leaving transitions embedded in the final states, these -transitions will no longer show up since leaving transtion operator no longer -causes actions to be moved into the the EOF event when the state they are -embeeded into becomes a final state of the final machine. - -Const Element Type (4.0) -======================== - -If the element type has not been defined, the previous behaviour was to default -to the alphabet type. The element type however is usually not specified as -const and in most cases the data pointer in the machine's execute function -should be a const pointer. Therefore ragel now makes the element type default -to a constant version of the alphabet type. This can always be changed by using -the element statment. For example 'element char;' will result in a non-const -data pointer. - -New Interface Examples (4.0) -============================ - ----------- C ---------- - -struct fsm -{ - int curs; -}; - -%% fsm -{ - main := 'hello world'; -} - ---------- C++ --------- - -struct fsm -{ - int curs; - %% interface; -}; - -%% main := 'hello world'; - ------ Objective-C ----- - -@interface Clang : Object -{ -@public - int curs; -}; - -%% interface; - -@end - -@implementation Clang - -%% main := 'hello world'; - -@end - 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. diff --git a/doc/ragel/RELEASE_NOTES_V6 b/doc/ragel/RELEASE_NOTES_V6 deleted file mode 100644 index b08b8a33..00000000 --- a/doc/ragel/RELEASE_NOTES_V6 +++ /dev/null @@ -1,95 +0,0 @@ - - RELEASE NOTES Ragel 6.X - -This file describes the changes in Ragel version 6.X that are not backwards -compatible. For a list of all the changes see the ChangeLog file. - -Leaving Actions in Scanners (new in 6.1) -======================================== - -Scanners now ensure that any leaving actions at the end of a pattern are -executed. They are always executed before the pattern action. - -The EOF Event -============= - -There is a new execution variable called "eof". This should be set to pe on the -execution of the last buffer block. When p == eof the state machine's EOF -actions are executed. The variable is required only when EOF actions have been -embedded. - -The advantage of this over "write eof" is that EOF actions are now executed in -the same context as regular actions. They are free to manipulate p, and jump to -a new portion of the machine to reprocess input. This was not possible with -"write eof". - -The "write eof" directive was consequently removed. - -Scanners now use EOF actions to to flush out the last token, if needed. This -eliminates the need to manually flush the last token. - -Semantics of > % and Error Actions -================================== - -Ragel has gone back to the 3.X semantics for >, % and error actions. - -Those that have been using Ragel since the 3.X days will remember that the -entering operator > embedded a leaving action/priority into the start state -when it was final. The leaving operator % would embed EOF actions when the -final states stayed final all the way to the end of compilation. Also, error -actions would embed EOF actions when at the end of compilation the states the -error actions were embedded into were not final. - -The problem before was that EOF actions and regular actions were executed in -different contexts ("write exec" and "write eof"), and a single action block -could easily end up in two different functions. This could lead to compile -errors and other subtle errors. Now that all actions are executed in the same -context ("write exec") these problems go away. The original semantics has been -restored. - -Backend Automatically Executed -============================== - -The "ragel" program now automatically executes the appropriate backend. If you -need the intermediate XML format you can use the -x option. - -The fbreak Statement -==================== - -The fbreak statement now advances p. It is now possible to break out of the -machine and restart it without having to fix p first. Originally, fbreak did -not advance p because it was intended to be used to terminate processing. -Advancing p was more work than necessary in that case. But fbreak turns out to -be useful for stopping to return a token as well. In this case the failure to -advance p is an inconvenience. - -Guarded Concatenation Operators are Stronger -============================================ - -The :> :>> and <: guarded concatenation operators have been strengthened. In -the previous version of Ragel is was possible for the priority assignments to -be bypassed via the the zero length string. Running the following examples -through 5.25 you will see that the a and b actions are executed on a single -transition, showing the guard fails. This happens because the operators did not -consider that the middle machine might have a start state that is final. In 6.0 -these cases have been fixed. - - (' '@a)* <: 'x'* . ' '@b; - (' '@a)* :> 'x'? . ' '@b; - (' '@a)* :>> 'xyz'? . ' '@b; - -The tokstart and tokend Variables Renamed -========================================= - -The "tokstart" and "tokend" variables were changed to "ts" and "te". These -variables get referenced a lot in scanner actions. They should be shorter. - -To update your code simply search and replace: - tokstart => ts - tokend => te - -Options -======= - -The -l option in rlgen-cd was changed to -L because -l is used in the frontend, -which now must pass options through. diff --git a/doc/ragel/bmconcat.fig b/doc/ragel/bmconcat.fig deleted file mode 100644 index 921f1313..00000000 --- a/doc/ragel/bmconcat.fig +++ /dev/null @@ -1,78 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: bmconcat -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 2550 33 33 33 2550 66 2583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 2550 383 383 1333 2550 1716 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 1333 2633 0\001 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 66 2550 139 2550 237 2550 354 2550 485 2550 624 2550 766 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 766 2483 933 2550 766 2600 766 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 500 2500 IN\001 -# 5 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 9400 2550 383 383 9400 2550 9783 2933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 9400 2550 450 450 9400 2550 9850 3000 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 9400 2633 5\001 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2966 2550 383 383 2966 2550 3349 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2966 2633 1\001 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 1733 2550 1837 2550 1946 2550 2060 2550 2175 2550 2289 2550 2400 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 2400 2483 2566 2550 2400 2600 2400 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2150 2500 'h'\001 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4566 2550 383 383 4566 2550 4949 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 4566 2633 2\001 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 3366 2550 3467 2550 3571 2550 3677 2550 3783 2550 3891 2550 4000 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 4000 2483 4166 2550 4000 2600 4000 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 3766 2500 'e'\001 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6133 2550 383 383 6133 2550 6516 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 6133 2633 3\001 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 4966 2550 5060 2550 5159 2550 5260 2550 5362 2550 5465 2550 5566 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 5566 2483 5733 2550 5566 2600 5566 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 5350 2500 'l'\001 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 7700 2550 383 383 7700 2550 8083 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 7700 2633 4\001 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 6533 2550 6627 2550 6725 2550 6827 2550 6929 2550 7032 2550 7133 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 7133 2483 7300 2550 7133 2600 7133 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 6916 2500 'l'\001 -# 4 -> 5 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 8100 2550 8202 2550 8309 2550 8420 2550 8534 2550 8650 2550 8766 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 8766 2483 8933 2550 8766 2600 8766 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 8516 2500 'o'\001 -# end of FIG file diff --git a/doc/ragel/bmnull.fig b/doc/ragel/bmnull.fig deleted file mode 100644 index a56e2ad9..00000000 --- a/doc/ragel/bmnull.fig +++ /dev/null @@ -1,28 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: bmnull -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 2550 33 33 33 2550 66 2583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 2550 383 383 1400 2550 1783 2933 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 2550 450 450 1400 2550 1850 3000 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 1400 2633 0\001 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 66 2550 132 2550 225 2550 341 2550 474 2550 617 2550 766 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 766 2483 933 2550 766 2600 766 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 500 2500 IN\001 -# end of FIG file diff --git a/doc/ragel/bmnum.fig b/doc/ragel/bmnum.fig deleted file mode 100644 index f00eec48..00000000 --- a/doc/ragel/bmnum.fig +++ /dev/null @@ -1,38 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: bmnum -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 2550 33 33 33 2550 66 2583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 2550 383 383 1333 2550 1716 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 1333 2633 0\001 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 66 2550 139 2550 237 2550 354 2550 485 2550 624 2550 766 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 766 2483 933 2550 766 2600 766 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 500 2500 IN\001 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3066 2550 383 383 3066 2550 3449 2933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3066 2550 450 450 3066 2550 3516 3000 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 3066 2633 1\001 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 1733 2550 1838 2550 1951 2550 2070 2550 2192 2550 2314 2550 2433 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 2433 2483 2600 2550 2433 2600 2433 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2166 2500 42\001 -# end of FIG file diff --git a/doc/ragel/bmor.fig b/doc/ragel/bmor.fig deleted file mode 100644 index 093c4f2b..00000000 --- a/doc/ragel/bmor.fig +++ /dev/null @@ -1,38 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: bmor -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 2550 33 33 33 2550 66 2583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 2550 383 383 1333 2550 1716 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 1333 2633 0\001 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 66 2550 139 2550 237 2550 354 2550 485 2550 624 2550 766 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 766 2483 933 2550 766 2600 766 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 500 2500 IN\001 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3933 2550 383 383 3933 2550 4316 2933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3933 2550 450 450 3933 2550 4383 3000 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 3933 2633 1\001 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 1733 2550 1960 2550 2217 2550 2491 2550 2771 2550 3045 2550 3300 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 3300 2483 3466 2550 3300 2600 3300 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2600 2500 'e', 'h', 'l', 'o'\001 -# end of FIG file diff --git a/doc/ragel/bmrange.fig b/doc/ragel/bmrange.fig deleted file mode 100644 index 7c85d8ef..00000000 --- a/doc/ragel/bmrange.fig +++ /dev/null @@ -1,38 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: bmrange -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 2550 33 33 33 2550 66 2583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 2550 383 383 1333 2550 1716 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 1333 2633 0\001 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 66 2550 139 2550 237 2550 354 2550 485 2550 624 2550 766 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 766 2483 933 2550 766 2600 766 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 500 2500 IN\001 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3333 2550 383 383 3333 2550 3716 2933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3333 2550 450 450 3333 2550 3783 3000 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 3333 2633 1\001 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 1733 2550 1881 2550 2039 2550 2204 2550 2371 2550 2538 2550 2700 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 2700 2483 2866 2550 2700 2600 2700 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2300 2500 'a'..'z'\001 -# end of FIG file diff --git a/doc/ragel/bmregex.fig b/doc/ragel/bmregex.fig deleted file mode 100644 index 881f534d..00000000 --- a/doc/ragel/bmregex.fig +++ /dev/null @@ -1,109 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: bmregex -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3850 33 33 33 3850 66 3883 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3850 383 383 1333 3850 1716 4233 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6866 3850 383 383 6866 3850 7249 4233 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6866 3850 450 450 6866 3850 7316 4300 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4866 3850 383 383 4866 3850 5249 4233 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2933 3850 383 383 2933 3850 3316 4233 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3783 933 3850 766 3900 766 3783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6583 3350 6550 3516 6483 3350 6583 3350 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5333 4166 5200 4050 5383 4066 5333 4166 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2366 3783 2533 3850 2366 3900 2366 3783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2700 3400 2666 3566 2600 3400 2700 3400 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4300 3783 4466 3850 4300 3900 4300 3783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6233 3783 6400 3850 6233 3883 6233 3783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4633 3400 4600 3566 4533 3400 4633 3400 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - -90 2835 7515 2835 7515 4365 -90 4365 -90 2835 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3850 139 3850 237 3850 354 3850 485 3850 624 3850 - 766 3850 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7183 3516 7208 3410 7201 3312 7162 3227 7093 3159 6994 3115 - 6866 3100 6772 3108 6691 3131 6625 3168 6575 3218 6544 3279 - 6533 3350 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 6466 4066 6407 4091 6345 4115 6283 4137 6220 4156 6159 4172 - 6100 4183 6001 4198 5917 4209 5839 4214 5760 4212 5672 4203 - 5566 4183 5533 4174 5499 4166 5464 4156 5428 4145 5390 4132 - 5350 4116 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 3850 1834 3850 1938 3850 2043 3850 2150 3850 2258 3850 - 2366 3850 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3200 3566 3220 3467 3216 3374 3185 3291 3128 3225 3044 3182 - 2933 3166 2849 3174 2782 3197 2729 3233 2690 3280 2664 3336 - 2650 3400 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3333 3850 3481 3850 3639 3850 3804 3850 3971 3850 4138 3850 - 4300 3850 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 5266 3850 5316 3848 5366 3845 5416 3841 5466 3837 5516 3834 - 5566 3833 5676 3833 5764 3833 5839 3833 5913 3833 5996 3833 - 6100 3833 6123 3833 6145 3833 6166 3833 6187 3833 6209 3833 - 6233 3833 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5133 3566 5154 3467 5149 3374 5118 3291 5061 3225 4977 3182 - 4866 3166 4783 3174 4715 3197 4662 3233 4623 3280 4597 3336 - 4583 3400 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3933 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3800 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 6866 3933 3\001 -4 1 0 0 0 0 14 0.0000 2 165 540 6866 3050 '1'..'3'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4866 3933 2\001 -4 1 0 0 0 0 14 0.0000 2 150 465 5833 4116 DEF\001 -4 1 0 0 0 0 14 0.0000 2 165 120 2933 3933 1\001 -4 1 0 0 0 0 14 0.0000 2 150 195 2133 3800 'a'\001 -4 1 0 0 0 0 14 0.0000 2 150 210 2933 3116 'b'\001 -4 1 0 0 0 0 14 0.0000 2 150 510 3900 3800 'c'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 165 540 5833 3783 '1'..'3'\001 -4 1 0 0 0 0 14 0.0000 2 150 465 4866 3116 DEF\001 diff --git a/doc/ragel/comments1.fig b/doc/ragel/comments1.fig deleted file mode 100644 index 066de168..00000000 --- a/doc/ragel/comments1.fig +++ /dev/null @@ -1,167 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: comments1 -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 5833 33 33 33 5833 66 5866 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 5833 383 383 1333 5833 1716 6216 -# 5 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 12833 5216 383 383 12833 5216 13216 5599 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 12833 5216 450 450 12833 5216 13283 5666 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4533 5833 383 383 4533 5833 4916 6216 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 7383 5900 383 383 7383 5900 7766 6283 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2900 5833 383 383 2900 5833 3283 6216 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 10333 6300 383 383 10333 6300 10716 6683 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 5766 933 5833 766 5883 766 5766 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5033 5583 4866 5616 4983 5483 5033 5583 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7933 5766 7750 5766 7900 5666 7933 5766 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2333 5766 2500 5833 2333 5883 2333 5766 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3966 5766 4133 5833 3966 5883 3966 5766 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4300 5383 4266 5550 4200 5383 4300 5383 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6816 5800 6983 5866 6816 5900 6816 5800 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5000 6150 4866 6033 5050 6050 5000 6150 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7150 5450 7116 5616 7050 5450 7150 5450 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 9816 6066 9966 6166 9783 6166 9816 6066 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 12300 5516 12466 5483 12350 5616 12300 5516 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4800 6316 4683 6183 4850 6216 4800 6316 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7833 6250 7716 6116 7883 6150 7833 6250 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 13410 4365 -45 4365 -45 6840 13410 6840 13410 4365 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 5833 139 5833 237 5833 354 5833 485 5833 624 5833 - 766 5833 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 5 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 12383 5100 11763 4966 10941 4822 9975 4700 8919 4633 7830 4655 - 6766 4800 6447 4883 6127 4993 5816 5122 5522 5261 5252 5401 - 5016 5533 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 5 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 12366 5216 11883 5230 11275 5256 10577 5302 9824 5370 9053 5468 - 8300 5600 8233 5616 8167 5633 8102 5652 8038 5671 7976 5692 - 7916 5716 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 5833 1827 5833 1925 5833 2027 5833 2129 5833 2232 5833 - 2333 5833 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3300 5833 3403 5833 3513 5833 3627 5833 3741 5833 3855 5833 - 3966 5833 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4800 5550 4820 5450 4816 5357 4785 5275 4728 5209 4644 5165 - 4533 5150 4449 5158 4382 5180 4329 5216 4290 5263 4264 5319 - 4250 5383 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 4933 5833 4983 5832 5033 5829 5083 5825 5133 5820 5183 5817 - 5233 5816 5478 5815 5679 5812 5856 5810 6032 5809 6228 5810 - 6466 5816 6525 5823 6583 5829 6641 5833 6700 5837 6758 5842 - 6816 5850 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 3 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 7016 6033 6930 6065 6840 6093 6747 6118 6653 6139 6559 6155 - 6466 6166 6228 6204 6032 6233 5856 6247 5679 6244 5478 6218 - 5233 6166 5199 6158 5166 6149 5131 6139 5095 6128 5057 6115 - 5016 6100 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7650 5616 7670 5517 7666 5424 7635 5341 7578 5275 7494 5232 - 7383 5216 7299 5224 7232 5247 7179 5283 7140 5330 7114 5386 - 7100 5450 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7783 5900 8021 5909 8296 5924 8595 5943 8909 5970 9225 6005 - 9533 6050 9576 6059 9620 6070 9666 6083 9712 6095 9757 6107 - 9800 6116 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 4 -> 5 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 10716 6200 10908 6150 11125 6085 11360 6008 11601 5919 11840 5821 - 12066 5716 12108 5691 12149 5666 12191 5641 12233 5616 12274 5591 - 12316 5566 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 4 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 10000 6516 9933 6529 9864 6537 9791 6541 9713 6546 9628 6553 - 9533 6566 8997 6655 8556 6719 8162 6758 7765 6769 7316 6750 - 6766 6700 6483 6658 6150 6602 5793 6533 5438 6453 5109 6363 - 4833 6266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 4 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 9950 6383 9722 6416 9462 6446 9181 6464 8887 6464 8590 6440 - 8300 6383 8225 6363 8150 6339 8077 6310 8004 6277 7934 6240 - 7866 6200 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 5916 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 5783 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 12833 5300 5\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4533 5916 2\001 -4 1 0 0 0 0 14 0.0000 2 150 1230 8916 4600 DEF / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 120 7383 5983 3\001 -4 1 0 0 0 0 14 0.0000 2 150 975 10333 5266 '*' / comm\001 -4 1 0 0 0 0 14 0.0000 2 165 120 2900 5916 1\001 -4 1 0 0 0 0 14 0.0000 2 150 150 2116 5783 '/'\001 -4 1 0 0 0 0 14 0.0000 2 90 210 3716 5783 '*'\001 -4 1 0 0 0 0 14 0.0000 2 150 1230 4533 5100 DEF / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 975 5850 5766 '*' / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 1230 5850 6116 DEF / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 975 7383 5166 '*' / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 120 10333 6383 4\001 -4 1 0 0 0 0 14 0.0000 2 150 915 8916 5883 '/' / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 915 11600 5666 ' ' / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 1230 7383 6650 DEF / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 975 8916 6333 '*' / comm\001 diff --git a/doc/ragel/comments2.fig b/doc/ragel/comments2.fig deleted file mode 100644 index 3417edc2..00000000 --- a/doc/ragel/comments2.fig +++ /dev/null @@ -1,110 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: comments2 -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3716 33 33 33 3716 66 3749 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3716 383 383 1333 3716 1716 4099 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8800 3716 383 383 8800 3716 9183 4099 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8800 3716 450 450 8800 3716 9250 4166 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2900 3716 383 383 2900 3716 3283 4099 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4533 3716 383 383 4533 3716 4916 4099 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 7166 3716 383 383 7166 3716 7549 4099 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3650 933 3716 766 3766 766 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2333 3650 2500 3716 2333 3766 2333 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3966 3650 4133 3716 3966 3766 3966 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4300 3266 4266 3433 4200 3266 4300 3266 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6600 3650 6766 3716 6600 3750 6600 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8166 3650 8333 3716 8166 3766 8166 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5000 4033 4866 3916 5050 3933 5000 4033 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6933 3266 6900 3433 6833 3266 6933 3266 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 9315 2745 -45 2745 -45 4185 9315 4185 9315 2745 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3716 139 3716 237 3716 354 3716 485 3716 624 3716 - 766 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 3716 1827 3716 1925 3716 2027 3716 2129 3716 2232 3716 - 2333 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3300 3716 3403 3716 3513 3716 3627 3716 3741 3716 3855 3716 - 3966 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4800 3433 4820 3334 4816 3240 4785 3158 4728 3092 4644 3049 - 4533 3033 4449 3041 4382 3064 4329 3100 4290 3146 4264 3203 - 4250 3266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 4933 3716 4983 3715 5033 3712 5083 3708 5133 3704 5183 3701 - 5233 3700 5478 3700 5679 3700 5856 3700 6032 3700 6228 3700 - 6466 3700 6490 3700 6512 3700 6533 3700 6554 3700 6576 3700 - 6600 3700 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 7566 3716 7660 3716 7759 3716 7860 3716 7962 3716 8065 3716 - 8166 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 3 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 6833 3916 6774 3948 6716 3977 6656 4002 6595 4022 6532 4038 - 6466 4050 6228 4098 6032 4127 5856 4137 5679 4127 5478 4098 - 5233 4050 5199 4041 5166 4032 5131 4022 5095 4011 5057 3998 - 5016 3983 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7433 3433 7454 3334 7449 3240 7418 3158 7361 3092 7277 3049 - 7166 3033 7083 3041 7015 3064 6962 3100 6923 3146 6897 3203 - 6883 3266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3800 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3666 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 8800 3800 4\001 -4 1 0 0 0 0 14 0.0000 2 165 120 2900 3800 1\001 -4 1 0 0 0 0 14 0.0000 2 150 150 2116 3666 '/'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4533 3800 2\001 -4 1 0 0 0 0 14 0.0000 2 90 210 3716 3666 '*'\001 -4 1 0 0 0 0 14 0.0000 2 150 1230 4533 2983 DEF / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 120 7166 3800 3\001 -4 1 0 0 0 0 14 0.0000 2 150 975 5850 3650 '*' / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 150 7950 3666 '/'\001 -4 1 0 0 0 0 14 0.0000 2 150 1230 5850 3983 DEF / comm\001 -4 1 0 0 0 0 14 0.0000 2 150 975 7166 2983 '*' / comm\001 diff --git a/doc/ragel/conds1.fig b/doc/ragel/conds1.fig deleted file mode 100644 index 3436e89c..00000000 --- a/doc/ragel/conds1.fig +++ /dev/null @@ -1,96 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: conds1 -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 4650 33 33 33 4650 66 4683 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 4650 383 383 1400 4650 1783 5033 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 4650 450 450 1400 4650 1850 5100 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3233 4650 383 383 3233 4650 3616 5033 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8466 4650 383 383 8466 4650 8849 5033 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8466 4650 450 450 8466 4650 8916 5100 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5500 5683 383 383 5500 5683 5883 6066 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 4583 933 4650 766 4700 766 4583 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2666 4583 2833 4650 2666 4700 2666 4583 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8183 4150 8150 4316 8083 4150 8183 4150 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3783 4683 3616 4633 3783 4566 3783 4683 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5016 5400 5150 5516 4966 5500 5016 5400 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7850 4800 8033 4800 7883 4900 7850 4800 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5266 5233 5233 5400 5166 5233 5266 5233 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 9360 3645 -90 3645 -90 6165 9360 6165 9360 3645 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 4650 132 4650 225 4650 341 4650 474 4650 617 4650 - 766 4650 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1866 4650 1995 4650 2129 4650 2266 4650 2403 4650 2537 4650 - 2666 4650 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 8783 4316 8808 4210 8801 4112 8762 4027 8693 3959 8594 3915 - 8466 3900 8372 3908 8291 3931 8225 3968 8175 4018 8144 4079 - 8133 4150 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 8016 4633 7959 4632 7904 4629 7852 4625 7800 4620 7750 4617 - 7700 4616 7136 4601 6679 4589 6272 4581 5865 4577 5403 4577 - 4833 4583 4661 4591 4483 4600 4302 4608 4122 4616 3947 4625 - 3783 4633 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3600 4816 3800 4908 4029 5014 4275 5127 4525 5241 4771 5351 - 5000 5450 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 5866 5550 6147 5455 6477 5342 6835 5218 7200 5090 7550 4965 - 7866 4850 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5766 5400 5787 5300 5782 5207 5752 5125 5695 5059 5611 5015 - 5500 5000 5416 5008 5348 5030 5295 5066 5256 5113 5230 5169 - 5216 5233 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1400 4733 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 4600 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3233 4733 1\001 -4 1 0 0 0 0 14 0.0000 2 165 360 2350 4600 100\001 -4 1 0 0 0 0 14 0.0000 2 150 120 8466 4733 3\001 -4 1 0 0 0 0 14 0.0000 2 210 1590 8466 3850 97..122(test_len)\001 -4 1 0 0 0 0 14 0.0000 2 210 1305 5500 4533 100(!test_len)\001 -4 1 0 0 0 0 14 0.0000 2 150 120 5500 5766 2\001 -4 1 0 0 0 0 14 0.0000 2 150 600 4233 4966 48..57\001 -4 1 0 0 0 0 14 0.0000 2 180 1245 7083 4900 58 / rec_num\001 -4 1 0 0 0 0 14 0.0000 2 150 600 5500 4950 48..57\001 diff --git a/doc/ragel/conds2.fig b/doc/ragel/conds2.fig deleted file mode 100644 index d5a55574..00000000 --- a/doc/ragel/conds2.fig +++ /dev/null @@ -1,107 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: conds2 -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 4350 33 33 33 4350 66 4383 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 4350 383 383 1333 4350 1716 4733 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 11633 5016 383 383 11633 5016 12016 5399 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 11633 5016 450 450 11633 5016 12083 5466 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 9183 4433 383 383 9183 4433 9566 4816 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4766 5383 383 383 4766 5383 5149 5766 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 4283 933 4350 766 4400 766 4283 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8616 4316 8783 4383 8616 4416 8616 4316 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4233 5166 4383 5266 4200 5266 4233 5166 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 11033 4816 11183 4916 11000 4916 11033 4816 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8950 3983 8916 4150 8850 3983 8950 3983 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 11016 5050 11183 5083 11016 5150 11016 5050 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8633 4500 8800 4516 8650 4600 8633 4500 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4533 4933 4500 5100 4433 4933 4533 4933 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 12285 3465 -135 3465 -135 5895 12285 5895 12285 3465 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 4350 139 4350 237 4350 354 4350 485 4350 624 4350 - 766 4350 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 25 - 1716 4283 1773 4282 1828 4278 1881 4272 1932 4266 1983 4258 - 2033 4250 2352 4232 2611 4227 2839 4231 3066 4238 3321 4246 - 3633 4250 4551 4259 5297 4260 5956 4260 6613 4267 7355 4288 - 8266 4333 8325 4340 8383 4345 8441 4350 8499 4354 8558 4359 - 8616 4366 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 0.000 -# 0 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1716 4466 2062 4570 2479 4694 2935 4829 3398 4966 3835 5098 - 4216 5216 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 9566 4516 9774 4564 10009 4622 10260 4685 10518 4750 10773 4811 - 11016 4866 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 9450 4150 9470 4050 9466 3957 9435 3875 9378 3809 9294 3765 - 9183 3750 9099 3758 9032 3780 8979 3816 8940 3863 8914 3919 - 8900 3983 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5166 5383 5685 5380 6364 5370 7158 5352 8024 5324 8919 5284 - 9800 5233 10010 5215 10222 5195 10433 5172 10638 5149 10833 5124 - 11016 5100 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 5150 5300 5623 5200 6208 5075 6854 4937 7508 4796 8118 4663 - 8633 4550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5033 5100 5054 5000 5049 4907 5018 4825 4961 4759 4877 4715 - 4766 4700 4683 4708 4615 4730 4562 4766 4523 4813 4497 4869 - 4483 4933 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 4433 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 4300 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 11633 5100 2\001 -4 1 0 0 0 0 14 0.0000 2 165 120 9183 4516 1\001 -4 1 0 0 0 0 14 0.0000 2 210 1665 4766 4216 97..122(!test_len)\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4766 5466 3\001 -4 1 0 0 0 0 14 0.0000 2 210 1590 2833 4533 97..122(test_len)\001 -4 1 0 0 0 0 14 0.0000 2 165 780 10483 4633 10 / two\001 -4 1 0 0 0 0 14 0.0000 2 195 1440 9183 3700 48..57, 97..122\001 -4 1 0 0 0 0 14 0.0000 2 195 1245 9183 5183 10 / one, two\001 -4 1 0 0 0 0 14 0.0000 2 210 2385 7083 4616 48..57, 97..122(!test_len)\001 -4 1 0 0 0 0 14 0.0000 2 210 1590 4766 4650 97..122(test_len)\001 diff --git a/doc/ragel/dropdown.fig b/doc/ragel/dropdown.fig deleted file mode 100644 index 29fefec5..00000000 --- a/doc/ragel/dropdown.fig +++ /dev/null @@ -1,107 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: dropdown -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3950 33 33 33 3950 66 3983 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3950 383 383 1333 3950 1716 4333 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 9266 4133 383 383 9266 4133 9649 4516 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 9266 4133 450 450 9266 4133 9716 4583 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5383 3550 383 383 5383 3550 5766 3933 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 7566 4133 383 383 7566 4133 7949 4516 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3883 933 3950 766 4000 766 3883 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1100 3500 1066 3666 1000 3500 1100 3500 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4816 3433 4983 3500 4816 3533 4816 3433 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1883 4066 1716 4000 1883 3966 1883 4066 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7033 3933 7183 4033 7000 4033 7033 3933 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8633 4066 8800 4133 8633 4183 8633 4066 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1833 4216 1666 4150 1833 4116 1833 4216 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7333 3683 7300 3850 7233 3683 7333 3683 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - -90 2970 9765 2970 9765 4680 -90 4680 -90 2970 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3950 139 3950 237 3950 354 3950 485 3950 624 3950 - 766 3950 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1600 3666 1620 3567 1616 3474 1585 3391 1528 3325 1444 3282 - 1333 3266 1249 3274 1182 3297 1129 3333 1090 3380 1064 3436 - 1050 3500 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1666 3750 1726 3725 1787 3700 1850 3677 1912 3654 1973 3634 - 2033 3616 2528 3528 3036 3474 3537 3450 4013 3447 4446 3460 - 4816 3483 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5033 3716 4892 3768 4738 3823 4575 3877 4406 3926 4235 3968 - 4066 4000 3689 4046 3300 4070 2912 4077 2538 4067 2190 4046 - 1883 4016 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 5766 3650 5954 3695 6161 3747 6379 3804 6600 3863 6815 3923 - 7016 3983 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 7966 4133 8069 4133 8176 4133 8287 4133 8401 4133 8516 4133 - 8633 4133 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 7183 4233 7062 4258 6935 4282 6804 4304 6669 4323 6534 4339 - 6400 4350 5539 4415 4838 4443 4216 4433 3595 4384 2893 4295 - 2033 4166 1999 4166 1966 4166 1933 4166 1899 4166 1866 4166 - 1833 4166 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7833 3850 7854 3750 7849 3657 7818 3575 7761 3509 7677 3465 - 7566 3450 7483 3458 7415 3480 7362 3516 7323 3563 7297 3619 - 7283 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 4033 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3900 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 9266 4216 3\001 -4 1 0 0 0 0 14 0.0000 2 150 1170 1333 3216 DEF / bchar\001 -4 1 0 0 0 0 14 0.0000 2 165 120 5383 3633 1\001 -4 1 0 0 0 0 14 0.0000 2 195 165 3050 3416 ']'\001 -4 1 0 0 0 0 14 0.0000 2 195 2055 3050 3950 DEF / bbrack1, bchar\001 -4 1 0 0 0 0 14 0.0000 2 150 120 7566 4216 2\001 -4 1 0 0 0 0 14 0.0000 2 195 165 6783 3883 ']'\001 -4 1 0 0 0 0 14 0.0000 2 150 225 8383 4083 '>'\001 -4 1 0 0 0 0 14 0.0000 2 195 2055 5383 4300 DEF / bbrack2, bchar\001 -4 1 0 0 0 0 14 0.0000 2 210 1110 7566 3400 ']' / bbrack1\001 diff --git a/doc/ragel/entryguard.fig b/doc/ragel/entryguard.fig deleted file mode 100644 index c8487169..00000000 --- a/doc/ragel/entryguard.fig +++ /dev/null @@ -1,73 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exstpri -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3550 33 33 33 3550 66 3583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3550 383 383 1333 3550 1716 3933 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6266 3550 383 383 6266 3550 6649 3933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6266 3550 450 450 6266 3550 6716 4000 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2966 3550 383 383 2966 3550 3349 3933 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4533 3550 383 383 4533 3550 4916 3933 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3483 933 3550 766 3600 766 3483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1100 3100 1066 3266 1000 3100 1100 3100 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2400 3483 2566 3550 2400 3600 2400 3483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3966 3483 4133 3550 3966 3600 3966 3483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5633 3483 5800 3550 5633 3600 5633 3483 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - -45 2565 6795 2565 6795 4185 -45 4185 -45 2565 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3550 139 3550 237 3550 354 3550 485 3550 624 3550 - 766 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1600 3266 1620 3167 1616 3074 1585 2991 1528 2925 1444 2882 - 1333 2866 1249 2874 1182 2897 1129 2933 1090 2980 1064 3036 - 1050 3100 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 3550 1837 3550 1946 3550 2060 3550 2175 3550 2289 3550 - 2400 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3366 3550 3460 3550 3559 3550 3660 3550 3762 3550 3865 3550 - 3966 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 4933 3550 5038 3550 5151 3550 5270 3550 5392 3550 5514 3550 - 5633 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3633 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3500 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 6266 3633 3\001 -4 1 0 0 0 0 14 0.0000 2 150 465 1333 2816 DEF\001 -4 1 0 0 0 0 14 0.0000 2 165 120 2966 3633 1\001 -4 1 0 0 0 0 14 0.0000 2 150 225 2150 3500 'F'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4533 3633 2\001 -4 1 0 0 0 0 14 0.0000 2 150 165 3750 3500 'I'\001 -4 1 0 0 0 0 14 0.0000 2 150 270 5366 3500 'N'\001 diff --git a/doc/ragel/exaction.fig b/doc/ragel/exaction.fig deleted file mode 100644 index 9829f063..00000000 --- a/doc/ragel/exaction.fig +++ /dev/null @@ -1,64 +0,0 @@ -#FIG 3.2 -# Generated by Graphviz version 2.12 (Tue Sep 4 16:56:48 UTC 2007) -# For: (thurston) Adrian Thurston,,, -# Title: exaction -# Pages: 1 -Portrait -Center -Inches -Letter -100.00 -Single --2 -1200 2 -0 32 #d3d3d3 -2 3 0 1 7 7 2 0 20 0.0 0 0 0 0 0 5 - 0 2460 0 0 8680 0 8680 2460 0 2460 -# ENTRY -1 1 0 1 0 0 1 0 20 0.000 0 0.0000 120 720 40 -40 120 720 160 680 -# 1 -1 1 0 1 0 7 1 0 -1 0.000 0 0.0000 1640 720 420 -430 1640 720 2060 290 -4 1 0 1 0 0 14.0 0.0000 4 0.0 0.0 1640 800 1\001 -# ENTRY->1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 160 720 247 720 364 720 505 720 662 720 829 720 1000 720 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 1000 650 1200 720 1000 790 1000 650 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 680 600 IN\001 -# 3 -1 1 0 1 0 7 1 0 -1 0.000 0 0.0000 8080 720 422 -430 8080 720 8502 290 -1 1 0 1 0 7 1 0 -1 0.000 0 0.0000 8080 720 500 -510 8080 720 8580 210 -4 1 0 1 0 0 14.0 0.0000 4 0.0 0.0 8080 800 3\001 -# 1->3 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 19 - 2060 620 2121 610 2185 600 2250 590 2315 580 2379 570 2440 560 3383 488 4150 465 4828 480 5504 521 6265 579 7200 640 7229 641 7255 645 7280 650 7305 655 7331 659 7360 660 - 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 7368 590 7560 680 7354 730 7368 590 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 4980 360 '\\n' / A, C, N\001 -# 2 -1 1 0 1 0 7 1 0 -1 0.000 0 0.0000 4980 1960 420 -430 4980 1960 5400 1530 -4 1 0 1 0 0 14.0 0.0000 4 0.0 0.0 4980 2040 2\001 -# 1->2 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 2040 860 2376 985 2767 1133 3188 1293 3613 1454 4019 1607 4380 1740 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 4409 1675 4580 1800 4368 1810 4409 1675 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 3160 920 'a'..'z' / A, B\001 -# 2->3 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 5380 1800 5669 1681 6002 1547 6363 1405 6731 1259 7090 1116 7420 980 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 7389 917 7600 900 7446 1045 7389 917 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 6640 1000 '\\n' / C, N\001 -# 2->2 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 13 - 4580 1780 4432 1645 4368 1509 4390 1383 4499 1278 4695 1206 4980 1180 5220 1199 5401 1250 5523 1328 5586 1423 5592 1530 5540 1640 - 0 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 5577 1701 5380 1780 5484 1596 5577 1701 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 4980 1060 'a'..'z' / B\001 -# end of FIG file diff --git a/doc/ragel/exallact.fig b/doc/ragel/exallact.fig deleted file mode 100644 index 593ffd32..00000000 --- a/doc/ragel/exallact.fig +++ /dev/null @@ -1,48 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exallact -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 2550 33 33 33 2550 66 2583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 2550 383 383 1333 2550 1716 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 1333 2633 0\001 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 66 2550 139 2550 237 2550 354 2550 485 2550 624 2550 766 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 766 2483 933 2550 766 2600 766 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 500 2500 IN\001 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5733 2550 383 383 5733 2550 6116 2933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5733 2550 450 450 5733 2550 6183 3000 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 5733 2633 2\001 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3366 2550 383 383 3366 2550 3749 2933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 3366 2633 1\001 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 1733 2550 1893 2550 2069 2550 2254 2550 2441 2550 2626 2550 2800 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 2800 2483 2966 2550 2800 2600 2800 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2350 2500 'm' / A\001 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 3766 2550 3962 2550 4179 2550 4408 2550 4643 2550 4876 2550 5100 2550 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 5100 2483 5266 2550 5100 2600 5100 2483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 4516 2500 '1'..'2' / A\001 -# end of FIG file diff --git a/doc/ragel/exconcat.fig b/doc/ragel/exconcat.fig deleted file mode 100644 index e6341398..00000000 --- a/doc/ragel/exconcat.fig +++ /dev/null @@ -1,217 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exconcat -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 10216 33 33 33 10216 66 10249 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 10216 383 383 1333 10216 1716 10599 -# 5 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8466 9950 383 383 8466 9950 8849 10333 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8466 9950 450 450 8466 9950 8916 10400 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3000 9283 383 383 3000 9283 3383 9666 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 10400 9283 383 383 10400 9283 10783 9666 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4666 8466 383 383 4666 8466 5049 8849 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6533 9000 383 383 6533 9000 6916 9383 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 10150 933 10216 766 10266 766 10150 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1866 10400 1716 10316 1883 10300 1866 10400 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3550 9400 3383 9333 3550 9300 3550 9400 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 9850 9416 10033 9416 9883 9516 9850 9416 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1100 9766 1066 9933 1000 9766 1100 9766 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2566 9650 2733 9583 2650 9733 2566 9650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 10116 9750 10250 9633 10216 9800 10116 9750 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1750 9833 1583 9916 1666 9750 1750 9833 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 10250 8750 10283 8916 10150 8800 10250 8750 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4150 8666 4316 8633 4200 8766 4150 8666 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1400 10783 1383 10600 1500 10733 1400 10783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 10166 8833 10133 9000 10066 8833 10166 8833 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1500 9716 1366 9833 1400 9666 1500 9716 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 9916 8983 10066 9083 9883 9083 9916 8983 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6000 8800 6150 8900 5966 8900 6000 8800 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7916 9650 8050 9766 7866 9750 7916 9650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 9850 9183 10016 9250 9850 9283 9850 9183 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 11160 7065 -45 7065 -45 12015 11160 12015 11160 7065 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 10216 139 10216 237 10216 354 10216 485 10216 624 10216 - 766 10216 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 5 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 8050 10133 7841 10211 7604 10290 7347 10364 7078 10425 6804 10467 - 6533 10483 5044 10483 4046 10483 3441 10483 3130 10483 3016 10483 - 3000 10483 2806 10478 2610 10463 2416 10441 2228 10414 2049 10383 - 1883 10350 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 5 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 8000 9900 7398 9822 6642 9727 5806 9625 4962 9522 4186 9427 - 3550 9350 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 5 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 8900 9800 9049 9747 9209 9691 9377 9633 9545 9575 9710 9519 - 9866 9466 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1600 9933 1620 9834 1616 9740 1585 9658 1528 9592 1444 9549 - 1333 9533 1249 9541 1182 9564 1129 9600 1090 9646 1064 9703 - 1050 9766 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1716 10150 1810 10122 1908 10089 2008 10052 2108 10010 2205 9965 - 2300 9916 2356 9889 2411 9856 2462 9820 2511 9782 2556 9741 - 2600 9700 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 1533 10550 1735 10781 1935 10961 2147 11093 2386 11183 2665 11234 - 3000 11250 3025 11250 3202 11250 3683 11250 4619 11250 6163 11250 - 8466 11250 8921 11199 9270 11054 9541 10829 9762 10533 9962 10181 - 10166 9783 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 2 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 2616 9366 2522 9393 2424 9422 2325 9456 2225 9493 2127 9536 - 2033 9583 1963 9623 1902 9661 1847 9697 1797 9732 1748 9766 - 1700 9800 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 2 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 25 - 3250 8983 3275 8967 3300 8953 3325 8937 3350 8919 3375 8896 - 3400 8866 3659 8554 3824 8222 3952 7906 4097 7638 4317 7452 - 4666 7383 4684 7383 4807 7383 5141 7383 5792 7383 6865 7383 - 8466 7383 8911 7429 9260 7560 9539 7768 9772 8045 9984 8380 - 10200 8766 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3350 9116 3472 9055 3606 8990 3745 8922 3888 8853 4029 8784 - 4166 8716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 31 - 10366 9666 10365 9691 10362 9715 10358 9737 10354 9756 10351 9772 - 10350 9783 10276 10083 10211 10331 10137 10545 10038 10746 9898 10952 - 9700 11183 9509 11404 9339 11583 9170 11722 8982 11821 8754 11880 - 8466 11900 6163 11900 4619 11900 3683 11900 3202 11900 3025 11900 - 3000 11900 2609 11865 2294 11764 2037 11600 1822 11374 1631 11089 - 1450 10750 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 10666 9000 10687 8900 10682 8807 10652 8725 10595 8659 10511 8615 - 10400 8600 10316 8608 10248 8630 10195 8666 10156 8713 10130 8769 - 10116 8833 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4266 8466 4030 8471 3764 8488 3477 8520 3180 8572 2884 8647 - 2600 8750 2326 8880 2098 8999 1906 9122 1740 9267 1591 9448 - 1450 9683 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 31 - 5050 8400 5107 8391 5161 8383 5214 8375 5266 8366 5316 8358 - 5366 8350 5462 8344 5539 8342 5606 8343 5671 8346 5744 8348 - 5833 8350 6455 8390 6959 8432 7402 8483 7840 8551 8332 8643 - 8933 8766 9088 8804 9213 8837 9322 8868 9430 8901 9551 8938 - 9700 8983 9740 8991 9777 9000 9812 9008 9844 9016 9873 9025 - 9900 9033 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 5050 8566 5190 8609 5343 8654 5504 8702 5667 8750 5828 8800 - 5983 8850 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 4 -> 5 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 6866 9200 6926 9233 6987 9266 7050 9297 7112 9328 7173 9357 - 7233 9383 7342 9434 7454 9487 7566 9541 7679 9595 7790 9648 - 7900 9700 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 4 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 6933 9016 7047 9024 7172 9032 7304 9039 7438 9045 7571 9048 - 7700 9050 8099 9080 8422 9108 8706 9133 8988 9158 9307 9185 - 9700 9216 9725 9217 9750 9220 9775 9225 9800 9229 9825 9232 - 9850 9233 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 10300 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 10166 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 8466 10033 5\001 -4 1 0 0 0 0 14 0.0000 2 165 240 4666 10433 10\001 -4 1 0 0 0 0 14 0.0000 2 150 120 3000 9366 2\001 -4 1 0 0 0 0 14 0.0000 2 150 240 5600 9550 'E'\001 -4 1 0 0 0 0 14 0.0000 2 165 120 10400 9366 1\001 -4 1 0 0 0 0 14 0.0000 2 150 465 9466 9500 DEF\001 -4 1 0 0 0 0 14 0.0000 2 165 240 1333 9483 10\001 -4 1 0 0 0 0 14 0.0000 2 150 240 2166 9866 'E'\001 -4 1 0 0 0 0 14 0.0000 2 150 465 5600 11200 DEF\001 -4 1 0 0 0 0 14 0.0000 2 165 240 2166 9450 10\001 -4 1 0 0 0 0 14 0.0000 2 150 465 6533 7333 DEF\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4666 8550 3\001 -4 1 0 0 0 0 14 0.0000 2 150 270 3833 8800 'O'\001 -4 1 0 0 0 0 14 0.0000 2 165 240 5600 11850 10\001 -4 1 0 0 0 0 14 0.0000 2 150 465 10400 8550 DEF\001 -4 1 0 0 0 0 14 0.0000 2 165 240 3000 8516 10\001 -4 1 0 0 0 0 14 0.0000 2 150 465 7466 8433 DEF\001 -4 1 0 0 0 0 14 0.0000 2 150 120 6533 9083 4\001 -4 1 0 0 0 0 14 0.0000 2 150 225 5600 8633 'F'\001 -4 1 0 0 0 0 14 0.0000 2 165 240 7466 9333 10\001 -4 1 0 0 0 0 14 0.0000 2 150 465 8466 9050 DEF\001 diff --git a/doc/ragel/exdoneact.fig b/doc/ragel/exdoneact.fig deleted file mode 100644 index 3930e5a3..00000000 --- a/doc/ragel/exdoneact.fig +++ /dev/null @@ -1,51 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exdoneact -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3550 33 33 33 3550 66 3583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3550 383 383 1333 3550 1716 3933 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3333 3550 383 383 3333 3550 3716 3933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3333 3550 450 450 3333 3550 3783 4000 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3483 933 3550 766 3600 766 3483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2700 3483 2866 3550 2700 3600 2700 3483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1100 3100 1066 3266 1000 3100 1100 3100 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - -270 2610 3915 2610 3915 4140 -270 4140 -270 2610 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3550 139 3550 237 3550 354 3550 485 3550 624 3550 - 766 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 3550 1881 3550 2039 3550 2204 3550 2371 3550 2538 3550 - 2700 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1600 3266 1620 3167 1616 3074 1585 2991 1528 2925 1444 2882 - 1333 2866 1249 2874 1182 2897 1129 2933 1090 2980 1064 3036 - 1050 3100 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3633 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3500 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3333 3633 1\001 -4 1 0 0 0 0 14 0.0000 2 150 510 2300 3500 ' ' / A\001 -4 1 0 0 0 0 14 0.0000 2 150 510 1333 2816 'a'..'z'\001 diff --git a/doc/ragel/exinter.fig b/doc/ragel/exinter.fig deleted file mode 100644 index cc802f64..00000000 --- a/doc/ragel/exinter.fig +++ /dev/null @@ -1,75 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exinter -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3816 33 33 33 3816 66 3849 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 3816 383 383 1400 3816 1783 4199 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 3816 450 450 1400 3816 1850 4266 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 1400 3900 0\001 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 66 3816 132 3816 225 3816 341 3816 474 3816 617 3816 766 3816 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 766 3750 933 3816 766 3866 766 3750 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 500 3766 IN\001 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3666 3266 383 383 3666 3266 4049 3649 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 3666 3350 1\001 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 1850 3700 2044 3654 2256 3603 2477 3550 2699 3496 2915 3445 3116 3400 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 3116 3350 3283 3366 3133 3450 3116 3350 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2566 3416 ' ', 'a'..'z'\001 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5866 3216 383 383 5866 3216 6249 3599 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 5866 3300 2\001 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 4066 3250 4252 3248 4456 3245 4670 3241 4887 3237 5099 3234 5300 3233 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 5300 3166 5466 3233 5300 3283 5300 3166 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 4766 3200 ' ', 'a'..'z'\001 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8066 3300 383 383 8066 3300 8449 3683 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 8066 3383 3\001 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 6266 3233 6452 3241 6656 3249 6870 3258 7087 3266 7299 3274 7500 3283 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 7500 3216 7666 3283 7500 3333 7500 3216 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 6966 3216 ' ', 'a'..'z'\001 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 10266 3816 383 383 10266 3816 10649 4199 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 10266 3900 4\001 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 8450 3383 8637 3428 8845 3479 9064 3533 9288 3587 9508 3637 9716 3683 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 9733 3633 9883 3716 9716 3733 9733 3633 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 9166 3433 ' ', 'a'..'z'\001 -# 4 -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 19 - 9883 3916 9643 3969 9364 4025 9056 4079 8730 4124 8396 4155 8066 4166 6212 4166 4970 4166 4216 4166 3829 4166 3687 4166 3666 4166 3378 4158 3087 4137 2797 4104 2518 4062 2255 4016 2016 3966 - 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 2000 4016 1850 3933 2016 3916 2000 4016 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 5866 4116 10\001 -# end of FIG file diff --git a/doc/ragel/exnegate.fig b/doc/ragel/exnegate.fig deleted file mode 100644 index 487fda58..00000000 --- a/doc/ragel/exnegate.fig +++ /dev/null @@ -1,52 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exnegate -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3683 33 33 33 3683 66 3716 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 3683 383 383 1400 3683 1783 4066 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 3683 450 450 1400 3683 1850 4133 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4400 3683 383 383 4400 3683 4783 4066 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4400 3683 450 450 4400 3683 4850 4133 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3616 933 3683 766 3733 766 3616 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3766 3616 3933 3683 3766 3733 3766 3616 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4116 3183 4083 3350 4016 3183 4116 3183 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 4950 2655 -90 2655 -90 4230 4950 4230 4950 2655 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3683 132 3683 225 3683 341 3683 474 3683 617 3683 - 766 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1866 3683 2147 3683 2462 3683 2797 3683 3137 3683 3465 3683 - 3766 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4716 3350 4741 3243 4734 3145 4695 3060 4626 2993 4527 2949 - 4400 2933 4305 2941 4224 2964 4158 3002 4108 3051 4077 3112 - 4066 3183 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1400 3766 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3633 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 4400 3766 1\001 -4 1 0 0 0 0 14 0.0000 2 195 1455 2900 3633 -128..'/', ':'..127\001 -4 1 0 0 0 0 14 0.0000 2 150 465 4400 2883 DEF\001 diff --git a/doc/ragel/exoption.fig b/doc/ragel/exoption.fig deleted file mode 100644 index fafc1078..00000000 --- a/doc/ragel/exoption.fig +++ /dev/null @@ -1,84 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exoption -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3683 33 33 33 3683 66 3716 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3683 383 383 1333 3683 1716 4066 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3333 3683 383 383 3333 3683 3716 4066 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3333 3683 450 450 3333 3683 3783 4133 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4966 3683 383 383 4966 3683 5349 4066 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6966 3683 383 383 6966 3683 7349 4066 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6966 3683 450 450 6966 3683 7416 4133 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3616 933 3683 766 3733 766 3616 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3050 3183 3016 3350 2950 3183 3050 3183 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4400 3616 4566 3683 4400 3733 4400 3616 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6683 3183 6650 3350 6583 3183 6683 3183 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2700 3616 2866 3683 2700 3733 2700 3616 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6333 3616 6500 3683 6333 3733 6333 3616 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 7515 2655 -45 2655 -45 4230 7515 4230 7515 2655 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3683 139 3683 237 3683 354 3683 485 3683 624 3683 - 766 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3650 3350 3675 3243 3667 3145 3629 3060 3559 2993 3460 2949 - 3333 2933 3239 2941 3158 2964 3091 3002 3041 3051 3010 3112 - 3000 3183 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3800 3683 3894 3683 3992 3683 4093 3683 4196 3683 4298 3683 - 4400 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7283 3350 7308 3243 7301 3145 7262 3060 7193 2993 7094 2949 - 6966 2933 6872 2941 6791 2964 6725 3002 6675 3051 6644 3112 - 6633 3183 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 3683 1881 3683 2039 3683 2204 3683 2371 3683 2538 3683 - 2700 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 5366 3683 5514 3683 5672 3683 5837 3683 6004 3683 6171 3683 - 6333 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3766 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3633 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3333 3766 1\001 -4 1 0 0 0 0 14 0.0000 2 150 540 3333 2883 '0'..'9'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4966 3766 2\001 -4 1 0 0 0 0 14 0.0000 2 150 150 4183 3633 '.'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 6966 3766 3\001 -4 1 0 0 0 0 14 0.0000 2 150 540 6966 2883 '0'..'9'\001 -4 1 0 0 0 0 14 0.0000 2 150 540 2300 3633 '0'..'9'\001 -4 1 0 0 0 0 14 0.0000 2 150 540 5933 3633 '0'..'9'\001 diff --git a/doc/ragel/exor.fig b/doc/ragel/exor.fig deleted file mode 100644 index 62e0184f..00000000 --- a/doc/ragel/exor.fig +++ /dev/null @@ -1,128 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exor -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 8700 33 33 33 8700 66 8733 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 8700 383 383 1333 8700 1716 9083 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4066 7683 383 383 4066 7683 4449 8066 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4066 7683 450 450 4066 7683 4516 8133 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6133 8700 383 383 6133 8700 6516 9083 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6133 8700 450 450 6133 8700 6583 9150 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6133 7000 383 383 6133 7000 6516 7383 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 9533 7000 383 383 9533 7000 9916 7383 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 9533 7000 450 450 9533 7000 9983 7450 -# 5 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4066 10316 383 383 4066 10316 4449 10699 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4066 10316 450 450 4066 10316 4516 10766 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 8633 933 8700 766 8750 766 8633 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5600 8366 5716 8500 5550 8466 5600 8366 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5583 7116 5766 7116 5616 7216 5583 7116 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5850 8200 5816 8366 5750 8200 5850 8200 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 9250 6500 9216 6666 9150 6500 9250 6500 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3783 9816 3750 9983 3683 9816 3783 9816 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3450 7850 3633 7850 3483 7950 3450 7850 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5500 8633 5666 8700 5500 8750 5500 8633 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3533 9966 3650 10100 3483 10066 3533 9966 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8900 6933 9066 7000 8900 7050 8900 6933 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 10530 5985 -90 5985 -90 10845 10530 10845 10530 5985 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 8700 139 8700 237 8700 354 8700 485 8700 624 8700 - 766 8700 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 4483 7883 4650 7963 4830 8051 5018 8143 5208 8237 5392 8329 - 5566 8416 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 4500 7533 4672 7479 4855 7419 5043 7356 5233 7291 5420 7227 - 5600 7166 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 6450 8366 6475 8260 6467 8162 6429 8077 6359 8009 6260 7965 - 6133 7950 6039 7958 5958 7981 5891 8018 5841 8068 5810 8129 - 5800 8200 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 4 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 9850 6666 9875 6560 9867 6462 9829 6377 9759 6309 9660 6265 - 9533 6250 9439 6258 9358 6281 9291 6318 9241 6368 9210 6429 - 9200 6500 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 5 -> 5 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4383 9983 4408 9877 4401 9779 4362 9693 4293 9626 4194 9582 - 4066 9566 3972 9574 3891 9598 3825 9635 3775 9685 3744 9746 - 3733 9816 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1700 8566 1950 8473 2239 8364 2552 8245 2871 8124 3181 8007 - 3466 7900 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 8700 2226 8700 2850 8700 3547 8700 4260 8700 4930 8700 - 5500 8700 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 5 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1650 8933 1709 8976 1771 9020 1835 9066 1900 9112 1966 9157 - 2033 9200 2280 9349 2535 9496 2791 9639 3041 9775 3280 9901 - 3500 10016 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 6533 7000 6862 7000 7250 7000 7672 7000 8104 7000 8522 7000 - 8900 7000 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 8783 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 8650 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 4066 7766 1\001 -4 1 0 0 0 0 14 0.0000 2 150 120 6133 8783 2\001 -4 1 0 0 0 0 14 0.0000 2 150 540 5100 7966 '0'..'9'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 6133 7083 3\001 -4 1 0 0 0 0 14 0.0000 2 150 210 5100 7200 'x'\001 -4 1 0 0 0 0 14 0.0000 2 150 540 6133 7900 '0'..'9'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 9533 7083 4\001 -4 1 0 0 0 0 14 0.0000 2 180 1875 9533 6200 '0'..'9', 'A'..'F', 'a'..'f'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4066 10400 5\001 -4 1 0 0 0 0 14 0.0000 2 180 1920 4066 9516 '0'..'9', 'A'..'Z', 'a'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 150 210 2666 7916 '0'\001 -4 1 0 0 0 0 14 0.0000 2 165 540 4066 8650 '1'..'9'\001 -4 1 0 0 0 0 14 0.0000 2 180 1260 2666 9100 'A'..'Z', 'a'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 180 1875 7833 6950 '0'..'9', 'A'..'F', 'a'..'f'\001 diff --git a/doc/ragel/exoutact1.fig b/doc/ragel/exoutact1.fig deleted file mode 100644 index 5ebc3322..00000000 --- a/doc/ragel/exoutact1.fig +++ /dev/null @@ -1,62 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exoutact1 -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3550 33 33 33 3550 66 3583 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3550 383 383 1333 3550 1716 3933 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5333 3550 383 383 5333 3550 5716 3933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5333 3550 450 450 5333 3550 5783 4000 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3266 3550 383 383 3266 3550 3649 3933 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3483 933 3550 766 3600 766 3483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2700 3483 2866 3550 2700 3600 2700 3483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4700 3483 4866 3550 4700 3600 4700 3483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3033 3100 3000 3266 2933 3100 3033 3100 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - -135 2610 5895 2610 5895 4140 -135 4140 -135 2610 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3550 139 3550 237 3550 354 3550 485 3550 624 3550 - 766 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 3550 1881 3550 2039 3550 2204 3550 2371 3550 2538 3550 - 2700 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3666 3550 3824 3550 3993 3550 4170 3550 4350 3550 4528 3550 - 4700 3550 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3533 3266 3554 3167 3549 3074 3518 2991 3461 2925 3377 2882 - 3266 2866 3183 2874 3115 2897 3062 2933 3023 2980 2997 3036 - 2983 3100 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3633 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3500 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 5333 3633 2\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3266 3633 1\001 -4 1 0 0 0 0 14 0.0000 2 150 510 2300 3500 'a'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 165 600 4266 3500 10 / A\001 -4 1 0 0 0 0 14 0.0000 2 150 510 3266 2816 'a'..'z'\001 diff --git a/doc/ragel/exoutact2.fig b/doc/ragel/exoutact2.fig deleted file mode 100644 index 7e01a180..00000000 --- a/doc/ragel/exoutact2.fig +++ /dev/null @@ -1,78 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exoutact2 -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3716 33 33 33 3716 66 3749 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3716 383 383 1333 3716 1716 4099 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8500 3716 383 383 8500 3716 8883 4099 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8500 3716 450 450 8500 3716 8950 4166 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4733 3716 383 383 4733 3716 5116 4099 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3650 933 3716 766 3766 766 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4166 3650 4333 3716 4166 3750 4166 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7866 3650 8033 3716 7866 3766 7866 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1800 4033 1666 3916 1850 3933 1800 4033 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4500 3266 4466 3433 4400 3266 4500 3266 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - -135 2745 9090 2745 9090 4320 -135 4320 -135 2745 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3716 139 3716 237 3716 354 3716 485 3716 624 3716 - 766 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 1733 3716 1783 3715 1833 3712 1883 3708 1933 3704 1983 3701 - 2033 3700 2432 3700 2755 3700 3039 3700 3322 3700 3640 3700 - 4033 3700 4057 3700 4079 3700 4100 3700 4120 3700 4142 3700 - 4166 3700 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 5133 3716 5508 3716 5960 3716 6456 3716 6961 3716 7443 3716 - 7866 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 4400 3916 4341 3948 4282 3977 4222 4002 4161 4022 4098 4038 - 4033 4050 3645 4126 3325 4172 3039 4187 2751 4172 2428 4126 - 2033 4050 1999 4041 1966 4032 1931 4022 1895 4011 1857 3998 - 1816 3983 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5000 3433 5020 3334 5016 3240 4985 3158 4928 3092 4844 3049 - 4733 3033 4649 3041 4582 3064 4529 3100 4490 3146 4464 3203 - 4450 3266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3800 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3666 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 8500 3800 2\001 -4 1 0 0 0 0 14 0.0000 2 165 120 4733 3800 1\001 -4 1 0 0 0 0 14 0.0000 2 165 1230 3033 3650 'a'..'z' / lower\001 -4 1 0 0 0 0 14 0.0000 2 195 2325 6583 3666 10 / term_word, newline\001 -4 1 0 0 0 0 14 0.0000 2 210 2010 3033 3983 ' ' / term_word, space\001 -4 1 0 0 0 0 14 0.0000 2 165 1230 4733 2983 'a'..'z' / lower\001 diff --git a/doc/ragel/explus.fig b/doc/ragel/explus.fig deleted file mode 100644 index 81636f01..00000000 --- a/doc/ragel/explus.fig +++ /dev/null @@ -1,51 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: explus -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3683 33 33 33 3683 66 3716 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3683 383 383 1333 3683 1716 4066 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4700 3683 383 383 4700 3683 5083 4066 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4700 3683 450 450 4700 3683 5150 4133 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3616 933 3683 766 3733 766 3616 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4416 3183 4383 3350 4316 3183 4416 3183 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4066 3616 4233 3683 4066 3733 4066 3616 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 5850 2655 -90 2655 -90 4230 5850 4230 5850 2655 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3683 139 3683 237 3683 354 3683 485 3683 624 3683 - 766 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5016 3350 5041 3243 5034 3145 4995 3060 4926 2993 4827 2949 - 4700 2933 4605 2941 4524 2964 4458 3002 4408 3051 4377 3112 - 4366 3183 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 3683 2055 3683 2438 3683 2856 3683 3283 3683 3695 3683 - 4066 3683 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3766 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3633 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 4700 3766 1\001 -4 1 0 0 0 0 14 0.0000 2 180 1920 4700 2883 '0'..'9', 'A'..'Z', 'a'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 180 1920 2983 3633 '0'..'9', 'A'..'Z', 'a'..'z'\001 diff --git a/doc/ragel/exstact.fig b/doc/ragel/exstact.fig deleted file mode 100644 index 849f8ed9..00000000 --- a/doc/ragel/exstact.fig +++ /dev/null @@ -1,64 +0,0 @@ -#FIG 3.2 -# Generated by Graphviz version 2.12 (Tue Sep 4 16:56:48 UTC 2007) -# For: (thurston) Adrian Thurston,,, -# Title: exstact -# Pages: 1 -Portrait -Center -Inches -Letter -100.00 -Single --2 -1200 2 -0 32 #d3d3d3 -2 3 0 1 7 7 2 0 20 0.0 0 0 0 0 0 5 - 0 2340 0 0 6920 0 6920 2340 0 2340 -# ENTRY -1 1 0 1 0 0 1 0 20 0.000 0 0.0000 120 600 40 -40 120 600 160 560 -# 1 -1 1 0 1 0 7 1 0 -1 0.000 0 0.0000 1640 600 420 -430 1640 600 2060 170 -4 1 0 1 0 0 14.0 0.0000 4 0.0 0.0 1640 680 1\001 -# ENTRY->1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 160 600 247 600 364 600 505 600 662 600 829 600 1000 600 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 1000 530 1200 600 1000 670 1000 530 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 680 480 IN\001 -# 3 -1 1 0 1 0 7 1 0 -1 0.000 0 0.0000 6320 600 422 -430 6320 600 6742 170 -1 1 0 1 0 7 1 0 -1 0.000 0 0.0000 6320 600 500 -510 6320 600 6820 90 -4 1 0 1 0 0 14.0 0.0000 4 0.0 0.0 6320 680 3\001 -# 1->3 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 19 - 2080 560 2140 551 2200 545 2260 540 2320 535 2380 529 2440 520 2902 495 3277 479 3608 470 3936 468 4306 472 4760 480 4901 490 5044 500 5188 510 5329 520 5467 530 5600 540 - 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 5608 470 5800 560 5594 610 5608 470 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 4320 360 SP / A\001 -# 2 -1 1 0 1 0 7 1 0 -1 0.000 0 0.0000 4320 1840 420 -430 4320 1840 4740 1410 -4 1 0 1 0 0 14.0 0.0000 4 0.0 0.0 4320 1920 2\001 -# 1->2 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 2020 780 2273 899 2560 1032 2868 1173 3180 1315 3483 1453 3760 1580 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 3786 1515 3940 1660 3729 1643 3786 1515 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 2980 880 'a'..'z' / A\001 -# 2->3 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 4680 1620 4829 1525 4993 1423 5168 1315 5347 1204 5526 1091 5700 980 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 5671 916 5880 880 5739 1038 5671 916 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 5280 1080 SP\001 -# 2->2 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 13 - 4020 1540 3970 1421 3960 1309 3990 1210 4060 1131 4170 1079 4320 1060 4430 1070 4520 1097 4590 1140 4640 1196 4670 1264 4680 1340 - 0 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 4745 1369 4620 1540 4610 1328 4745 1369 -4 1 0 0 0 0 14.0 0.0000 4 0.0 0.0 4320 940 'a'..'z'\001 -# end of FIG file diff --git a/doc/ragel/exstar.fig b/doc/ragel/exstar.fig deleted file mode 100644 index 3d822156..00000000 --- a/doc/ragel/exstar.fig +++ /dev/null @@ -1,77 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exstar -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3850 33 33 33 3850 66 3883 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 3850 383 383 1400 3850 1783 4233 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 3850 450 450 1400 3850 1850 4300 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3400 3850 383 383 3400 3850 3783 4233 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3783 933 3850 766 3900 766 3783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1116 3350 1083 3516 1016 3350 1116 3350 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2833 3783 3000 3850 2833 3883 2833 3783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1950 4183 1816 4066 2000 4083 1950 4183 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3166 3400 3133 3566 3066 3400 3166 3400 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 3915 2835 -90 2835 -90 4410 3915 4410 3915 2835 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3850 132 3850 225 3850 341 3850 474 3850 617 3850 - 766 3850 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1716 3516 1741 3410 1734 3312 1695 3227 1626 3159 1527 3115 - 1400 3100 1305 3108 1224 3131 1158 3168 1108 3218 1077 3279 - 1066 3350 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 1866 3850 1916 3842 1966 3838 2016 3835 2066 3833 2116 3833 - 2166 3833 2276 3833 2364 3833 2439 3833 2513 3833 2596 3833 - 2700 3833 2723 3833 2745 3833 2766 3833 2787 3833 2809 3833 - 2833 3833 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 1 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 3066 4050 3008 4081 2949 4110 2889 4135 2828 4156 2765 4172 - 2700 4183 2601 4203 2517 4212 2439 4214 2360 4209 2272 4198 - 2166 4183 2133 4175 2100 4166 2066 4158 2033 4150 2000 4141 - 1966 4133 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3666 3566 3687 3467 3682 3374 3652 3291 3595 3225 3511 3182 - 3400 3166 3316 3174 3248 3197 3195 3233 3156 3280 3130 3336 - 3116 3400 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1400 3933 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3800 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 240 1400 3050 10\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3400 3933 1\001 -4 1 0 0 0 0 14 0.0000 2 150 510 2433 3783 'a'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 165 240 2433 4116 10\001 -4 1 0 0 0 0 14 0.0000 2 150 510 3400 3116 'a'..'z'\001 diff --git a/doc/ragel/exstrongsubtr.fig b/doc/ragel/exstrongsubtr.fig deleted file mode 100644 index 2f256991..00000000 --- a/doc/ragel/exstrongsubtr.fig +++ /dev/null @@ -1,120 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exstrongsubtr -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3716 33 33 33 3716 66 3749 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 3716 383 383 1333 3716 1716 4099 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8433 3716 383 383 8433 3716 8816 4099 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8433 3716 450 450 8433 3716 8883 4166 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3266 3716 383 383 3266 3716 3649 4099 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4833 3716 383 383 4833 3716 5216 4099 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6700 3716 383 383 6700 3716 7083 4099 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3650 933 3716 766 3766 766 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2700 3650 2866 3716 2700 3766 2700 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3033 3266 3000 3433 2933 3266 3033 3266 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4266 3650 4433 3716 4266 3766 4266 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4600 3266 4566 3433 4500 3266 4600 3266 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6133 3650 6300 3716 6133 3750 6133 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7800 3650 7966 3716 7800 3766 7800 3650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5300 4033 5166 3916 5350 3933 5300 4033 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6466 3266 6433 3433 6366 3266 6466 3266 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 9135 2745 -180 2745 -180 4365 9135 4365 9135 2745 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3716 139 3716 237 3716 354 3716 485 3716 624 3716 - 766 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1733 3716 1881 3716 2039 3716 2204 3716 2371 3716 2538 3716 - 2700 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3533 3433 3554 3334 3549 3240 3518 3158 3461 3092 3377 3049 - 3266 3033 3183 3041 3115 3064 3062 3100 3023 3146 2997 3203 - 2983 3266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3666 3716 3760 3716 3859 3716 3960 3716 4062 3716 4165 3716 - 4266 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5100 3433 5120 3334 5116 3240 5085 3158 5028 3092 4944 3049 - 4833 3033 4749 3041 4682 3064 4629 3100 4590 3146 4564 3203 - 4550 3266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 5233 3716 5283 3715 5333 3712 5383 3708 5433 3704 5483 3701 - 5533 3700 5629 3700 5706 3700 5772 3700 5838 3700 5911 3700 - 6000 3700 6023 3700 6045 3700 6066 3700 6087 3700 6109 3700 - 6133 3700 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 7100 3716 7205 3716 7318 3716 7437 3716 7559 3716 7681 3716 - 7800 3716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 3 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 6366 3916 6308 3948 6249 3977 6189 4002 6128 4022 6065 4038 - 6000 4050 5911 4063 5838 4072 5772 4075 5706 4072 5629 4063 - 5533 4050 5499 4041 5466 4032 5431 4022 5395 4011 5357 3998 - 5316 3983 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 6966 3433 6987 3334 6982 3240 6952 3158 6895 3092 6811 3049 - 6700 3033 6616 3041 6548 3064 6495 3100 6456 3146 6430 3203 - 6416 3266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 3800 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3666 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 8433 3800 4\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3266 3800 1\001 -4 1 0 0 0 0 14 0.0000 2 150 510 2300 3666 'a'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 150 510 3266 2983 'a'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4833 3800 2\001 -4 1 0 0 0 0 14 0.0000 2 150 150 4050 3666 ':'\001 -4 1 0 0 0 0 14 0.0000 2 150 465 4833 2983 DEF\001 -4 1 0 0 0 0 14 0.0000 2 150 120 6700 3800 3\001 -4 1 0 0 0 0 14 0.0000 2 165 240 5766 3650 13\001 -4 1 0 0 0 0 14 0.0000 2 165 240 7533 3666 10\001 -4 1 0 0 0 0 14 0.0000 2 150 465 5766 3983 DEF\001 -4 1 0 0 0 0 14 0.0000 2 165 240 6700 2983 13\001 diff --git a/doc/ragel/exsubtr.fig b/doc/ragel/exsubtr.fig deleted file mode 100644 index 4a2ead26..00000000 --- a/doc/ragel/exsubtr.fig +++ /dev/null @@ -1,141 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exsubtr -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 9100 33 33 33 9100 66 9133 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 9100 383 383 1333 9100 1716 9483 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 1333 9183 0\001 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 66 9100 139 9100 237 9100 354 9100 485 9100 624 9100 766 9100 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 766 9033 933 9100 766 9150 766 9033 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 500 9050 IN\001 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 10600 8400 383 383 10600 8400 10983 8783 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 10600 8400 450 450 10600 8400 11050 8850 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 10600 8483 1\001 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 13 - 10916 8066 10941 7960 10934 7862 10895 7777 10826 7709 10727 7665 10600 7650 10505 7658 10424 7681 10358 7718 10308 7768 10277 7829 10266 7900 - 0 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 10316 7900 10283 8066 10216 7900 10316 7900 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 10600 7600 'a'..'z'\001 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2966 7633 383 383 2966 7633 3349 8016 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2966 7633 450 450 2966 7633 3416 8083 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2966 7716 2\001 -# 2 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 13 - 3433 7650 3917 7670 4530 7701 5237 7741 6002 7793 6790 7856 7566 7933 7997 7981 8433 8038 8862 8102 9271 8166 9649 8228 9983 8283 - 0 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 10000 8233 10150 8316 9983 8333 10000 8233 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 6950 7783 'a'..'n', 'p'..'z'\001 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5150 6716 383 383 5150 6716 5533 7099 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5150 6716 450 450 5150 6716 5600 7166 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 5150 6800 3\001 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 3400 7450 3576 7372 3769 7291 3972 7208 4180 7125 4385 7044 4583 6966 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 4550 6916 4733 6900 4600 7016 4550 6916 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 3850 7200 'o'\001 -# 3 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 13 - 5600 6616 6025 6539 6548 6468 7137 6422 7762 6420 8393 6478 9000 6616 9362 6750 9657 6893 9900 7058 10103 7256 10282 7499 10450 7800 - 0 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 10500 7766 10516 7950 10400 7816 10500 7766 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 8433 6383 'a'..'q', 's'..'z'\001 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8433 7150 383 383 8433 7150 8816 7533 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 8433 7233 4\001 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 5600 6783 5938 6827 6321 6875 6729 6927 7139 6979 7531 7032 7883 7083 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 7883 7033 8050 7100 7883 7133 7883 7033 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 6950 6850 'r'\001 -# 5 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2966 9100 383 383 2966 9100 3349 9483 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 2966 9100 450 450 2966 9100 3416 9550 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2966 9183 5\001 -# 5 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 19 - 3416 9166 3546 9177 3685 9191 3829 9208 3975 9224 4122 9239 4266 9250 5378 9281 6280 9248 7075 9158 7864 9017 8749 8834 9833 8616 9866 8615 9899 8612 9931 8608 9961 8604 9990 8601 10016 8600 - 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 10016 8550 10183 8583 10016 8650 10016 8550 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 6950 9033 'a'..'m', 'o'..'z'\001 -# 6 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5150 8650 383 383 5150 8650 5533 9033 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5150 8650 450 450 5150 8650 5600 9100 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 5150 8733 6\001 -# 5 -> 6 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 3416 9000 3590 8965 3776 8928 3968 8889 4162 8849 4352 8808 4533 8766 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 4533 8716 4700 8733 4550 8816 4533 8716 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 3850 8883 'n'\001 -# 6 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 13 - 5616 8650 5881 8656 6185 8660 6516 8660 6864 8656 7218 8647 7566 8633 7992 8612 8425 8586 8854 8556 9262 8524 9638 8494 9966 8466 - 0 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 9966 8416 10133 8450 9966 8516 9966 8416 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 8433 8516 'a'..'s', 'u'..'z'\001 -# 6 -> 4 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 13 - 5616 8616 5947 8587 6318 8548 6697 8497 7053 8435 7353 8358 7566 8266 7694 8183 7811 8087 7918 7981 8016 7867 8104 7750 8183 7633 - 0 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 8133 7616 8266 7500 8233 7666 8133 7616 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 6950 8216 't'\001 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 19 - 1566 9416 1727 9603 1922 9801 2147 9989 2400 10148 2674 10258 2966 10300 2991 10300 3169 10300 3650 10300 4586 10300 6130 10300 8433 10300 8906 10255 9276 10127 9572 9925 9823 9655 10056 9327 10300 8950 - 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 10266 8900 10400 8800 10350 8966 10266 8900 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 5150 10250 'a'..'e', 'g'..'h', 'j'..'z'\001 -# 0 -> 2 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 1633 8833 1765 8717 1909 8589 2060 8454 2212 8316 2360 8179 2500 8050 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 2466 8000 2633 7933 2550 8083 2466 8000 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2116 8316 'f'\001 -# 0 -> 5 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 7 - 1733 9100 1827 9100 1925 9100 2027 9100 2129 9100 2232 9100 2333 9100 - 0 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 2333 9033 2500 9100 2333 9150 2333 9033 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 2116 9050 'i'\001 -# 4 -> 1 -3 4 0 1 0 0 0 0 -1 0.0 0 0 0 13 - 8800 7283 8957 7345 9127 7416 9304 7493 9483 7578 9661 7669 9833 7766 9883 7801 9933 7837 9983 7875 10033 7912 10083 7948 10133 7983 - 0 1 1 1 1 1 1 1 1 1 1 1 0 -2 3 0 1 0 0 0 0 20 0.0 0 0 0 0 0 4 - 10166 7933 10266 8083 10100 8033 10166 7933 -4 1 0 0 0 0 14.0 0.0000 2 0.0 0.0 9566 7450 'a'..'z'\001 -# end of FIG file diff --git a/doc/ragel/extract.awk b/doc/ragel/extract.awk deleted file mode 100644 index 2874456b..00000000 --- a/doc/ragel/extract.awk +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/awk -# - -BEGIN { - in_generate = 0; - in_verbatim = 0; - return_val = 1; -} - -/^% GENERATE: *[a-z0-9A-Z_\.\-]+ *$/ && $3 == exname { - in_generate = 1; - return_val = 0; - next; -} - -/^% END GENERATE$/ { - in_generate = 0; - next; -} - -in_generate && /\\begin\{verbatim\}/ { - in_generate = 0; - in_verbatim = 1; - next; -} - -in_verbatim && /\\end\{verbatim\}/ { - in_generate = 1; - in_verbatim = 0; - next; -} - -in_generate && /^%/ { - print substr( $0, 2 ); -} - -in_verbatim { - print $0; -} - -END { exit return_val; } diff --git a/doc/ragel/finguard.fig b/doc/ragel/finguard.fig deleted file mode 100644 index 325eeb7f..00000000 --- a/doc/ragel/finguard.fig +++ /dev/null @@ -1,119 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exdonepri -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 4983 33 33 33 4983 66 5016 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1333 4983 383 383 1333 4983 1716 5366 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6566 4983 383 383 6566 4983 6949 5366 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 6566 4983 450 450 6566 4983 7016 5433 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3200 4466 383 383 3200 4466 3583 4849 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4833 4983 383 383 4833 4983 5216 5366 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 4916 933 4983 766 5033 766 4916 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1100 4533 1066 4700 1000 4533 1100 4533 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2633 4483 2800 4500 2650 4583 2633 4483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1866 5150 1716 5066 1883 5050 1866 5150 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2966 4016 2933 4183 2866 4016 2966 4016 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4350 4683 4483 4800 4300 4783 4350 4683 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5933 4916 6100 4983 5933 5033 5933 4916 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1816 5250 1650 5216 1816 5150 1816 5250 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3550 4900 3450 4766 3616 4816 3550 4900 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - -90 3510 7155 3510 7155 5535 -90 5535 -90 3510 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 4983 139 4983 237 4983 354 4983 485 4983 624 4983 - 766 4983 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1600 4700 1620 4600 1616 4507 1585 4425 1528 4359 1444 4315 - 1333 4300 1249 4308 1182 4330 1129 4366 1090 4413 1064 4469 - 1050 4533 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1683 4800 1741 4775 1799 4750 1858 4725 1916 4700 1974 4675 - 2033 4650 2127 4626 2225 4604 2327 4585 2429 4567 2532 4550 - 2633 4533 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 2950 4766 2892 4821 2833 4869 2768 4912 2694 4953 2606 4992 - 2500 5033 2398 5068 2295 5091 2191 5104 2087 5108 1984 5106 - 1883 5100 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3466 4183 3487 4084 3482 3990 3452 3908 3395 3842 3311 3799 - 3200 3783 3116 3791 3048 3814 2995 3850 2956 3896 2930 3953 - 2916 4016 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3583 4533 3669 4544 3759 4559 3852 4579 3946 4601 4040 4625 - 4133 4650 4166 4665 4200 4679 4233 4691 4266 4704 4300 4717 - 4333 4733 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 5233 4983 5338 4983 5451 4983 5570 4983 5692 4983 5814 4983 - 5933 4983 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 4483 5166 4354 5206 4228 5229 4097 5241 3954 5248 3791 5254 - 3600 5266 3295 5296 3045 5304 2822 5295 2598 5272 2344 5239 - 2033 5200 1992 5194 1954 5192 1918 5193 1883 5196 1850 5198 - 1816 5200 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 2 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4450 5033 4362 5038 4270 5038 4175 5033 4079 5022 3987 5005 - 3900 4983 3836 4965 3777 4945 3725 4925 3677 4904 3636 4884 - 3600 4866 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1333 5066 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 4933 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 120 6566 5066 3\001 -4 1 0 0 0 0 14 0.0000 2 150 465 1333 4250 DEF\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3200 4550 1\001 -4 1 0 0 0 0 14 0.0000 2 150 225 2266 4533 'F'\001 -4 1 0 0 0 0 14 0.0000 2 150 465 2266 4983 DEF\001 -4 1 0 0 0 0 14 0.0000 2 150 225 3200 3733 'F'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 4833 5066 2\001 -4 1 0 0 0 0 14 0.0000 2 150 165 4016 4550 'I'\001 -4 1 0 0 0 0 14 0.0000 2 150 270 5666 4933 'N'\001 -4 1 0 0 0 0 14 0.0000 2 150 465 3200 5216 DEF\001 -4 1 0 0 0 0 14 0.0000 2 150 225 4016 4933 'F'\001 diff --git a/doc/ragel/fixbackbox.awk b/doc/ragel/fixbackbox.awk deleted file mode 100644 index 434fd206..00000000 --- a/doc/ragel/fixbackbox.awk +++ /dev/null @@ -1,10 +0,0 @@ -#!/usr/bin/awk -# - -NF == 16 && $16 == 5 { - $7 = 1 - print $0 - next; -} - -{ print $0; } diff --git a/doc/ragel/generate.lm b/doc/ragel/generate.lm deleted file mode 100644 index bd4faef0..00000000 --- a/doc/ragel/generate.lm +++ /dev/null @@ -1,547 +0,0 @@ -# -# Copyright 2012 Adrian Thurston <thurston@colm.net> -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to -# deal in the Software without restriction, including without limitation the -# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -# sell copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. -# - -lex - token word /( [^. \t\n]+ | '.' )/ - token lws /[ \t]+/ - token nl / '\n'/ - - token cmd_verb1 /'.verb|'/ - token cmd_verb2 /'.verb/'/ - token cmd_label /'.label{'/ - token cmd_ref /'.ref{'/ - token cmd_em /'.em{'/ - token cmd_tt /'.tt{'/ - - token cmd_title /'.title' lws/ - token cmd_sub_title /'.subtitle' lws/ - token cmd_author /'.author' lws/ - - token cmd_chapter /'.chapter' lws/ - token cmd_section /'.section' lws/ - token cmd_sub_section /'.subsection' lws/ - token cmd_sub_sub_section /'.subsubsection' lws/ - - token cmd_graphic /'.graphic' lws/ - token cmd_comment /'.comment' lws? '\n'/ - token cmd_verbatim /'.verbatim' lws? '\n'/ - token cmd_code /'.code' lws? '\n'/ - - token cmd_itemize /'.itemize' lws? '\n'/ - token end_itemize /'.end' lws 'itemize' lws? '\n'/ - token cmd_item /'.item' lws/ - - token cmd_center /'.center' lws? '\n'/ - token end_center /'.end' lws 'center' lws? '\n'/ - - token cmd_tabular /'.tabular' lws? '\n'/ - token cmd_row /'.row' lws/ - token end_tabular /'.end' lws 'tabular' lws? '\n'/ - - token cmd_multicols /'.multicols' lws? '\n'/ - token cmd_columnbreak /'.columnbreak' lws? '\n'/ - token end_multicols /'.end' lws 'multicols' lws? '\n'/ - - token cmd_figure / '.figure' lws?/ - token cmd_caption / '.caption' lws/ - token end_figure / '.end' lws 'figure' lws? '\n'/ - - token cmd_list /'.list' lws? '\n'/ - token end_list /'.end' lws 'list' lws? '\n'/ - token cmd_li /'.li' lws/ - - token cmd_license /'.license' lws? '\n'/ -end - -lex - token bar_data /[^|]*/ - token end_bar /'|'/ -end - -lex - token slash_data /[^/]*/ - token end_slash /'/'/ -end - -lex - token curly_data /[^}]*/ - token end_curly /'}'/ -end - -def cmd_il - [cmd_verb1 bar_data end_bar] -| [cmd_verb2 slash_data end_slash] -| [cmd_label curly_data end_curly] -| [cmd_ref curly_data end_curly] -| [cmd_em curly_data end_curly] -| [cmd_tt curly_data end_curly] - -def text - [word] -| [lws] -| [cmd_il] - -lex - token end_verbatim /lws? '.' lws? 'end' lws 'verbatim' lws? '\n'/ - token verbatim_line /[^\n]* '\n'/ -end - -def verbatim - [cmd_verbatim verbatim_line* end_verbatim] - -lex - token end_code /lws? '.' lws? 'end' lws 'code' lws? '\n'/ - token code_line /[^\n]* '\n'/ -end - -def code - [cmd_code code_line* end_code] - -lex - token end_comment /lws? '.' lws? 'end' lws 'comment' lws? '\n'/ - token comment_line /[^\n]* '\n'/ -end - -def comment - [cmd_comment comment_line* end_comment] - -def figure - [cmd_figure text nl line* caption? end_figure] - -def li - [cmd_li text* nl] - -def _list - [cmd_list li* end_list] - -def scale - [lws word word*] - -def graphic - [cmd_graphic word scale? nl] - -def itemize - [cmd_itemize line* item* end_itemize] - -def center - [cmd_center line* end_center] - -def row - [cmd_row text* nl] - -def tabular - [cmd_tabular row* end_tabular] - -def multicols_line - [cmd_columnbreak] -| [line] - -def multicols - [cmd_multicols multicols_line* end_multicols] - -def item - [cmd_item line*] - -def caption - [cmd_caption line*] - -def line - [text] -| [nl] -| [comment] -| [verbatim] -| [code] -| [graphic] -| [itemize] -| [center] -| [tabular] -| [multicols] -| [figure] -| [_list] - -def sub_sub_section - [cmd_sub_sub_section text* nl line*] - -def sub_section - [cmd_sub_section text* nl line* sub_sub_section*] - -def section - [cmd_section text* nl line* sub_section*] - -def chapter - [cmd_chapter text* nl line* section*] - -def title - [cmd_title text* nl] - -def subtitle - [cmd_sub_title text* nl] - -def author - [cmd_author text* nl] - -# -# Paragraphs. -# - -def pline - [text text* nl] - -def paragraph - [pline pline*] - -def pextra - [nl paragraph] - -def block - [paragraph pextra*] - -def license - [cmd_license nl* block nl*] - -# -# Preamble. -# - -def preamble_item - [text] -| [nl] -| [title] -| [subtitle] -| [author] - -def preamble - [preamble_item* license] - -def start - [preamble chapter*] - -parse Start: start[ stdin ] -if ( ! Start ) { - print( error, '\n' ) - exit( 1 ) -} - -int printPlData( Pld: cmd_il ) -{ - if match Pld [ cmd_verb1 V: bar_data end_bar] { - print( '\\verb|' ) - print( V ) - print( '|' ) - } - else if match Pld [cmd_verb2 V: slash_data end_slash] { - print( '\\verb/' ) - print( V ) - print( '/' ) - } - else if match Pld [cmd_label L: curly_data end_curly] { - print( '\\label{' ) - print( L ) - print( '}' ) - } - else if match Pld [cmd_ref L: curly_data end_curly] { - print( '\\ref{' ) - print( L ) - print( '}' ) - } - else if match Pld [cmd_em L: curly_data end_curly] { - print( '{\\em ' ) - print( L ) - print( '}' ) - } - else if match Pld [cmd_tt L: curly_data end_curly] { - print( '{\\tt ' ) - print( L ) - print( '}' ) - } - else { - print( Pld ) - } -} - -int printText( Lines: text* ) -{ - for L: text in repeat(Lines) { - if match L [PlData: cmd_il] { - printPlData( PlData ) - } - else { - print( L ) - } - } -} - -int printLines( Lines: line* ) -{ - for L: line in repeat(Lines) { - if match L [word] { - print( L ) - } - if match L [lws] { - print( L ) - } - if match L [nl] { - print( L ) - } - if match L [PlData: cmd_il] { - printPlData( PlData ) - } - if match L [cmd_verbatim Lines: verbatim_line* end_verbatim] { - print( '\\begin{verbatim}\n' ) - print( Lines ) - print( '\\end{verbatim}\n' ) - print( '\\verbspace\n' ) - } - if match L [cmd_code Lines: code_line* end_code] { - print( '\\begin{inline_code}\n' ) - print( '\\begin{verbatim}\n' ) - print( Lines ) - print( '\\end{verbatim}\n' ) - print( '\\end{inline_code}\n' ) - print( '\\verbspace\n' ) - } - if match L [cmd_graphic Name: word Scale: scale? nl] { - print( '\\graphspace\n' ) - print( '\\begin{center}\n' ) - print( '\\includegraphics' ) - if match Scale [lws Spd: word Spd2: word*] - print( '[scale=', Spd, Spd2, ']' ) - else - print( '[scale=0.55]' ) - print( '{', Name, '}\n' ) - print( '\\end{center}\n' ) - print( '\\graphspace\n' ) - } - if match L [cmd_itemize Lines: line* Items: item* end_itemize] { - print( '\\begin{itemize}\n' ) - printLines( Lines ) - for Item: item in repeat(Items) { - match Item [cmd_item Lines: line*] - print( '\\item ' ) - printLines( Lines ) - } - print( '\\end{itemize}\n' ) - } - if match L [cmd_figure DirData: text nl Lines: line* Caption: caption? end_figure] { - print( '\\begin{figure}\n' ) - print( '\\small\n' ) - printLines( Lines ) - if match Caption [cmd_caption CL: line*] { - print( '\\caption{' ) - printLines( CL ) - print( '}\n' ) - } - print( '\\label{', DirData, '}\n' ) - print( '\\end{figure}\n' ) - } - if match L [cmd_list LiList: li* end_list] { - for Li: li* in LiList { - if match Li [cmd_li Lines: text* nl Rest: li*] { - print( '\\noindent\\\hspace*{24pt}' ) - printText( Lines ) - if match Rest [ li li* ] - print( '\\\\' ) - print( '\n' ) - } - } - print( '\\vspace{12pt}\n' ) - } - if match L [cmd_center Lines: line* end_center] { - print( '\\begin{center}\n' ) - printLines( Lines ) - print( '\\end{center}\n' ) - } - if match L [cmd_tabular Rows: row* end_tabular] { - print( '\\begin{tabular}{|c|c|c|}\n' ) - print( '\\hline\n' ) - for Row: row in repeat(Rows) { - if match Row [cmd_row Lines: text* nl ] { - printText( Lines ) - print( '\\\\' '\n' ) - print( '\\hline\n' ) - } - } - print( '\\end{tabular}\n' ) - } - if match L [cmd_multicols Lines: multicols_line* end_multicols] { - print( '\\begin{multicols}{2}\n' ) - for McLine: multicols_line in repeat( Lines ) { - if match McLine [Line: line] - printLines( cons line* [Line] ) - else if match McLine [cmd_columnbreak] { - print( '\\columnbreak\n' ) - } - } - print( '\\end{multicols}\n' ) - } - } -} - -match Start - [Preamble: preamble Chapters: chapter*] - -Title: title = title in Preamble -match Title [cmd_title TitleData: text* nl] - -SubTitle: subtitle = subtitle in Preamble -match SubTitle [cmd_sub_title SubTitleData: text* nl] - -Author: author = author in Preamble -match Author [cmd_author AuthorData: text* nl] - -License: license = license in Preamble - -print( - ~\documentclass[letterpaper,11pt,oneside]{book} - ~\usepackage{graphicx} - ~\usepackage{comment} - ~\usepackage{multicol} - ~\usepackage[ - ~ colorlinks=true, - ~ linkcolor=black, - ~ citecolor=green, - ~ filecolor=black, - ~ urlcolor=black]{hyperref} - ~ - ~\topmargin -0.20in - ~\oddsidemargin 0in - ~\textwidth 6.5in - ~\textheight 9in - ~ - ~\setlength{\parskip}{0pt} - ~\setlength{\topsep}{0pt} - ~\setlength{\partopsep}{0pt} - ~\setlength{\itemsep}{0pt} - ~ - ~\input{version} - ~ - ~\newcommand{\verbspace}{\vspace{10pt}} - ~\newcommand{\graphspace}{\vspace{10pt}} - ~ - ~\renewcommand\floatpagefraction{.99} - ~\renewcommand\topfraction{.99} - ~\renewcommand\bottomfraction{.99} - ~\renewcommand\textfraction{.01} - ~\setcounter{totalnumber}{50} - ~\setcounter{topnumber}{50} - ~\setcounter{bottomnumber}{50} - ~ - ~\newenvironment{inline_code}{\def\baselinestretch{1}\vspace{12pt}\small}{} - ~ - ~\begin{document} - ~ - ~\thispagestyle{empty} - ~\begin{center} - ~\vspace*{3in} -) - -print( '{\\huge ', TitleData, '}\\\\\n' ) - -print( '\\vspace*{12pt}\n' ) - -print( '{\\Large ', SubTitleData, '}\\\\\n' ) - -print( - ~\vspace{1in} - ~by\\ - ~\vspace{12pt} -) - -print( '{\\large ', AuthorData, '}\\\\\n' ) - -print( - ~\end{center} - ~\clearpage - ~ - ~\pagenumbering{roman} - ~ - ~\chapter*{License} -) - -print( - ~Ragel version \version, \pubdate\\ - ~Copyright \copyright\ 2003-2012 Adrian D. Thurston - ~\vspace{6mm} - ~ -) - -i: int = 0 -for P: paragraph in License { - if ( i != 0 ) { - print( - ~ - ~\vspace{5pt} - ~ - ) - } - print( "{\\bf\\it\\noindent " ) - print( P ) - print( "}\n" ) - i = i + 1 -} - -print( - ~ - ~\clearpage - ~\tableofcontents - ~\clearpage - ~ - ~\pagenumbering{arabic} -) - - -for Chapter: chapter in repeat(Chapters) { - match Chapter - [cmd_chapter DirData: text* nl Lines: line* SectionList: section*] - - print( '\\chapter{', DirData, '}\n' ) - printLines( Lines ) - - for Section: section in repeat(SectionList) { - match Section - [cmd_section DirData: text* nl Lines: line* SubSectionList: sub_section*] - - print( '\\section{', DirData, '}\n' ) - printLines( Lines ) - for SubSection: sub_section in repeat(SubSectionList) { - match SubSection - [cmd_sub_section DirData: text* nl Lines: line* - SubSubSectionList: sub_sub_section*] - - print( '\\subsection{', DirData, '}\n' ) - printLines( Lines ) - - for SubSubSection: sub_sub_section in repeat(SubSubSectionList) { - match SubSubSection - [cmd_sub_sub_section DirData: text* nl Lines: line*] - - print( '\\subsubsection{', DirData, '}\n' ) - printLines( Lines ) - } - } - } -} - -print( - ~ - ~\end{document} -) diff --git a/doc/ragel/genfigs.sh b/doc/ragel/genfigs.sh deleted file mode 100755 index 8d521075..00000000 --- a/doc/ragel/genfigs.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/bin/bash -# - -input=ragel-guide.tex - -for fig; do - if awk -f extract.awk -vexname=$fig $input > /dev/null; then - echo generating ${fig}.dot - opt=`awk -f extract.awk -vexname=$fig $input | - sed '/^ *OPT:/s/^.*: *//p;d'` - awk -f extract.awk -vexname=$fig $input > ${fig}.rl - ../ragel/ragel -V -p ${fig}.rl > ${fig}.dot - else - echo "$0: internal error: figure $fig not found in $input" >&2 - exit 1 - fi -done - diff --git a/doc/ragel/leftguard.fig b/doc/ragel/leftguard.fig deleted file mode 100644 index 0fdb7f7b..00000000 --- a/doc/ragel/leftguard.fig +++ /dev/null @@ -1,94 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: leftguard -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 5183 33 33 33 5183 66 5216 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 5183 383 383 1400 5183 1783 5566 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 5183 450 450 1400 5183 1850 5633 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4033 4550 383 383 4033 4550 4416 4933 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 4033 4550 450 450 4033 4550 4483 5000 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 7500 5183 383 383 7500 5183 7883 5566 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 7500 5183 450 450 7500 5183 7950 5633 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 5116 933 5183 766 5233 766 5116 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3416 4650 3583 4666 3433 4750 3416 4650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6883 5216 7050 5250 6883 5316 6883 5216 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3750 4050 3716 4216 3650 4050 3750 4050 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6900 5016 7050 5100 6883 5116 6900 5016 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7400 4600 7333 4766 7300 4600 7400 4600 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7033 4766 7116 4933 6950 4850 7033 4766 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 8190 3510 -45 3510 -45 5715 8190 5715 8190 3510 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 5183 132 5183 225 5183 341 5183 474 5183 617 5183 - 766 5183 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1850 5083 2082 5028 2341 4965 2614 4897 2891 4829 3162 4761 - 3416 4700 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1866 5266 2062 5292 2280 5320 2512 5347 2753 5374 2995 5397 - 3233 5416 3891 5447 4564 5444 5227 5416 5851 5372 6412 5319 - 6883 5266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4350 4216 4375 4110 4367 4012 4329 3927 4259 3859 4160 3815 - 4033 3800 3939 3808 3858 3831 3791 3868 3741 3918 3710 3979 - 3700 4050 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 4483 4633 4827 4692 5227 4764 5658 4843 6094 4924 6511 5001 - 6883 5066 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7666 4766 7662 4678 7649 4598 7627 4531 7595 4479 7552 4445 - 7500 4433 7462 4438 7431 4454 7406 4479 7385 4512 7366 4552 - 7350 4600 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7883 4933 8038 4752 8106 4570 8085 4402 7977 4262 7781 4168 - 7500 4133 7243 4160 7055 4236 6937 4350 6888 4491 6909 4650 - 7000 4816 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1400 5266 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 5133 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 4033 4633 1\001 -4 1 0 0 0 0 14 0.0000 2 150 720 2550 4800 ' ' / start\001 -4 1 0 0 0 0 14 0.0000 2 150 120 7500 5266 2\001 -4 1 0 0 0 0 14 0.0000 2 225 1575 4033 5366 'a'..'z' / fin, alpha\001 -4 1 0 0 0 0 14 0.0000 2 150 150 4033 3750 ' '\001 -4 1 0 0 0 0 14 0.0000 2 225 1575 5933 4716 'a'..'z' / fin, alpha\001 -4 1 0 0 0 0 14 0.0000 2 150 600 7500 4383 ' ' / ws\001 -4 1 0 0 0 0 14 0.0000 2 225 1200 7500 4083 'a'..'z' / alpha\001 diff --git a/doc/ragel/lines1.fig b/doc/ragel/lines1.fig deleted file mode 100644 index dfaf2197..00000000 --- a/doc/ragel/lines1.fig +++ /dev/null @@ -1,164 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: lines1 -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 6150 33 33 33 6150 66 6183 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 6150 383 383 1400 6150 1783 6533 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 6150 450 450 1400 6150 1850 6600 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3933 6150 383 383 3933 6150 4316 6533 -# 4 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5666 5416 383 383 5666 5416 6049 5799 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5666 5416 450 450 5666 5416 6116 5866 -# 5 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8633 5716 383 383 8633 5716 9016 6099 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 10433 5716 383 383 10433 5716 10816 6099 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 12833 5066 383 383 12833 5066 13216 5449 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 6083 933 6150 766 6200 766 6083 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3366 6083 3533 6150 3366 6200 3366 6083 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8116 5466 8266 5566 8083 5566 8116 5466 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5050 5616 5233 5600 5100 5716 5050 5616 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3700 5700 3666 5866 3600 5700 3700 5700 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 9900 5916 10083 5900 9950 6016 9900 5916 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 12283 5083 12450 5116 12283 5183 12283 5083 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6266 5216 6083 5216 6216 5100 6266 5216 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 10966 5900 10816 5816 10983 5800 10966 5900 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 12600 4616 12566 4783 12500 4616 12600 4616 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6166 5800 6050 5666 6216 5700 6166 5800 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 9866 5650 10033 5716 9866 5766 9866 5650 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 8400 5266 8366 5433 8300 5266 8400 5266 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 13455 4095 -45 4095 -45 6660 13455 6660 13455 4095 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 6150 132 6150 225 6150 341 6150 474 6150 617 6150 - 766 6150 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 1866 6150 2091 6150 2340 6150 2604 6150 2870 6150 3128 6150 - 3366 6150 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 4 -> 5 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 6116 5400 6370 5393 6658 5391 6968 5397 7291 5413 7617 5441 - 7933 5483 7959 5484 7987 5488 8016 5493 8045 5500 8073 5508 - 8100 5516 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 4300 6000 4414 5947 4540 5891 4672 5833 4809 5775 4947 5719 - 5083 5666 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4200 5866 4220 5767 4216 5674 4185 5591 4128 5525 4044 5482 - 3933 5466 3849 5474 3782 5497 3729 5533 3690 5580 3664 5636 - 3650 5700 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4316 6216 4847 6281 5543 6347 6356 6395 7240 6408 8148 6365 - 9033 6250 9191 6218 9348 6176 9502 6127 9651 6073 9796 6018 - 9933 5966 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 10783 5533 10841 5508 10900 5483 10958 5458 11016 5433 11075 5408 - 11133 5383 11322 5327 11520 5277 11720 5233 11918 5194 12107 5161 - 12283 5133 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 25 - 12450 4933 12399 4916 12349 4900 12297 4885 12245 4871 12190 4859 - 12133 4850 11611 4766 10966 4689 10252 4627 9522 4588 8831 4581 - 8233 4616 7870 4671 7577 4725 7320 4785 7066 4857 6781 4948 - 6433 5066 6400 5082 6367 5095 6335 5108 6304 5120 6276 5134 - 6250 5150 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 0.000 -# 3 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 12616 5383 12554 5459 12483 5534 12406 5606 12321 5670 12230 5725 - 12133 5766 11943 5828 11746 5866 11545 5883 11348 5883 11158 5871 - 10983 5850 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 13100 4783 13120 4684 13116 4590 13085 4508 13028 4442 12944 4399 - 12833 4383 12749 4391 12682 4414 12629 4450 12590 4496 12564 4553 - 12550 4616 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 5 -> 4 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 8250 5800 8003 5840 7719 5874 7410 5895 7085 5897 6756 5873 - 6433 5816 6392 5807 6354 5795 6316 5783 6279 5770 6240 5759 - 6200 5750 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 5 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 9033 5716 9163 5716 9301 5716 9443 5716 9587 5716 9729 5716 - 9866 5716 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 5 -> 5 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 8900 5433 8920 5334 8916 5240 8885 5158 8828 5092 8744 5049 - 8633 5033 8549 5041 8482 5064 8429 5100 8390 5146 8364 5203 - 8350 5266 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1400 6233 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 6100 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3933 6233 1\001 -4 1 0 0 0 0 14 0.0000 2 150 1050 2700 6100 'a'..'z' / first\001 -4 1 0 0 0 0 14 0.0000 2 150 120 5666 5500 4\001 -4 1 0 0 0 0 14 0.0000 2 150 120 8633 5800 5\001 -4 1 0 0 0 0 14 0.0000 2 195 1455 7183 5350 'a'..'z' / tail, first\001 -4 1 0 0 0 0 14 0.0000 2 165 240 4766 5733 10\001 -4 1 0 0 0 0 14 0.0000 2 150 1050 3933 5416 'a'..'z' / first\001 -4 1 0 0 0 0 14 0.0000 2 150 120 10433 5800 2\001 -4 1 0 0 0 0 14 0.0000 2 180 390 7183 6350 9, ' '\001 -4 1 0 0 0 0 14 0.0000 2 150 120 12833 5150 3\001 -4 1 0 0 0 0 14 0.0000 2 165 975 11633 5133 'a'..'z' / tail\001 -4 1 0 0 0 0 14 0.0000 2 165 240 9533 4550 10\001 -4 1 0 0 0 0 14 0.0000 2 180 390 11633 5716 9, ' '\001 -4 1 0 0 0 0 14 0.0000 2 165 975 12833 4333 'a'..'z' / tail\001 -4 1 0 0 0 0 14 0.0000 2 165 240 7183 5766 10\001 -4 1 0 0 0 0 14 0.0000 2 180 390 9533 5666 9, ' '\001 -4 1 0 0 0 0 14 0.0000 2 195 1455 8633 4983 'a'..'z' / first, tail\001 diff --git a/doc/ragel/lines2.fig b/doc/ragel/lines2.fig deleted file mode 100644 index 9d9d7130..00000000 --- a/doc/ragel/lines2.fig +++ /dev/null @@ -1,121 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: lines2 -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 4883 33 33 33 4883 66 4916 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 4883 383 383 1400 4883 1783 5266 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 4883 450 450 1400 4883 1850 5333 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3933 4416 383 383 3933 4416 4316 4799 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5733 4416 383 383 5733 4416 6116 4799 -# 3 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 8133 4883 383 383 8133 4883 8516 5266 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 4816 933 4883 766 4933 766 4816 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3366 4350 3533 4416 3366 4466 3366 4350 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2000 5066 1850 4983 2016 4966 2000 5066 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3700 3966 3666 4133 3600 3966 3700 3966 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5166 4350 5333 4416 5166 4466 5166 4350 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7666 4566 7783 4700 7616 4666 7666 4566 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1933 5183 1766 5150 1933 5083 1933 5183 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 6133 4816 6033 4666 6200 4716 6133 4816 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 7900 4433 7866 4600 7800 4433 7900 4433 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 8775 3465 -45 3465 -45 5400 8775 5400 8775 3465 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 4883 132 4883 225 4883 341 4883 474 4883 617 4883 - 766 4883 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1816 4683 1875 4658 1933 4633 1991 4610 2050 4588 2108 4567 - 2166 4550 2370 4505 2577 4470 2785 4445 2988 4429 3184 4419 - 3366 4416 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3650 4683 3590 4733 3527 4781 3460 4827 3389 4868 3313 4904 - 3233 4933 3035 4988 2829 5021 2618 5037 2409 5039 2207 5031 - 2016 5016 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 4200 4133 4220 4034 4216 3940 4185 3858 4128 3792 4044 3749 - 3933 3733 3849 3741 3782 3764 3729 3800 3690 3846 3664 3903 - 3650 3966 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 4333 4416 4463 4416 4601 4416 4743 4416 4887 4416 5029 4416 - 5166 4416 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 6133 4416 6321 4418 6529 4425 6752 4439 6981 4463 7210 4499 - 7433 4550 7466 4558 7499 4567 7533 4577 7566 4588 7599 4601 - 7633 4616 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 25 - 7800 5066 7748 5072 7693 5074 7635 5075 7572 5075 7505 5077 - 7433 5083 6610 5156 5940 5185 5345 5183 4748 5164 4069 5143 - 3233 5133 3025 5142 2856 5151 2706 5158 2554 5159 2381 5151 - 2166 5133 2125 5127 2083 5125 2043 5127 2004 5129 1967 5132 - 1933 5133 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 0.000 -# 3 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 7750 4950 7561 4971 7349 4984 7122 4985 6889 4970 6657 4938 - 6433 4883 6384 4872 6338 4856 6293 4837 6250 4815 6208 4791 - 6166 4766 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 3 -> 3 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 8400 4600 8420 4500 8416 4407 8385 4325 8328 4259 8244 4215 - 8133 4200 8049 4208 7982 4230 7929 4266 7890 4313 7864 4369 - 7850 4433 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1400 4966 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 4833 IN\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3933 4500 1\001 -4 1 0 0 0 0 14 0.0000 2 150 1050 2700 4400 'a'..'z' / first\001 -4 1 0 0 0 0 14 0.0000 2 165 240 2700 4883 10\001 -4 1 0 0 0 0 14 0.0000 2 150 1050 3933 3683 'a'..'z' / first\001 -4 1 0 0 0 0 14 0.0000 2 150 120 5733 4500 2\001 -4 1 0 0 0 0 14 0.0000 2 180 390 4833 4366 9, ' '\001 -4 1 0 0 0 0 14 0.0000 2 150 120 8133 4966 3\001 -4 1 0 0 0 0 14 0.0000 2 165 975 6933 4400 'a'..'z' / tail\001 -4 1 0 0 0 0 14 0.0000 2 165 240 4833 5116 10\001 -4 1 0 0 0 0 14 0.0000 2 180 390 6933 4833 9, ' '\001 -4 1 0 0 0 0 14 0.0000 2 165 975 8133 4150 'a'..'z' / tail\001 diff --git a/doc/ragel/lmkleene.fig b/doc/ragel/lmkleene.fig deleted file mode 100644 index b0207af8..00000000 --- a/doc/ragel/lmkleene.fig +++ /dev/null @@ -1,116 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: exfinpri -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 6166 33 33 33 6166 66 6199 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 6166 383 383 1400 6166 1783 6549 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 6166 450 450 1400 6166 1850 6616 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3466 5416 383 383 3466 5416 3849 5799 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 3466 5416 450 450 3466 5416 3916 5866 -# 2 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5866 6433 383 383 5866 6433 6249 6816 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5866 6433 450 450 5866 6433 6316 6883 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 6100 933 6166 766 6216 766 6100 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1116 5666 1083 5833 1016 5666 1116 5666 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2833 5366 3000 5400 2833 5466 2833 5366 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5233 6350 5400 6416 5233 6450 5233 6350 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 2033 6166 1866 6133 2033 6066 2033 6166 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 3183 4916 3150 5083 3083 4916 3183 4916 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5300 6133 5433 6250 5250 6233 5300 6133 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1950 6483 1816 6366 2000 6383 1950 6483 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 5583 5933 5550 6100 5483 5933 5583 5933 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - -45 4365 6615 4365 6615 7020 -45 7020 -45 4365 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 6166 132 6166 225 6166 341 6166 474 6166 617 6166 - 766 6166 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1716 5833 1741 5727 1734 5629 1695 5543 1626 5476 1527 5432 - 1400 5416 1305 5424 1224 5448 1158 5485 1108 5535 1077 5596 - 1066 5666 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1733 5833 1794 5782 1860 5730 1931 5679 2006 5630 2084 5587 - 2166 5550 2270 5512 2380 5482 2493 5458 2608 5440 2722 5426 - 2833 5416 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1866 6200 2033 6216 2216 6232 2408 6247 2606 6261 2804 6273 - 3000 6283 3391 6307 3790 6328 4185 6347 4565 6366 4918 6383 - 5233 6400 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3116 5700 3049 5742 2982 5786 2914 5829 2845 5869 2773 5904 - 2700 5933 2590 5979 2479 6017 2366 6050 2254 6076 2142 6098 - 2033 6116 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 3783 5083 3808 4977 3801 4879 3762 4793 3693 4726 3594 4682 - 3466 4666 3372 4674 3291 4698 3225 4735 3175 4785 3144 4846 - 3133 4916 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 1 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 3883 5600 4095 5688 4327 5784 4570 5885 4816 5987 5056 6088 - 5283 6183 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 2 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5416 6533 5099 6593 4727 6650 4314 6695 3878 6722 3434 6720 - 3000 6683 2783 6650 2595 6618 2427 6583 2271 6542 2120 6493 - 1966 6433 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 2 -> 2 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 6183 6100 6208 5993 6201 5895 6162 5810 6093 5743 5994 5699 - 5866 5683 5772 5691 5691 5714 5625 5752 5575 5801 5544 5862 - 5533 5933 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1400 6250 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 6116 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 150 1400 5366 ' '\001 -4 1 0 0 0 0 14 0.0000 2 165 120 3466 5500 1\001 -4 1 0 0 0 0 14 0.0000 2 150 540 2433 5400 '0'..'9'\001 -4 1 0 0 0 0 14 0.0000 2 150 120 5866 6516 2\001 -4 1 0 0 0 0 14 0.0000 2 150 510 3466 6233 'a'..'z'\001 -4 1 0 0 0 0 14 0.0000 2 150 495 2433 5883 ' ' / B\001 -4 1 0 0 0 0 14 0.0000 2 150 540 3466 4616 '0'..'9'\001 -4 1 0 0 0 0 14 0.0000 2 150 855 4666 5733 'a'..'z' / B\001 -4 1 0 0 0 0 14 0.0000 2 150 510 3466 6633 ' ' / A\001 -4 1 0 0 0 0 14 0.0000 2 180 1170 5866 5633 '0'..'9', 'a'..'z'\001 diff --git a/doc/ragel/opconcat.fig b/doc/ragel/opconcat.fig deleted file mode 100644 index d46084eb..00000000 --- a/doc/ragel/opconcat.fig +++ /dev/null @@ -1,39 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Landscape -Center -Metric -A4 -100.00 -Single --2 -1200 2 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 585 630 135 135 585 630 720 630 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1215 810 90 90 1215 810 1305 810 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1215 810 135 135 1215 810 1350 810 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1215 450 135 135 1215 450 1350 450 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1215 450 90 90 1215 450 1305 450 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2340 630 135 135 2340 630 2475 630 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2970 450 90 90 2970 450 3060 450 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2970 450 135 135 2970 450 3105 450 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2970 810 135 135 2970 810 3105 810 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2970 810 90 90 2970 810 3060 810 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 45.00 60.00 - 1350 450 2205 585 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 45.00 60.00 - 1350 810 2205 675 -3 1 0 1 0 7 50 0 -1 0.000 0 0 0 8 - 225 630 495 270 1125 180 1485 270 1530 630 1485 990 - 1125 1080 495 990 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 -3 1 0 1 0 7 50 0 -1 0.000 0 0 0 8 - 1980 630 2250 270 2880 180 3240 270 3285 630 3240 990 - 2880 1080 2250 990 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 -3 0 0 1 0 7 50 0 -1 0.000 0 1 0 6 - 1 1 1.00 45.00 60.00 - 45 675 135 540 225 810 315 630 360 630 450 630 - 0.000 1.000 1.000 1.000 1.000 0.000 -4 0 0 50 0 32 10 0.0000 4 90 75 1710 450 e\001 -4 0 0 50 0 32 10 0.0000 4 90 75 1710 900 e\001 diff --git a/doc/ragel/opor.fig b/doc/ragel/opor.fig deleted file mode 100644 index edeefb40..00000000 --- a/doc/ragel/opor.fig +++ /dev/null @@ -1,40 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Landscape -Center -Metric -A4 -100.00 -Single --2 -1200 2 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 585 945 135 135 585 945 720 945 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1215 450 135 135 1215 450 1350 450 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1845 630 135 135 1845 630 1980 630 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1845 630 90 90 1845 630 1935 630 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1845 270 135 135 1845 270 1980 270 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1845 270 90 90 1845 270 1935 270 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1845 1260 90 90 1845 1260 1935 1260 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1845 1260 135 135 1845 1260 1980 1260 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1215 1440 135 135 1215 1440 1350 1440 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1845 1620 90 90 1845 1620 1935 1620 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1845 1620 135 135 1845 1620 1980 1620 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 45.00 60.00 - 675 1035 1125 1350 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 45.00 60.00 - 675 855 1125 540 -3 1 0 1 0 7 50 0 -1 0.000 0 0 0 8 - 855 1440 1125 1080 1755 990 2115 1080 2160 1440 2115 1800 - 1755 1890 1125 1800 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 -3 1 0 1 0 7 50 0 -1 0.000 0 0 0 8 - 855 450 1125 90 1755 0 2115 90 2160 450 2115 810 - 1755 900 1125 810 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 -3 0 0 1 0 7 50 0 -1 0.000 0 1 0 6 - 1 1 1.00 45.00 60.00 - 45 990 135 855 225 1125 315 945 360 945 450 945 - 0.000 1.000 1.000 1.000 1.000 0.000 -4 0 0 50 0 32 10 0.0000 4 90 75 720 1260 e\001 -4 0 0 50 0 32 10 0.0000 4 90 75 720 720 e\001 diff --git a/doc/ragel/opstar.fig b/doc/ragel/opstar.fig deleted file mode 100644 index cb2cac6d..00000000 --- a/doc/ragel/opstar.fig +++ /dev/null @@ -1,43 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Landscape -Center -Metric -A4 -100.00 -Single --2 -1200 2 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 945 675 135 135 945 675 1080 675 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1149 58 90 90 1149 58 1239 58 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1149 58 135 135 1149 58 1284 58 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 1620 495 135 135 1620 495 1755 495 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2250 315 90 90 2250 315 2340 315 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2250 315 135 135 2250 315 2385 315 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2250 675 135 135 2250 675 2385 675 -1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 2250 675 90 90 2250 675 2340 675 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 45.00 60.00 - 1080 630 1485 540 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 45.00 60.00 - 973 543 1103 203 -3 1 0 1 0 7 50 0 -1 0.000 0 0 0 8 - 1260 495 1530 135 2160 45 2520 135 2565 495 2520 855 - 2160 945 1530 855 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 -3 0 0 1 0 7 50 0 -1 0.000 0 1 0 6 - 1 1 1.00 45.00 60.00 - 2385 360 2700 630 2700 1215 1980 1395 1260 1125 978 801 - 0.000 1.000 1.000 1.000 1.000 0.000 -3 0 0 1 0 7 50 0 -1 0.000 0 1 0 6 - 1 1 1.00 45.00 60.00 - 405 720 495 585 585 855 675 675 720 675 810 675 - 0.000 1.000 1.000 1.000 1.000 0.000 -3 0 0 1 0 7 50 0 -1 0.000 0 1 0 6 - 1 1 1.00 45.00 60.00 - 2385 720 2520 855 2475 1125 1935 1215 1395 1035 1067 730 - 0.000 1.000 1.000 1.000 1.000 0.000 -4 0 0 50 0 32 10 0.0000 4 90 75 1845 1125 e\001 -4 0 0 50 0 32 10 0.0000 4 90 75 1845 1440 e\001 -4 0 0 50 0 32 10 0.0000 4 90 75 1156 549 e\001 -4 0 0 50 0 32 10 0.0000 4 90 75 896 442 e\001 diff --git a/doc/ragel/ragel-guide.tex b/doc/ragel/ragel-guide.tex deleted file mode 100644 index ac43edbc..00000000 --- a/doc/ragel/ragel-guide.tex +++ /dev/null @@ -1,3561 +0,0 @@ -\documentclass[letterpaper,11pt,oneside]{book} -\usepackage{graphicx} -\usepackage{comment} -\usepackage{multicol} -\usepackage[ - colorlinks=true, - linkcolor=black, - citecolor=green, - filecolor=black, - urlcolor=black]{hyperref} - -\topmargin -0.20in -\oddsidemargin 0in -\textwidth 6.5in -\textheight 9in - -\setlength{\parskip}{0pt} -\setlength{\topsep}{0pt} -\setlength{\partopsep}{0pt} -\setlength{\itemsep}{0pt} - -\input{version} - -\newcommand{\verbspace}{\vspace{10pt}} -\newcommand{\graphspace}{\vspace{10pt}} - -\renewcommand\floatpagefraction{.99} -\renewcommand\topfraction{.99} -\renewcommand\bottomfraction{.99} -\renewcommand\textfraction{.01} -\setcounter{totalnumber}{50} -\setcounter{topnumber}{50} -\setcounter{bottomnumber}{50} - -\newenvironment{inline_code}{\def\baselinestretch{1}\vspace{12pt}\small}{} - -\begin{document} - -\thispagestyle{empty} -\begin{center} -\vspace*{3in} -{\huge Ragel State Machine Compiler}\\ -\vspace*{12pt} -{\Large User Guide}\\ -\vspace{1in} -by\\ -\vspace{12pt} -{\large Adrian Thurston}\\ -\end{center} -\clearpage - -\pagenumbering{roman} - -\chapter*{License} -Ragel version \version, \pubdate\\ -Copyright \copyright\ 2003-2016 Adrian D. Thurston -\vspace{6mm} - -{\bf\it\noindent Permission is hereby granted, free of charge, to any person -obtaining a copy of this software and associated documentation files (the -"Software"), to deal in the Software without restriction, including without -limitation the rights to use, copy, modify, merge, publish, distribute, -sublicense, and/or sell copies of the Software, and to permit persons to whom -the Software is furnished to do so, subject to the following conditions:} - -\vspace{5pt} - -{\bf\it\noindent The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software.} - -\vspace{5pt} - -{\bf\it\noindent THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY -KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO -EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES -OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE.} - -\clearpage -\tableofcontents -\clearpage - -\pagenumbering{arabic} -\chapter{Introduction} - -\section{Abstract} - -Regular expressions are used heavily in practice for the purpose of specifying -parsers. They are normally used as black boxes linked together with program -logic. User actions are executed in between invocations of the regular -expression engine. Adding actions before a pattern terminates requires patterns -to be broken and pasted back together with program logic. The more user actions -are needed, the less the advantages of regular expressions are seen. - -Ragel is a software development tool that allows user actions to be -embedded into the transitions of a regular expression's corresponding state -machine, eliminating the need to switch from the regular expression engine and -user code execution environment and back again. As a result, expressions can be -maximally continuous. One is free to specify an entire parser using a single -regular expression. The single-expression model affords concise and elegant -descriptions of languages and the generation of very simple, fast and robust -code. Ragel compiles executable finite state machines from a high level regular language -notation. Ragel targets C, C++, Objective-C, D, Go, Java, Ruby and OCaml. - -In addition to building state machines from regular expressions, Ragel allows -the programmer to directly specify state machines with state charts. These two -notations may be freely combined. There are also facilities for controlling -nondeterminism in the resulting machines and building scanners using patterns -that themselves have embedded actions. Ragel can produce code that is small and -runs very fast. Ragel can handle integer-sized alphabets and can compile very -large state machines. - -\section{Motivation} - -When a programmer is faced with the task of producing a parser for a -context-free language, there are many tools to choose from. It is quite common -to generate useful and efficient parsers for programming languages from a -formal grammar. It is also quite common for programmers to avoid such tools -when making parsers for simple computer languages, such as file formats and -communication protocols. Such languages are often regular, and tools for -processing the context-free languages are viewed as too heavyweight for the -purpose of parsing regular languages. The extra run-time effort required for -supporting the recursive nature of context-free languages is wasted. - -When we turn to the regular expression-based parsing tools, such as Lex, Re2C, -and scripting languages such as Sed, Awk and Perl we find that they are split -into two levels: a regular expression matching engine and some kind of program -logic for linking patterns together. For example, a Lex program is composed of -sets of regular expressions. The implied program logic repeatedly attempts to -match a pattern in the current set. When a match is found, the associated user -code executed. It requires the user to consider a language as a sequence of -independent tokens. Scripting languages and regular expression libraries allow -one to link patterns together using arbitrary program code. This is very -flexible and powerful; however, we can be more concise and clear if we avoid -gluing together regular expressions with if statements and while loops. - -This model of execution, where the runtime alternates between regular -expression matching and user code execution places restrictions on when -action code may be executed. Since action code can only be associated with -complete patterns, any action code that must be executed before an entire -pattern is matched requires that the pattern be broken into smaller units. -Instead of being forced to disrupt the regular expression syntax and write -smaller expressions, it is desirable to retain a single expression and embed -code for performing actions directly into the transitions that move over the -characters. After all, capable programmers are astutely aware of the machinery -underlying their programs, so why not provide them with access to that -machinery? To achieve this, we require an action execution model for associating -code with the sub-expressions of a regular expression in a way that does not -disrupt its syntax. - -The primary goal of Ragel is to provide developers with an ability to embed -actions into the transitions and states of a regular expression's state machine -in support of the definition of entire parsers or large sections of parsers -using a single regular expression. From the regular expression we gain a clear -and concise statement of our language. From the state machine we obtain a very -fast and robust executable that lends itself to many kinds of analysis and -visualization. - -\section{Overview} - -Ragel is a language for specifying state machines. The Ragel program is a -compiler that assembles a state machine definition to executable code. Ragel -is based on the principle that any regular language can be converted to a -deterministic finite state automaton. Since every regular language has a state -machine representation and vice versa, the terms regular language and state -machine (or just machine) will be used interchangeably in this document. - -Ragel outputs machines to C, C++, Objective-C, D, Go, Java, Ruby or OCaml code. The output is -designed to be generic and is not bound to any particular input or processing -method. A Ragel machine expects to have data passed to it in buffer blocks. -When there is no more input, the machine can be queried for acceptance. In -this way, a Ragel machine can be used to simply recognize a regular language -like a regular expression library. By embedding code into the regular language, -a Ragel machine can also be used to parse input. - -The Ragel language has many operators for constructing and manipulating -machines. Machines are built up from smaller machines, to bigger ones, to the -final machine representing the language that needs to be recognized or parsed. - -The core state machine construction operators are those found in most theory -of computation textbooks. They date back to the 1950s and are widely studied. -They are based on set operations and permit one to think of languages as a set -of strings. They are Union, Intersection, Difference, Concatenation and Kleene -Star. Put together, these operators make up what most people know as regular -expressions. Ragel also provides a scanner construction operator -and provides operators for explicitly constructing machines -using a state chart method. In the state chart method, one joins machines -together without any implied transitions and then explicitly specifies where -epsilon transitions should be drawn. - -The state machine manipulation operators are specific to Ragel. They allow the -programmer to access the states and transitions of regular language's -corresponding machine. There are two uses of the manipulation operators. The -first and primary use is to embed code into transitions and states, allowing -the programmer to specify the actions of the state machine. - -Ragel attempts to make the action embedding facility as intuitive as possible. -To do so, a number of issues need to be addressed. For example, when making a -nondeterministic specification into a DFA using machines that have embedded -actions, new transitions are often made that have the combined actions of -several source transitions. Ragel ensures that multiple actions associated with -a single transition are ordered consistently with respect to the order of -reference and the natural ordering implied by the construction operators. - -The second use of the manipulation operators is to assign priorities to -transitions. Priorities provide a convenient way of controlling any -nondeterminism introduced by the construction operators. Suppose two -transitions leave from the same state and go to distinct target states on the -same character. If these transitions are assigned conflicting priorities, then -during the determinization process the transition with the higher priority will -take precedence over the transition with the lower priority. The lower priority -transition gets abandoned. The transitions would otherwise be combined into a new -transition that goes to a new state that is a combination of the original -target states. Priorities are often required for segmenting machines. The most -common uses of priorities have been encoded into a set of simple operators -that should be used instead of priority embeddings whenever possible. - -For the purposes of embedding, Ragel divides transitions and states into -different classes. There are four operators for embedding actions and -priorities into the transitions of a state machine. It is possible to embed -into entering transitions, finishing transitions, all transitions and leaving -transitions. The embedding into leaving transitions is a special case. -These transition embeddings get stored in the final states of a machine. They -are transferred to any transitions that are made going out of the machine by -future concatenation or kleene star operations. - -There are several more operators for embedding actions into states. Like the -transition embeddings, there are various different classes of states that the -embedding operators access. For example, one can access start states, final -states or all states, among others. Unlike the transition embeddings, there are -several different types of state action embeddings. These are executed at -various different times during the processing of input. It is possible to embed -actions that are executed on transitions into a state, on transitions out of a -state, on transitions taken on the error event, or on transitions taken on the -EOF event. - -Within actions, it is possible to influence the behaviour of the state machine. -The user can write action code that jumps or calls to another portion of the -machine, changes the current character being processed, or breaks out of the -processing loop. With the state machine calling feature Ragel can be used to -parse languages that are not regular. For example, one can parse balanced -parentheses by calling into a parser when an open parenthesis character is seen -and returning to the state on the top of the stack when the corresponding -closing parenthesis character is seen. More complicated context-free languages -such as expressions in C are out of the scope of Ragel. - -Ragel also provides a scanner construction operator that can be used to build -scanners much the same way that Lex is used. The Ragel generated code, which -relies on user-defined variables for backtracking, repeatedly tries to match -patterns to the input, favouring longer patterns over shorter ones and patterns -that appear ahead of others when the lengths of the possible matches are -identical. When a pattern is matched the associated action is executed. - -The key distinguishing feature between scanners in Ragel and scanners in Lex is -that Ragel patterns may be arbitrary Ragel expressions and can therefore -contain embedded code. With a Ragel-based scanner the user need not wait until -the end of a pattern before user code can be executed. - -Scanners do take Ragel out of the domain of pure state machines and require the -user to maintain the backtracking related variables. However, scanners -integrate well with regular state machine instantiations. They can be called to -or jumped to only when needed, or they can be called out of or jumped out of -when a simpler, pure state machine model is appropriate. - -Two types of output code style are available. Ragel can produce a table-driven -machine or a directly executable machine. The directly executable machine is -much faster than the table-driven. On the other hand, the table-driven machine -is more compact and less demanding on the host language compiler. It is better -suited to compiling large state machines. - -\section{Related Work} - -Lex is perhaps the best-known tool for constructing parsers from regular -expressions. In the Lex processing model, generated code attempts to match one -of the user's regular expression patterns, favouring longer matches over -shorter ones. Once a match is made it then executes the code associated with -the pattern and consumes the matching string. This process is repeated until -the input is fully consumed. - -Through the use of start conditions, related sets of patterns may be defined. -The active set may be changed at any time. This allows the user to define -different lexical regions. It also allows the user to link patterns together by -requiring that some patterns come before others. This is quite like a -concatenation operation. However, use of Lex for languages that require a -considerable amount of pattern concatenation is inappropriate. In such cases a -Lex program deteriorates into a manually specified state machine, where start -conditions define the states and pattern actions define the transitions. Lex -is therefore best suited to parsing tasks where the language to be parsed can -be described in terms of regions of tokens. - -Lex is useful in many scenarios and has undoubtedly stood the test of time. -There are, however, several drawbacks to using Lex. Lex can impose too much -overhead for parsing applications where buffering is not required because all -the characters are available in a single string. In these cases there is -structure to the language to be parsed and a parser specification tool can -help, but employing a heavyweight processing loop that imposes a stream -``pull'' model and dynamic input buffer allocation is inappropriate. An -example of this kind of scenario is the conversion of floating point numbers -contained in a string to their corresponding numerical values. - -Another drawback is the very issue that Ragel attempts to solve. -It is not possible to execute a user action while -matching a character contained inside a pattern. For example, if scanning a -programming language and string literals can contain newlines which must be -counted, a Lex user must break up a string literal pattern so as to associate -an action with newlines. This forces the definition of a new start condition. -Alternatively the user can reprocess the text of the matched string literal to -count newlines. - - -The Re2C program defines an input processing model similar to that of Lex. -Re2C focuses on making generated state machines run very fast and -integrate easily into any program, free of dependencies. Re2C generates -directly executable code and is able to claim that generated parsers run nearly -as fast as their hand-coded equivalents. This is very important for user -adoption, as programmers are reluctant to use a tool when a faster alternative -exists. A consideration to ease of use is also important because developers -need the freedom to integrate the generated code as they see fit. - -Many scripting languages provide ways of composing parsers by linking regular -expressions using program logic. For example, Sed and Awk are two established -Unix scripting tools that allow the programmer to exploit regular expressions -for the purpose of locating and extracting text of interest. High-level -programming languages such as Perl, Python, PHP and Ruby all provide regular -expression libraries that allow the user to combine regular expressions with -arbitrary code. - -In addition to supporting the linking of regular expressions with arbitrary -program logic, the Perl programming language permits the embedding of code into -regular expressions. Perl embeddings do not translate into the embedding of -code into deterministic state machines. Perl regular expressions are in fact -not fully compiled to deterministic machines when embedded code is involved. -They are instead interpreted and involve backtracking. This is shown by the -following Perl program. When it is fed the input \verb|abcd| the interpreter -attempts to match the first alternative, printing \verb|a1 b1|. When this -possibility fails it backtracks and tries the second possibility, printing -\verb|a2 b2|, at which point it succeeds. - -\begin{inline_code} -\begin{verbatim} -print "YES\n" if ( <STDIN> =~ - /( a (?{ print "a1 "; }) b (?{ print "b1 "; }) cX ) | - ( a (?{ print "a2 "; }) b (?{ print "b2 "; }) cd )/x ) -\end{verbatim} -\end{inline_code} -\verbspace - -In Ragel there is no regular expression interpreter. Aside from the scanner -operator, all Ragel expressions are made into deterministic machines and the -run time simply moves from state to state as it consumes input. An equivalent -parser expressed in Ragel would attempt both of the alternatives concurrently, -printing \verb|a1 a2 b1 b2|. - -\section{Development Status} - -Ragel is a relatively new tool and is under continuous development. As a rough -release guide, minor revision number changes are for implementation -improvements and feature additions. Major revision number changes are for -implementation and language changes that do not preserve backwards -compatibility. Though in the past this has not always held true: changes that -break code have crept into minor version number changes. Typically, the -documentation lags behind the development in the interest of documenting only -the lasting features. The latest changes are always documented in the ChangeLog -file. - -\chapter{Constructing State Machines} - -\section{Ragel State Machine Specifications} - -A Ragel input file consists of a program in the host language that contains embedded machine -specifications. Ragel normally passes input straight to output. When it sees -a machine specification it stops to read the Ragel statements and possibly generate -code in place of the specification. -Afterwards it continues to pass input through. There -can be any number of FSM specifications in an input file. A multi-line FSM spec -starts with \verb|%%{| and ends with \verb|}%%|. A single-line FSM spec starts -with \verb|%%| and ends at the first newline. - -While Ragel is looking for FSM specifications it does basic lexical analysis on -the surrounding input. It interprets literal strings and comments so a -\verb|%%| sequence in either of those will not trigger the parsing of an FSM -specification. Ragel does not pass the input through any preprocessor nor does it -interpret preprocessor directives itself so includes, defines and ifdef logic -cannot be used to alter the parse of a Ragel input file. It is therefore not -possible to use an \verb|#if 0| directive to comment out a machine as is -commonly done in C code. As an alternative, a machine can be prevented from -causing any generated output by commenting out write statements. - -In Figure \ref{cmd-line-parsing}, a multi-line specification is used to define the -machine and single line specifications are used to trigger the writing of the machine -data and execution code. - -\begin{figure} -\small -\begin{multicols}{2} -\begin{verbatim} -#include <string.h> -#include <stdio.h> - -%%{ - machine foo; - main := - ( 'foo' | 'bar' ) - 0 @{ res = 1; }; -}%% - -%% write data; -\end{verbatim} -\verbspace -\columnbreak -\begin{verbatim} -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; -} -\end{verbatim} -\verbspace -\end{multicols} -\caption{Parsing a command line argument. -} -\label{cmd-line-parsing} -\end{figure} - -\subsection{Naming Ragel Blocks} - -\begin{verbatim} -machine fsm_name; -\end{verbatim} -\verbspace - -The \verb|machine| statement gives the name of the FSM. If present in a -specification, this statement must appear first. If a machine specification -does not have a name then Ragel uses the previous specification name. If no -previous specification name exists then this is an error. Because FSM -specifications persist in memory, a machine's statements can be spread across -multiple machine specifications. This allows one to break up a machine across -several files or draw in statements that are common to multiple machines using -the \verb|include| statement. - -\subsection{Machine Definition} -\label{definition} - -\begin{verbatim} -<name> = <expression>; -\end{verbatim} -\verbspace - -The machine definition statement associates an FSM expression with a name. Machine -expressions assigned to names can later be referenced in other expressions. A -definition statement on its own does not cause any states to be generated. It is simply a -description of a machine to be used later. States are generated only when a definition is -instantiated, which happens when a definition is referenced in an instantiated -expression. - -\subsection{Machine Instantiation} -\label{instantiation} - -\begin{verbatim} -<name> := <expression>; -\end{verbatim} -\verbspace - -The machine instantiation statement generates a set of states representing an -expression. Each instantiation generates a distinct set of states. The starting -state of the instantiation is written in the data section of the generated code -using the instantiation name. If a machine named -\verb|main| is instantiated, its start state is used as the -specification's start state and is assigned to the \verb|cs| variable by the -\verb|write init| command. If no \verb|main| machine is given, the start state -of the last machine instantiation to appear is used as the specification's -start state. - -From outside the execution loop, control may be passed to any machine by -assigning the entry point to the \verb|cs| variable. From inside the execution -loop, control may be passed to any machine instantiation using \verb|fcall|, -\verb|fgoto| or \verb|fnext| statements. - -\subsection{Including Ragel Code} - -\begin{verbatim} -include FsmName "inputfile.rl"; -\end{verbatim} -\verbspace - -The \verb|include| statement can be used to draw in the statements of another FSM -specification. Both the name and input file are optional, however at least one -must be given. Without an FSM name, the given input file is searched for an FSM -of the same name as the current specification. Without an input file, the -current file is searched for a machine of the given name. If both are present, -the given input file is searched for a machine of the given name. - -Ragel searches for included files from the location of the current file. -Additional directories can be added to the search path using the \verb|-I| -option. - -\subsection{Importing Definitions} -\label{import} - -\begin{verbatim} -import "inputfile.h"; -\end{verbatim} -\verbspace - -The \verb|import| statement scrapes a file for sequences of tokens that match -the following forms. Ragel treats these forms as state machine definitions. - -\noindent\hspace*{24pt}\verb|name '=' number|\\ -\noindent\hspace*{24pt}\verb|name '=' lit_string|\\ -\noindent\hspace*{24pt}\verb|'define' name number|\\ -\noindent\hspace*{24pt}\verb|'define' name lit_string| -\vspace{12pt} - -If the input file is a Ragel program then tokens inside any Ragel -specifications are ignored. See Section \ref{export} for a description of -exporting machine definitions. - -Ragel searches for imported files from the location of the current file. -Additional directories can be added to the search path using the \verb|-I| -option. - -\section{Lexical Analysis of a Ragel Block} -\label{lexing} - -Within a machine specification the following lexical rules apply to the input. - -\begin{itemize} - -\item The \verb|#| symbol begins a comment that terminates at the next newline. - -\item The symbols \verb|""|, \verb|''|, \verb|//|, \verb|[]| behave as the -delimiters of literal strings. Within them, the following escape sequences -are interpreted: - -\verb| \0 \a \b \t \n \v \f \r| - -A backslash at the end of a line joins the following line onto the current. A -backslash preceding any other character removes special meaning. This applies -to terminating characters and to special characters in regular expression -literals. As an exception, regular expression literals do not support escape -sequences as the operands of a range within a list. See the bullet on regular -expressions in Section \ref{basic}. - -\item The symbols \verb|{}| delimit a block of host language code that will be -embedded into the machine as an action. Within the block of host language -code, basic lexical analysis of comments and strings is done in order to -correctly find the closing brace of the block. With the exception of FSM -commands embedded in code blocks, the entire block is preserved as is for -identical reproduction in the output code. - -\item The pattern \verb|[+-]?[0-9]+| denotes an integer in decimal format. -Integers used for specifying machines may be negative only if the alphabet type -is signed. Integers used for specifying priorities may be positive or negative. - -\item The pattern \verb|0x[0-9A-Fa-f]+| denotes an integer in hexadecimal -format. - -\item The keywords are \verb|access|, \verb|action|, \verb|alphtype|, -\verb|getkey|, \verb|write|, \verb|machine| and \verb|include|. - -\item The pattern \verb|[a-zA-Z_][a-zA-Z_0-9]*| denotes an identifier. - - -\item Any amount of whitespace may separate tokens. - -\end{itemize} - - -\section{Basic Machines} -\label{basic} - -The basic machines are the base operands of regular language expressions. They -are the smallest unit to which machine construction and manipulation operators -can be applied. - -\begin{itemize} - -\item \verb|'hello'| -- Concatenation Literal. Produces a machine that matches -the sequence of characters in the quoted string. If there are 5 characters -there will be 6 states chained together with the characters in the string. See -Section \ref{lexing} for information on valid escape sequences. - - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{bmconcat} -\end{center} -\graphspace - -It is possible -to make a concatenation literal case-insensitive by appending an \verb|i| to -the string, for example \verb|'cmd'i|. - -\item \verb|"hello"| -- Identical to the single quoted version. - -\item \verb|[hello]| -- Or Expression. Produces a union of characters. There -will be two states with a transition for each unique character between the two states. -The \verb|[]| delimiters behave like the quotes of a literal string. For example, -\verb|[ \t]| means tab or space. The \verb|or| expression supports character ranges -with the \verb|-| symbol as a separator. The meaning of the union can be negated -using an initial \verb|^| character as in standard regular expressions. -See Section \ref{lexing} for information on valid escape sequences -in \verb|or| expressions. - - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{bmor} -\end{center} -\graphspace - -\item \verb|''|, \verb|""|, and \verb|[]| -- Zero Length Machine. Produces a machine -that matches the zero length string. Zero length machines have one state that is both -a start state and a final state. - - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{bmnull} -\end{center} -\graphspace - -% FIXME: More on the range of values here. -\item \verb|42| -- Numerical Literal. Produces a two state machine with one -transition on the given number. The number may be in decimal or hexadecimal -format and should be in the range allowed by the alphabet type. The minimum and -maximum values permitted are defined by the host machine that Ragel is compiled -on. For example, numbers in a \verb|short| alphabet on an i386 machine should -be in the range \verb|-32768| to \verb|32767|. - - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{bmnum} -\end{center} -\graphspace - -\item \verb|/simple_regex/| -- Regular Expression. Regular expressions are -parsed as a series of expressions that are concatenated together. Each -concatenated expression -may be a literal character, the ``any'' character specified by the \verb|.| -symbol, or a union of characters specified by the \verb|[]| delimiters. If the -first character of a union is \verb|^| then it matches any character not in the -list. Within a union, a range of characters can be given by separating the first -and last characters of the range with the \verb|-| symbol. Each -concatenated machine may have repetition specified by following it with the -\verb|*| symbol. The standard escape sequences described in Section -\ref{lexing} are supported everywhere in regular expressions except as the -operands of a range within in a list. This notation also supports the \verb|i| -trailing option. Use it to produce case-insensitive machines, as in \verb|/GET/i|. - -Ragel does not support very complex regular expressions because the desired -results can always be achieved using the more general machine construction -operators listed in Section \ref{machconst}. The following diagram shows the -result of compiling \verb|/ab*[c-z].*[123]/|. \verb|DEF| represents the default -transition, which is taken if no other transition can be taken. - - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{bmregex} -\end{center} -\graphspace - -\item \verb|'a' .. 'z'| -- Range. Produces a machine that matches any -characters in the specified range. Allowable upper and lower bounds of the -range are concatenation literals of length one and numerical literals. For -example, \verb|0x10..0x20|, \verb|0..63|, and \verb|'a'..'z'| are valid ranges. -The bounds should be in the range allowed by the alphabet type. - - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{bmrange} -\end{center} -\graphspace - -\item \verb|variable_name| -- Lookup the machine definition assigned to the -variable name given and use an instance of it. See Section \ref{definition} for -an important note on what it means to reference a variable name. - -\item \verb|builtin_machine| -- There are several built-in machines available -for use. They are all two state machines for the purpose of matching common -classes of characters. They are: - -\begin{itemize} - -\item \verb|any | -- Any character in the alphabet. - -\item \verb|ascii | -- Ascii characters. \verb|0..127| - -\item \verb|extend| -- Ascii extended characters. This is the range -\verb|-128..127| for signed alphabets and the range \verb|0..255| for unsigned -alphabets. - -\item \verb|alpha | -- Alphabetic characters. \verb|[A-Za-z]| - -\item \verb|digit | -- Digits. \verb|[0-9]| - -\item \verb|alnum | -- Alpha numerics. \verb|[0-9A-Za-z]| - -\item \verb|lower | -- Lowercase characters. \verb|[a-z]| - -\item \verb|upper | -- Uppercase characters. \verb|[A-Z]| - -\item \verb|xdigit| -- Hexadecimal digits. \verb|[0-9A-Fa-f]| - -\item \verb|cntrl | -- Control characters. \verb|0..31|, \verb|127| - -\item \verb|graph | -- Graphical characters. \verb|[!-~]| - -\item \verb|print | -- Printable characters. \verb|[ -~]| - -\item \verb|punct | -- Punctuation. Graphical characters that are not alphanumerics. -\verb|[!-/:-@[-`{-~]| - -\item \verb|space | -- Whitespace. \verb|[\t\v\f\n\r ]| - -\item \verb|zlen | -- Zero length string. \verb|""| - -\item \verb|empty | -- Empty set. Matches nothing. \verb|^any| - -\end{itemize} -\end{itemize} - -\section{Operator Precedence} -The following table shows operator precedence from lowest to highest. Operators -in the same precedence group are evaluated from left to right. - -\begin{tabular}{|c|c|c|} -\hline -1&\verb| , |&Join\\ -\hline -2&\verb/ | & - --/&Union, Intersection and Subtraction\\ -\hline -3&\verb| . <: :> :>> |&Concatenation\\ -\hline -4&\verb| : |&Label\\ -\hline -5&\verb| -> |&Epsilon Transition\\ -\hline -6&\verb| > @ $ % |&Transitions Actions and Priorities\\ -\hline -6&\verb| >/ $/ %/ </ @/ <>/ |&EOF Actions\\ -\hline -6&\verb| >! $! %! <! @! <>! |&Global Error Actions\\ -\hline -6&\verb| >^ $^ %^ <^ @^ <>^ |&Local Error Actions\\ -\hline -6&\verb| >~ $~ %~ <~ @~ <>~ |&To-State Actions\\ -\hline -6&\verb| >* $* %* <* @* <>* |&From-State Action\\ -\hline -7&\verb| * ** ? + {n} {,n} {n,} {n,m} |&Repetition\\ -\hline -8&\verb| ! ^ |&Negation and Character-Level Negation\\ -\hline -9&\verb| ( <expr> ) |&Grouping\\ -\hline -\end{tabular} - -\section{Regular Language Operators} -\label{machconst} - -When using Ragel it is helpful to have a sense of how it constructs machines. -The determinization process can produce results that seem unusual to someone -not familiar with the NFA to DFA conversion algorithm. In this section we -describe Ragel's state machine operators. Though the operators are defined -using epsilon transitions, it should be noted that this is for discussion only. -The epsilon transitions described in this section do not persist, but are -immediately removed by the determinization process which is executed at every -operation. Ragel does not make use of any nondeterministic intermediate state -machines. - -To create an epsilon transition between two states \verb|x| and \verb|y| is to -copy all of the properties of \verb|y| into \verb|x|. This involves drawing in -all of \verb|y|'s to-state actions, EOF actions, etc., in addition to its -transitions. If \verb|x| and \verb|y| both have a transition out on the same -character, then the transitions must be combined. During transition -combination a new transition is made that goes to a new state that is the -combination of both target states. The new combination state is created using -the same epsilon transition method. The new state has an epsilon transition -drawn to all the states that compose it. Since the creation of new epsilon -transitions may be triggered every time an epsilon transition is drawn, the -process of drawing epsilon transitions is repeated until there are no more -epsilon transitions to be made. - -A very common error that is made when using Ragel is to make machines that do -too much. That is, to create machines that have unintentional -nondeterministic properties. This usually results from being unaware of the common strings -between machines that are combined together using the regular language -operators. This can involve never leaving a machine, causing its actions to be -propagated through all the following states. Or it can involve an alternation -where both branches are unintentionally taken simultaneously. - -This problem forces one to think hard about the language that needs to be -matched. To guard against this kind of problem one must ensure that the machine -specification is divided up using boundaries that do not allow ambiguities from -one portion of the machine to the next. See Chapter -\ref{controlling-nondeterminism} for more on this problem and how to solve it. - -The Graphviz tool is an immense help when debugging improperly compiled -machines or otherwise learning how to use Ragel. Graphviz Dot files can be -generated from Ragel programs using the \verb|-V| option. See Section -\ref{visualization} for more information. - - -\subsection{Union} - -\verb/expr | expr/ - -The union operation produces a machine that matches any string in machine one -or machine two. The operation first creates a new start state. Epsilon -transitions are drawn from the new start state to the start states of both -input machines. The resulting machine has a final state set equivalent to the -union of the final state sets of both input machines. In this operation, there -is the opportunity for nondeterminism among both branches. If there are -strings, or prefixes of strings that are matched by both machines then the new -machine will follow both parts of the alternation at once. The union operation is -shown below. - -\graphspace -\begin{center} -\includegraphics[scale=1.0]{opor} -\end{center} -\graphspace - -The following example demonstrates the union of three machines representing -common tokens. - -% GENERATE: exor -% OPT: -p -% %%{ -% machine exor; -\begin{inline_code} -\begin{verbatim} -# Hex digits, decimal digits, or identifiers -main := '0x' xdigit+ | digit+ | alpha alnum*; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exor} -\end{center} -\graphspace - -\subsection{Intersection} - -\verb|expr & expr| - -Intersection produces a machine that matches any -string that is in both machine one and machine two. To achieve intersection, a -union is performed on the two machines. After the result has been made -deterministic, any final state that is not a combination of final states from -both machines has its final state status revoked. To complete the operation, -paths that do not lead to a final state are pruned from the machine. Therefore, -if there are any such paths in either of the expressions they will be removed -by the intersection operator. Intersection can be used to require that two -independent patterns be simultaneously satisfied as in the following example. - -% GENERATE: exinter -% OPT: -p -% %%{ -% machine exinter; -\begin{inline_code} -\begin{verbatim} -# Match lines four characters wide that contain -# words separated by whitespace. -main := - /[^\n][^\n][^\n][^\n]\n/* & - (/[a-z][a-z]*/ | [ \n])**; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exinter} -\end{center} -\graphspace - -\subsection{Difference} - -\verb|expr - expr| - -The difference operation produces a machine that matches -strings that are in machine one but are not in machine two. To achieve subtraction, -a union is performed on the two machines. After the result has been made -deterministic, any final state that came from machine two or is a combination -of states involving a final state from machine two has its final state status -revoked. As with intersection, the operation is completed by pruning any path -that does not lead to a final state. The following example demonstrates the -use of subtraction to exclude specific cases from a set. - -% GENERATE: exsubtr -% OPT: -p -% %%{ -% machine exsubtr; -\begin{inline_code} -\begin{verbatim} -# Subtract keywords from identifiers. -main := /[a-z][a-z]*/ - ( 'for' | 'int' ); -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exsubtr} -\end{center} -\graphspace - -\subsection{Strong Difference} -\label{strong_difference} - -\verb|expr -- expr| - -Strong difference produces a machine that matches any string of the first -machine that does not have any string of the second machine as a substring. In -the following example, strong subtraction is used to excluded \verb|CRLF| from -a sequence. In the corresponding visualization, the label \verb|DEF| is short -for default. The default transition is taken if no other transition can be -taken. - -% GENERATE: exstrongsubtr -% OPT: -p -% %%{ -% machine exstrongsubtr; -\begin{inline_code} -\begin{verbatim} -crlf = '\r\n'; -main := [a-z]+ ':' ( any* -- crlf ) crlf; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exstrongsubtr} -\end{center} -\graphspace - -This operator is equivalent to the following. - -\begin{verbatim} -expr - ( any* expr any* ) -\end{verbatim} -\verbspace - -\subsection{Concatenation} - -\verb|expr . expr| - -Concatenation produces a machine that matches all the strings in machine one followed by all -the strings in machine two. Concatenation draws epsilon transitions from the -final states of the first machine to the start state of the second machine. The -final states of the first machine lose their final state status, unless the -start state of the second machine is final as well. -Concatenation is the default operator. Two machines next to each other with no -operator between them results in concatenation. - -\graphspace -\begin{center} -\includegraphics[scale=1.0]{opconcat} -\end{center} -\graphspace - -The opportunity for nondeterministic behaviour results from the possibility of -the final states of the first machine accepting a string that is also accepted -by the start state of the second machine. -The most common scenario in which this happens is the -concatenation of a machine that repeats some pattern with a machine that gives -a terminating string, but the repetition machine does not exclude the -terminating string. The example in Section \ref{strong_difference} -guards against this. Another example is the expression \verb|("'" any* "'")|. -When executed the thread of control will -never leave the \verb|any*| machine. This is a problem especially if actions -are embedded to process the characters of the \verb|any*| component. - -In the following example, the first machine is always active due to the -nondeterministic nature of concatenation. This particular nondeterminism is intended, -however, because we wish to permit EOF strings before the end of the input. - -% GENERATE: exconcat -% OPT: -p -% %%{ -% machine exconcat; -\begin{inline_code} -\begin{verbatim} -# Require an eof marker on the last line. -main := /[^\n]*\n/* . 'EOF\n'; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exconcat} -\end{center} -\graphspace - -There is a language -ambiguity involving concatenation and subtraction. Because concatenation is the -default operator for two -adjacent machines there is an ambiguity between subtraction of -a positive numerical literal and concatenation of a negative numerical literal. -For example, \verb|(x-7)| could be interpreted as \verb|(x . -7)| or -\verb|(x - 7)|. In the Ragel language, the subtraction operator always takes precedence -over concatenation of a negative literal. We adhere to the rule that the default -concatenation operator takes effect only when there are no other operators between -two machines. Beware of writing machines such as \verb|(any -1)| when what is -desired is a concatenation of \verb|any| and \verb|-1|. Instead write -\verb|(any . -1)| or \verb|(any (-1))|. If in doubt of the meaning of your program do not -rely on the default concatenation operator; always use the \verb|.| symbol. - - -\subsection{Kleene Star} - -\verb|expr*| - -The machine resulting from the Kleene Star operator will match zero or more -repetitions of the machine it is applied to. -It creates a new start state and an additional final -state. Epsilon transitions are drawn between the new start state and the old start -state, between the new start state and the new final state, and -between the final states of the machine and the new start state. After the -machine is made deterministic, the final states get all the -transitions of the start state. - -\graphspace -\begin{center} -\includegraphics[scale=1.0]{opstar} -\end{center} -\graphspace - -The possibility for nondeterministic behaviour arises if the final states have -transitions on any of the same characters as the start state. This is common -when applying kleene star to an alternation of tokens. Like the other problems -arising from nondeterministic behavior, this is discussed in more detail in Chapter -\ref{controlling-nondeterminism}. This particular problem can also be solved -by using the longest-match construction discussed in Section -\ref{generating-scanners} on scanners. - -In this -example, there is no nondeterminism introduced by the exterior kleene star due to -the newline at the end of the regular expression. Without the newline the -exterior kleene star would be redundant and there would be ambiguity between -repeating the inner range of the regular expression and the entire regular -expression. Though it would not cause a problem in this case, unnecessary -nondeterminism in the kleene star operator often causes undesired results for -new Ragel users and must be guarded against. - -% GENERATE: exstar -% OPT: -p -% %%{ -% machine exstar; -\begin{inline_code} -\begin{verbatim} -# Match any number of lines with only lowercase letters. -main := /[a-z]*\n/*; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exstar} -\end{center} -\graphspace - -\subsection{One Or More Repetition} - -\verb|expr+| - -This operator produces the concatenation of the machine with the kleene star of -itself. The result will match one or more repetitions of the machine. The plus -operator is equivalent to \verb|(expr . expr*)|. - -% GENERATE: explus -% OPT: -p -% %%{ -% machine explus; -\begin{inline_code} -\begin{verbatim} -# Match alpha-numeric words. -main := alnum+; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{explus} -\end{center} -\graphspace - -\subsection{Optional} - -\verb|expr?| - -The {\em optional} operator produces a machine that accepts the machine -given or the zero length string. The optional operator is equivalent to -\verb/(expr | '' )/. In the following example the optional operator is used to -possibly extend a token. - -% GENERATE: exoption -% OPT: -p -% %%{ -% machine exoption; -\begin{inline_code} -\begin{verbatim} -# Match integers or floats. -main := digit+ ('.' digit+)?; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exoption} -\end{center} -\graphspace - -\subsection{Repetition} - -\noindent\hspace*{24pt}\verb|expr {n}| -- Exactly N copies of expr.\\ -\noindent\hspace*{24pt}\verb|expr {,n}| -- Zero to N copies of expr.\\ -\noindent\hspace*{24pt}\verb|expr {n,}| -- N or more copies of expr.\\ -\noindent\hspace*{24pt}\verb|expr {n,m}| -- N to M copies of expr. -\vspace{12pt} - -\subsection{Negation} - -\verb|!expr| - -Negation produces a machine that matches any string not matched by the given -machine. Negation is equivalent to \verb|(any* - expr)|. - -% GENERATE: exnegate -% OPT: -p -% %%{ -% machine exnegate; -\begin{inline_code} -\begin{verbatim} -# Accept anything but a string beginning with a digit. -main := ! ( digit any* ); -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exnegate} -\end{center} -\graphspace - -\subsection{Character-Level Negation} - -\verb|^expr| - -Character-level negation produces a machine that matches any single character -not matched by the given machine. Character-Level Negation is equivalent to -\verb|(any - expr)|. It must be applied only to machines that match strings of -length one. - -\section{State Machine Minimization} - -State machine minimization is the process of finding the minimal equivalent FSM accepting -the language. Minimization reduces the number of states in machines -by merging equivalent states. It does not change the behaviour of the machine -in any way. It will cause some states to be merged into one because they are -functionally equivalent. State minimization is on by default. It can be turned -off with the \verb|-n| option. - -The algorithm implemented is similar to Hopcroft's state minimization -algorithm. Hopcroft's algorithm assumes a finite alphabet that can be listed in -memory, whereas Ragel supports arbitrary integer alphabets that cannot be -listed in memory. Though exact analysis is very difficult, Ragel minimization -runs close to O(n * log(n)) and requires O(n) temporary storage where -$n$ is the number of states. - -\section{Visualization} -\label{visualization} - -%In many cases, practical -%parsing programs will be too large to completely visualize with Graphviz. The -%proper approach is to reduce the language to the smallest subset possible that -%still exhibits the characteristics that one wishes to learn about or to fix. -%This can be done without modifying the source code using the \verb|-M| and -%\verb|-S| options. If a machine cannot be easily reduced, -%embeddings of unique actions can be very useful for tracing a -%particular component of a larger machine specification, since action names are -%written out on transition labels. - -Ragel is able to emit compiled state machines in Graphviz's Dot file format. -This is done using the \verb|-V| option. -Graphviz support allows users to perform -incremental visualization of their parsers. User actions are displayed on -transition labels of the graph. - -If the final graph is too large to be -meaningful, or even drawn, the user is able to inspect portions of the parser -by naming particular regular expression definitions with the \verb|-S| and -\verb|-M| options to the \verb|ragel| program. Use of Graphviz greatly -improves the Ragel programming experience. It allows users to learn Ragel by -experimentation and also to track down bugs caused by unintended -nondeterminism. - -Ragel has another option to help debugging. The \verb|-x| option causes Ragel -to emit the compiled machine in an XML format. - -\chapter{User Actions} - -Ragel permits the user to embed actions into the transitions of a regular -expression's corresponding state machine. These actions are executed when the -generated code moves over a transition. Like the regular expression operators, -the action embedding operators are fully compositional. They take a state -machine and an action as input, embed the action and yield a new state machine -that can be used in the construction of other machines. Due to the -compositional nature of embeddings, the user has complete freedom in the -placement of actions. - -A machine's transitions are categorized into four classes. The action embedding -operators access the transitions defined by these classes. The {\em entering -transition} operator \verb|>| isolates the start state, then embeds an action -into all transitions leaving it. The {\em finishing transition} operator -\verb|@| embeds an action into all transitions going into a final state. The -{\em all transition} operator \verb|$| embeds an action into all transitions of -an expression. The {\em leaving transition} operator \verb|%| provides access -to the yet-unmade transitions moving out of the machine via the final states. - -\section{Embedding Actions} - -\begin{verbatim} -action ActionName { - /* Code an action here. */ - count += 1; -} -\end{verbatim} -\verbspace - -The action statement defines a block of code that can be embedded into an FSM. -Action names can be referenced by the action embedding operators in -expressions. Though actions need not be named in this way (literal blocks -of code can be embedded directly when building machines), defining reusable -blocks of code whenever possible is good practice because it potentially increases the -degree to which the machine can be minimized. - -Within an action some Ragel expressions and statements are parsed and -translated. These allow the user to interact with the machine from action code. -See Section \ref{vals} for a complete list of statements and values available -in code blocks. - -\subsection{Entering Action} - -\verb|expr > action| - -The entering action operator embeds an action into all transitions -that enter into the machine from the start state. If the start state is final, -then the action is also embedded into the start state as a leaving action. This -means that if a machine accepts the zero-length string and control passes -through the start state then the entering action is executed. Note -that this can happen on both a following character and on the EOF event. - -In some machines, the start state has transtions coming in from within the -machine. In these cases the start state is first isolated from the rest of the -machine ensuring that the entering actions are executed once only. - -% GENERATE: exstact -% OPT: -p -% %%{ -% machine exstact; -\begin{inline_code} -\begin{verbatim} -# Execute A at the beginning of a string of alpha. -action A {} -main := ( lower* >A ) . ' '; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exstact} -\end{center} -\graphspace - -\subsection{Finishing Action} - -\verb|expr @ action| - -The finishing action operator embeds an action into any transitions that move -the machine into a final state. Further input may move the machine out of the -final state, but keep it in the machine. Therefore, finishing actions may be -executed more than once if a machine has any internal transitions out of a -final state. In the following example, the final state has no transitions out -and the finishing action is executed only once. - -% GENERATE: exdoneact -% OPT: -p -% %%{ -% machine exdoneact; -% action A {} -\begin{inline_code} -\begin{verbatim} -# Execute A when the trailing space is seen. -main := ( lower* ' ' ) @A; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exdoneact} -\end{center} -\graphspace - -\subsection{All Transition Action} - -\verb|expr $ action| - -The all transition operator embeds an action into all transitions of a machine. -The action is executed whenever a transition of the machine is taken. In the -following example, A is executed on every character matched. - -% GENERATE: exallact -% OPT: -p -% %%{ -% machine exallact; -% action A {} -\begin{inline_code} -\begin{verbatim} -# Execute A on any characters of the machine. -main := ( 'm1' | 'm2' ) $A; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exallact} -\end{center} -\graphspace - -\subsection{Leaving Actions} -\label{out-actions} - -\verb|expr % action| - -The leaving action operator queues an action for embedding into the transitions -that go out of a machine via a final state. The action is first stored in -the machine's final states and is later transferred to any transitions that are -made going out of the machine by a kleene star or concatenation operation. - -If a final state of the machine is still final when compilation is complete -then the leaving action is also embedded as an EOF action. Therefore, leaving -the machine is defined as either leaving on a character or as state machine -acceptance. - -This operator allows one to associate an action with the termination of a -sequence, without being concerned about what particular character terminates -the sequence. In the following example, A is executed when leaving the alpha -machine on the newline character. - -% GENERATE: exoutact1 -% OPT: -p -% %%{ -% machine exoutact1; -% action A {} -\begin{inline_code} -\begin{verbatim} -# Match a word followed by a newline. Execute A when -# finishing the word. -main := ( lower+ %A ) . '\n'; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exoutact1} -\end{center} -\graphspace - -In the following example, the \verb|term_word| action could be used to register -the appearance of a word and to clear the buffer that the \verb|lower| action used -to store the text of it. - -% GENERATE: exoutact2 -% OPT: -p -% %%{ -% machine exoutact2; -% action lower {} -% action space {} -% action term_word {} -% action newline {} -\begin{inline_code} -\begin{verbatim} -word = ( [a-z] @lower )+ %term_word; -main := word ( ' ' @space word )* '\n' @newline; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exoutact2} -\end{center} -\graphspace - -In this final example of the action embedding operators, A is executed upon entering -the alpha machine, B is executed on all transitions of the -alpha machine, C is executed when the alpha machine is exited by moving into the -newline machine and N is executed when the newline machine moves into a final -state. - -% GENERATE: exaction -% OPT: -p -% %%{ -% machine exaction; -% action A {} -% action B {} -% action C {} -% action N {} -\begin{inline_code} -\begin{verbatim} -# Execute A on starting the alpha machine, B on every transition -# moving through it and C upon finishing. Execute N on the newline. -main := ( lower* >A $B %C ) . '\n' @N; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{exaction} -\end{center} -\graphspace - - -\section{State Action Embedding Operators} - -The state embedding operators allow one to embed actions into states. Like the -transition embedding operators, there are several different classes of states -that the operators access. The meanings of the symbols are similar to the -meanings of the symbols used for the transition embedding operators. The design -of the state selections was driven by a need to cover the states of an -expression with exactly one error action. - -Unlike the transition embedding operators, the state embedding operators are -also distinguished by the different kinds of events that embedded actions can -be associated with. Therefore the state embedding operators have two -components. The first, which is the first one or two characters, specifies the -class of states that the action will be embedded into. The second component -specifies the type of event the action will be executed on. The symbols of the -second component also have equivalent keywords. - -\begin{multicols}{2} -The different classes of states are: - -\noindent\hspace*{24pt}\verb|> | -- the start state\\ -\noindent\hspace*{24pt}\verb|< | -- any state except the start state\\ -\noindent\hspace*{24pt}\verb|$ | -- all states\\ -\noindent\hspace*{24pt}\verb|% | -- final states\\ -\noindent\hspace*{24pt}\verb|@ | -- any state except final states\\ -\noindent\hspace*{24pt}\verb|<>| -- any except start and final (middle) -\vspace{12pt} - -\columnbreak - -The different kinds of embeddings are: - -\noindent\hspace*{24pt}\verb|~| -- to-state actions (\verb|to|)\\ -\noindent\hspace*{24pt}\verb|*| -- from-state actions (\verb|from|)\\ -\noindent\hspace*{24pt}\verb|/| -- EOF actions (\verb|eof|)\\ -\noindent\hspace*{24pt}\verb|!| -- error actions (\verb|err|)\\ -\noindent\hspace*{24pt}\verb|^| -- local error actions (\verb|lerr|) -\vspace{12pt} - -\end{multicols} - -\subsection{To-State and From-State Actions} - -\subsubsection{To-State Actions} - -\noindent\hspace*{24pt}\verb|>~action >to(name) >to{...} | -- the start state\\ -\noindent\hspace*{24pt}\verb|<~action <to(name) <to{...} | -- any state except the start state\\ -\noindent\hspace*{24pt}\verb|$~action $to(name) $to{...} | -- all states\\ -\noindent\hspace*{24pt}\verb|%~action %to(name) %to{...} | -- final states\\ -\noindent\hspace*{24pt}\verb|@~action @to(name) @to{...} | -- any state except final states\\ -\noindent\hspace*{24pt}\verb|<>~action <>to(name) <>to{...}| -- any except start and final (middle) -\vspace{12pt} - - -To-state actions are executed whenever the state machine moves into the -specified state, either by a natural movement over a transition or by an -action-based transfer of control such as \verb|fgoto|. They are executed after the -in-transition's actions but before the current character is advanced and -tested against the end of the input block. To-state embeddings stay with the -state. They are irrespective of the state's current set of transitions and any -future transitions that may be added in or out of the state. - -Note that the setting of the current state variable \verb|cs| outside of the -execute code is not considered by Ragel as moving into a state and consequently -the to-state actions of the new current state are not executed. This includes -the initialization of the current state when the machine begins. This is -because the entry point into the machine execution code is after the execution -of to-state actions. - -\subsubsection{From-State Actions} - -\noindent\hspace*{24pt}\verb|>*action >from(name) >from{...} | -- the start state\\ -\noindent\hspace*{24pt}\verb|<*action <from(name) <from{...} | -- any state except the start state\\ -\noindent\hspace*{24pt}\verb|$*action $from(name) $from{...} | -- all states\\ -\noindent\hspace*{24pt}\verb|%*action %from(name) %from{...} | -- final states\\ -\noindent\hspace*{24pt}\verb|@*action @from(name) @from{...} | -- any state except final states\\ -\noindent\hspace*{24pt}\verb|<>*action <>from(name) <>from{...}| -- any except start and final (middle) -\vspace{12pt} - -From-state actions are executed whenever the state machine takes a transition from a -state, either to itself or to some other state. These actions are executed -immediately after the current character is tested against the input block end -marker and before the transition to take is sought based on the current -character. From-state actions are therefore executed even if a transition -cannot be found and the machine moves into the error state. Like to-state -embeddings, from-state embeddings stay with the state. - -\subsection{EOF Actions} - -\noindent\hspace*{24pt}\verb|>/action >eof(name) >eof{...} | -- the start state\\ -\noindent\hspace*{24pt}\verb|</action <eof(name) <eof{...} | -- any state except the start state\\ -\noindent\hspace*{24pt}\verb|$/action $eof(name) $eof{...} | -- all states\\ -\noindent\hspace*{24pt}\verb|%/action %eof(name) %eof{...} | -- final states\\ -\noindent\hspace*{24pt}\verb|@/action @eof(name) @eof{...} | -- any state except final states\\ -\noindent\hspace*{24pt}\verb|<>/action <>eof(name) <>eof{...}| -- any except start and final (middle) -\vspace{12pt} - -The EOF action embedding operators enable the user to embed actions that are -executed at the end of the input stream. EOF actions are stored in states and -generated in the \verb|write exec| block. They are run when \verb|p == pe == eof| -as the execute block is finishing. EOF actions are free to adjust \verb|p| and -jump to another part of the machine to restart execution. - -\subsection{Handling Errors} - -In many applications it is useful to be able to react to parsing errors. The -user may wish to print an error message that depends on the context. It -may also be desirable to consume input in an attempt to return the input stream -to some known state and resume parsing. To support error handling and recovery, -Ragel provides error action embedding operators. There are two kinds of error -actions: global error actions and local error actions. -Error actions can be used to simply report errors, or by jumping to a machine -instantiation that consumes input, can attempt to recover from errors. - -\subsubsection{Global Error Actions} - -\noindent\hspace*{24pt}\verb|>!action >err(name) >err{...} | -- the start state\\ -\noindent\hspace*{24pt}\verb|<!action <err(name) <err{...} | -- any state except the start state\\ -\noindent\hspace*{24pt}\verb|$!action $err(name) $err{...} | -- all states\\ -\noindent\hspace*{24pt}\verb|%!action %err(name) %err{...} | -- final states\\ -\noindent\hspace*{24pt}\verb|@!action @err(name) @err{...} | -- any state except final states\\ -\noindent\hspace*{24pt}\verb|<>!action <>err(name) <>err{...}| -- any except start and final (middle) -\vspace{12pt} - -Global error actions are stored in the states they are embedded into until -compilation is complete. They are then transferred to the transitions that move -into the error state. These transitions are taken on all input characters that -are not already covered by the state's transitions. If a state with an error -action is not final when compilation is complete, then the action is also -embedded as an EOF action. - -Error actions can be used to recover from errors by jumping back into the -machine with \verb|fgoto| and optionally altering \verb|p|. - -\subsubsection{Local Error Actions} - -\noindent\hspace*{24pt}\verb|>^action >lerr(name) >lerr{...} | -- the start state\\ -\noindent\hspace*{24pt}\verb|<^action <lerr(name) <lerr{...} | -- any state except the start state\\ -\noindent\hspace*{24pt}\verb|$^action $lerr(name) $lerr{...} | -- all states\\ -\noindent\hspace*{24pt}\verb|%^action %lerr(name) %lerr{...} | -- final states\\ -\noindent\hspace*{24pt}\verb|@^action @lerr(name) @lerr{...} | -- any state except final states\\ -\noindent\hspace*{24pt}\verb|<>^action <>lerr(name) <>lerr{...}| -- any except start and final (middle) -\vspace{12pt} - -Like global error actions, local error actions are also stored in the states -they are embedded into until a transfer point. The transfer point is different -however. Each local error action embedding is associated with a name. When a -machine definition has been fully constructed, all local error action -embeddings associated with the same name as the machine definition are -transferred to the error transitions. At this time they are also embedded as -EOF actions in the case of non-final states. - -Local error actions can be used to specify an action to take when a particular -section of a larger state machine fails to match. A particular machine -definition's ``thread'' may die and the local error actions executed, however -the machine as a whole may continue to match input. - -There are two forms of local error action embeddings. In the first form the -name defaults to the current machine. In the second form the machine name can -be specified. This is useful when it is more convenient to specify the local -error action in a sub-definition that is used to construct the machine -definition that the local error action is associated with. To embed local -error actions and -explicitly state the machine definition on which the transfer is to happen use -\verb|(name, action)| as the action. - -\subsubsection{Example} - -The following example uses error actions to report an error and jump to a -machine that consumes the remainder of the line when parsing fails. After -consuming the line, the error recovery machine returns to the main loop. - -% GENERATE: erract -% %%{ -% machine erract; -% ws = ' '; -% address = 'foo AT bar..com'; -% date = 'Monday May 12'; -\begin{inline_code} -\begin{verbatim} -action cmd_err { - printf( "command error\n" ); - fhold; fgoto line; -} -action from_err { - printf( "from error\n" ); - fhold; fgoto line; -} -action to_err { - printf( "to error\n" ); - fhold; fgoto line; -} - -line := [^\n]* '\n' @{ fgoto main; }; - -main := ( - ( - 'from' @err(cmd_err) - ( ws+ address ws+ date '\n' ) $err(from_err) | - 'to' @err(cmd_err) - ( ws+ address '\n' ) $err(to_err) - ) -)*; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% %% write data; -% void f() -% { -% %% write init; -% %% write exec; -% } -% END GENERATE - - - -\section{Action Ordering and Duplicates} - -When combining expressions that have embedded actions it is often the case that -a number of actions must be executed on a single input character. For example, -following a concatenation the leaving action of the left expression and the -entering action of the right expression will be embedded into one transition. -This requires a method of ordering actions that is intuitive and -predictable for the user, and repeatable for the compiler. - -We associate with the embedding of each action a unique timestamp that is -used to order actions that appear together on a single transition in the final -state machine. To accomplish this, we recursively traverse the parse tree of -regular expressions and assign timestamps to action embeddings. References to -machine definitions are followed in the traversal. When we visit a -parse tree node, we assign timestamps to all {\em entering} action embeddings, -recurse on the parse tree, then assign timestamps to the remaining {\em all}, -{\em finishing}, and {\em leaving} embeddings in the order in which they -appear. - -By default Ragel does not permit a single action to appear multiple times in an action -list. When the final machine has been created, actions that appear more than -once in a single transition, to-state, from-state or EOF action list have their -duplicates removed. -The first appearance of the action is preserved. This is useful in a number of -scenarios. First, it allows us to union machines with common prefixes without -worrying about the action embeddings in the prefix being duplicated. Second, it -prevents leaving actions from being transferred multiple times. This can -happen when a machine is repeated, then followed with another machine that -begins with a common character. For example: - -\begin{verbatim} -word = [a-z]+ %act; -main := word ( '\n' word )* '\n\n'; -\end{verbatim} -\verbspace - -Note that Ragel does not compare action bodies to determine if they have -identical program text. It simply checks for duplicates using each action -block's unique location in the program. - -The removal of duplicates can be turned off using the \verb|-d| option. - -\section{Values and Statements Available in Code Blocks} -\label{vals} - -The following values are available in code blocks: - -\begin{itemize} -\item \verb|fpc| -- A pointer to the current character. This is equivalent to -accessing the \verb|p| variable. - -\item \verb|fc| -- The current character. This is equivalent to the expression \verb|(*p)|. - -\item \verb|fcurs| -- An integer value representing the current state. This -value should only be read from. To move to a different place in the machine -from action code use the \verb|fgoto|, \verb|fnext| or \verb|fcall| statements. -Outside of the machine execution code the \verb|cs| variable may be modified. - -\item \verb|ftargs| -- An integer value representing the target state. This -value should only be read from. Again, \verb|fgoto|, \verb|fnext| and -\verb|fcall| can be used to move to a specific entry point. - -\item \verb|fentry(<label>)| -- Retrieve an integer value representing the -entry point \verb|label|. The integer value returned will be a compile time -constant. This number is suitable for later use in control flow transfer -statements that take an expression. This value should not be compared against -the current state because any given label can have multiple states representing -it. The value returned by \verb|fentry| can be any one of the multiple states that -it represents. -\end{itemize} - -The following statements are available in code blocks: - -\begin{itemize} - -\item \verb|fhold;| -- Do not advance over the current character. If processing -data in multiple buffer blocks, the \verb|fhold| statement should only be used -once in the set of actions executed on a character. Multiple calls may result -in backing up over the beginning of the buffer block. The \verb|fhold| -statement does not imply any transfer of control. It is equivalent to the -\verb|p--;| statement. - -\item \verb|fexec <expr>;| -- Set the next character to process. This can be -used to backtrack to previous input or advance ahead. -Unlike \verb|fhold|, which can be used -anywhere, \verb|fexec| requires the user to ensure that the target of the -backtrack is in the current buffer block or is known to be somewhere ahead of -it. The machine will continue iterating forward until \verb|pe| is arrived at, -\verb|fbreak| is called or the machine moves into the error state. In actions -embedded into transitions, the \verb|fexec| statement is equivalent to setting -\verb|p| to one position ahead of the next character to process. If the user -also modifies \verb|pe|, it is possible to change the buffer block entirely. - -\item \verb|fgoto <label>;| -- Jump to an entry point defined by -\verb|<label>|. The \verb|fgoto| statement immediately transfers control to -the destination state. - -\item \verb|fgoto *<expr>;| -- Jump to an entry point given by \verb|<expr>|. -The expression must evaluate to an integer value representing a state. - -\item \verb|fnext <label>;| -- Set the next state to be the entry point defined -by \verb|label|. The \verb|fnext| statement does not immediately jump to the -specified state. Any action code following the statement is executed. - -\item \verb|fnext *<expr>;| -- Set the next state to be the entry point given -by \verb|<expr>|. The expression must evaluate to an integer value representing -a state. - -\item \verb|fcall <label>;| -- Push the target state and jump to the entry -point defined by \verb|<label>|. The next \verb|fret| will jump to the target -of the transition on which the call was made. Use of \verb|fcall| requires -the declaration of a call stack. An array of integers named \verb|stack| and a -single integer named \verb|top| must be declared. With the \verb|fcall| -construct, control is immediately transferred to the destination state. -See section \ref{modularization} for more information. - -\item \verb|fcall *<expr>;| -- Push the current state and jump to the entry -point given by \verb|<expr>|. The expression must evaluate to an integer value -representing a state. - -\item \verb|fret;| -- Return to the target state of the transition on which the -last \verb|fcall| was made. Use of \verb|fret| requires the declaration of a -call stack. Control is immediately transferred to the destination state. - -\item \verb|fbreak;| -- Advance \verb|p|, save the target state to \verb|cs| -and immediately break out of the execute loop. This statement is useful -in conjunction with the \verb|noend| write option. Rather than process input -until \verb|pe| is arrived at, the fbreak statement -can be used to stop processing from an action. After an \verb|fbreak| -statement the \verb|p| variable will point to the next character in the input. The -current state will be the target of the current transition. Note that \verb|fbreak| -causes the target state's to-state actions to be skipped. - -\end{itemize} - -Once actions with control-flow commands are embedded into a -machine, the user must exercise caution when using the machine as the operand -to other machine construction operators. If an action jumps to another state -then unioning any transition that executes that action with another transition -that follows some other path will cause that other path to be lost. Using -commands that manually jump around a machine takes us out of the domain of -regular languages because transitions that the -machine construction operators are not aware of are introduced. These -commands should therefore be used with caution. - - -\chapter{Controlling Nondeterminism} -\label{controlling-nondeterminism} - -Along with the flexibility of arbitrary action embeddings comes a need to -control nondeterminism in regular expressions. If a regular expression is -ambiguous, then sub-components of a parser other than the intended parts may become -active. This means that actions that are irrelevant to the -current subset of the parser may be executed, causing problems for the -programmer. - -Tools that are based on regular expression engines and that are used for -recognition tasks will usually function as intended regardless of the presence -of ambiguities. It is quite common for users of scripting languages to write -regular expressions that are heavily ambiguous and it generally does not -matter. As long as one of the potential matches is recognized, there can be any -number of other matches present. In some parsing systems the run-time engine -can employ a strategy for resolving ambiguities, for example always pursuing -the longest possible match and discarding others. - -In Ragel, there is no regular expression run-time engine, just a simple state -machine execution model. When we begin to embed actions and face the -possibility of spurious action execution, it becomes clear that controlling -nondeterminism at the machine construction level is very important. Consider -the following example. - -% GENERATE: lines1 -% OPT: -p -% %%{ -% machine lines1; -% action first {} -% action tail {} -% word = [a-z]+; -\begin{inline_code} -\begin{verbatim} -ws = [\n\t ]; -line = word $first ( ws word $tail )* '\n'; -lines = line*; -\end{verbatim} -\end{inline_code} -\verbspace -% main := lines; -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.53]{lines1} -\end{center} -\graphspace - -Since the \verb|ws| expression includes the newline character, we will -not finish the \verb|line| expression when a newline character is seen. We will -simultaneously pursue the possibility of matching further words on the same -line and the possibility of matching a second line. Evidence of this fact is -in the state tables. On several transitions both the \verb|first| and -\verb|tail| actions are executed. The solution here is simple: exclude -the newline character from the \verb|ws| expression. - -% GENERATE: lines2 -% OPT: -p -% %%{ -% machine lines2; -% action first {} -% action tail {} -% word = [a-z]+; -\begin{inline_code} -\begin{verbatim} -ws = [\t ]; -line = word $first ( ws word $tail )* '\n'; -lines = line*; -\end{verbatim} -\end{inline_code} -\verbspace -% main := lines; -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{lines2} -\end{center} -\graphspace - -Solving this kind of problem is straightforward when the ambiguity is created -by strings that are a single character long. When the ambiguity is created by -strings that are multiple characters long we have a more difficult problem. -The following example is an incorrect attempt at a regular expression for C -language comments. - -% GENERATE: comments1 -% OPT: -p -% %%{ -% machine comments1; -% action comm {} -\begin{inline_code} -\begin{verbatim} -comment = '/*' ( any @comm )* '*/'; -main := comment ' '; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{comments1} -\end{center} -\graphspace - -Using standard concatenation, we will never leave the \verb|any*| expression. -We will forever entertain the possibility that a \verb|'*/'| string that we see -is contained in a longer comment and that, simultaneously, the comment has -ended. The concatenation of the \verb|comment| machine with \verb|SP| is done -to show this. When we match space, we are also still matching the comment body. - -One way to approach the problem is to exclude the terminating string -from the \verb|any*| expression using set difference. We must be careful to -exclude not just the terminating string, but any string that contains it as a -substring. A verbose, but proper specification of a C comment parser is given -by the following regular expression. - -% GENERATE: comments2 -% OPT: -p -% %%{ -% machine comments2; -% action comm {} -\begin{inline_code} -\begin{verbatim} -comment = '/*' ( ( any @comm )* - ( any* '*/' any* ) ) '*/'; -\end{verbatim} -\end{inline_code} -\verbspace -% main := comment; -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{comments2} -\end{center} -\graphspace - -Note that Ragel's strong subtraction operator \verb|--| can also be used here. -In doing this subtraction we have phrased the problem of controlling non-determinism in -terms of excluding strings common to two expressions that interact when -combined. -We can also phrase the problem in terms of the transitions of the state -machines that implement these expressions. During the concatenation of -\verb|any*| and \verb|'*/'| we will be making transitions that are composed of -both the loop of the first expression and the final character of the second. -At this time we want the transition on the \verb|'/'| character to take precedence -over and disallow the transition that originated in the \verb|any*| loop. - -In another parsing problem, we wish to implement a lightweight tokenizer that we can -utilize in the composition of a larger machine. For example, some HTTP headers -have a token stream as a sub-language. The following example is an attempt -at a regular expression-based tokenizer that does not function correctly due to -unintended nondeterminism. - -% GENERATE: smallscanner -% OPT: -p -% %%{ -% machine smallscanner; -% action start_str {} -% action on_char {} -% action finish_str {} -\begin{inline_code} -\begin{verbatim} -header_contents = ( - lower+ >start_str $on_char %finish_str | - ' ' -)*; -\end{verbatim} -\end{inline_code} -\verbspace -% main := header_contents; -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{smallscanner} -\end{center} -\graphspace - -In this case, the problem with using a standard kleene star operation is that -there is an ambiguity between extending a token and wrapping around the machine -to begin a new token. Using the standard operator, we get an undesirable -nondeterministic behaviour. Evidence of this can be seen on the transition out -of state one, back to itself. The transition extends the string, and simultaneously, -finishes the string only to immediately begin a new one. What is required is -for the -transitions that represent an extension of a token to take precedence over the -transitions that represent the beginning of a new token. For this problem -there is no simple solution that uses standard regular expression operators. - -\section{Priorities} - -A priority mechanism was devised and built into the determinization -process, specifically for the purpose of allowing the user to control -nondeterminism. Priorities are integer values embedded into transitions. When -the determinization process is combining transitions that have different -priorities, the transition with the higher priority is preserved and the -transition with the lower priority is dropped. - -Unfortunately, priorities can have unintended side effects because their -operation requires that they linger in transitions indefinitely. They must linger -because the Ragel program cannot know when the user is finished with a priority -embedding. A solution whereby they are explicitly deleted after use is -conceivable; however this is not very user-friendly. Priorities were therefore -made into named entities. Only priorities with the same name are allowed to -interact. This allows any number of priorities to coexist in one machine for -the purpose of controlling various different regular expression operations and -eliminates the need to ever delete them. Such a scheme allows the user to -choose a unique name, embed two different priority values using that name -and be confident that the priority embedding will be free of any side effects. - -In the first form of priority embedding, the name defaults to the name of the machine -definition that the priority is assigned in. In this sense priorities are by -default local to the current machine definition or instantiation. Beware of -using this form in a longest-match machine, since there is only one name for -the entire set of longest match patterns. In the second form the priority's -name can be specified, allowing priority interaction across machine definition -boundaries. - -\begin{itemize} -\item \verb|expr > int| -- Sets starting transitions to have priority int. -\item \verb|expr @ int| -- Sets transitions that go into a final state to have priority int. -\item \verb|expr $ int| -- Sets all transitions to have priority int. -\item \verb|expr % int| -- Sets leaving transitions to -have priority int. When a transition is made going out of the machine (either -by concatenation or kleene star) its priority is immediately set to the -leaving priority. -\end{itemize} - -The second form of priority assignment allows the programmer to specify the name -to which the priority is assigned. - -\begin{itemize} -\item \verb|expr > (name, int)| -- Starting transitions. -\item \verb|expr @ (name, int)| -- Finishing transitions (into a final state). -\item \verb|expr $ (name, int)| -- All transitions. -\item \verb|expr % (name, int)| -- Leaving transitions. -\end{itemize} - -\section{Guarded Operators that Encapsulate Priorities} - -Priority embeddings are a very expressive mechanism. At the same time they -can be very confusing for the user. They force the user to imagine -the transitions inside two interacting expressions and work out the precise -effects of the operations between them. When we consider -that this problem is worsened by the -potential for side effects caused by unintended priority name collisions, we -see that exposing the user to priorities is undesirable. - -Fortunately, in practice the use of priorities has been necessary only in a -small number of scenarios. This allows us to encapsulate their functionality -into a small set of operators and fully hide them from the user. This is -advantageous from a language design point of view because it greatly simplifies -the design. - -Going back to the C comment example, we can now properly specify -it using a guarded concatenation operator which we call {\em finish-guarded -concatenation}. From the user's point of view, this operator terminates the -first machine when the second machine moves into a final state. It chooses a -unique name and uses it to embed a low priority into all -transitions of the first machine. A higher priority is then embedded into the -transitions of the second machine that enter into a final state. The following -example yields a machine identical to the example in Section -\ref{controlling-nondeterminism}. - -\begin{inline_code} -\begin{verbatim} -comment = '/*' ( any @comm )* :>> '*/'; -\end{verbatim} -\end{inline_code} -\verbspace - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{comments2} -\end{center} -\graphspace - -Another guarded operator is {\em left-guarded concatenation}, given by the -\verb|<:| compound symbol. This operator places a higher priority on all -transitions of the first machine. This is useful if one must forcibly separate -two lists that contain common elements. For example, one may need to tokenize a -stream, but first consume leading whitespace. - -Ragel also includes a {\em longest-match kleene star} operator, given by the -\verb|**| compound symbol. This -guarded operator embeds a high -priority into all transitions of the machine. -A lower priority is then embedded into the leaving transitions. When the -kleene star operator makes the epsilon transitions from -the final states into the new start state, the lower priority will be transferred -to the epsilon transitions. In cases where following an epsilon transition -out of a final state conflicts with an existing transition out of a final -state, the epsilon transition will be dropped. - -Other guarded operators are conceivable, such as guards on union that cause one -alternative to take precedence over another. These may be implemented when it -is clear they constitute a frequently used operation. -In the next section we discuss the explicit specification of state machines -using state charts. - -\subsection{Entry-Guarded Concatenation} - -\verb|expr :> expr| - -This operator concatenates two machines, but first assigns a low -priority to all transitions -of the first machine and a high priority to the starting transitions of the -second machine. This operator is useful if from the final states of the first -machine it is possible to accept the characters in the entering transitions of -the second machine. This operator effectively terminates the first machine -immediately upon starting the second machine, where otherwise they would be -pursued concurrently. In the following example, entry-guarded concatenation is -used to move out of a machine that matches everything at the first sign of an -end-of-input marker. - -% GENERATE: entryguard -% OPT: -p -% %%{ -% machine entryguard; -\begin{inline_code} -\begin{verbatim} -# Leave the catch-all machine on the first character of FIN. -main := any* :> 'FIN'; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{entryguard} -\end{center} -\graphspace - -Entry-guarded concatenation is equivalent to the following: - -\begin{verbatim} -expr $(unique_name,0) . expr >(unique_name,1) -\end{verbatim} -\verbspace - -\subsection{Finish-Guarded Concatenation} - -\verb|expr :>> expr| - -This operator is -like the previous operator, except the higher priority is placed on the final -transitions of the second machine. This is useful if one wishes to entertain -the possibility of continuing to match the first machine right up until the -second machine enters a final state. In other words, it terminates the first -machine only when the second accepts. In the following example, finish-guarded -concatenation causes the move out of the machine that matches everything to be -delayed until the full end-of-input marker has been matched. - -% GENERATE: finguard -% OPT: -p -% %%{ -% machine finguard; -\begin{inline_code} -\begin{verbatim} -# Leave the catch-all machine on the last character of FIN. -main := any* :>> 'FIN'; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{finguard} -\end{center} -\graphspace - -Finish-guarded concatenation is equivalent to the following, with one -exception. If the right machine's start state is final, the higher priority is -also embedded into it as a leaving priority. This prevents the left machine -from persisting via the zero-length string. - -\begin{verbatim} -expr $(unique_name,0) . expr @(unique_name,1) -\end{verbatim} -\verbspace - -\subsection{Left-Guarded Concatenation} - -\verb|expr <: expr| - -This operator places -a higher priority on the left expression. It is useful if you want to prefix a -sequence with another sequence composed of some of the same characters. For -example, one can consume leading whitespace before tokenizing a sequence of -whitespace-separated words as in: - -% GENERATE: leftguard -% OPT: -p -% %%{ -% machine leftguard; -% action alpha {} -% action ws {} -% action start {} -% action fin {} -\begin{inline_code} -\begin{verbatim} -main := ( ' '* >start %fin ) <: ( ' ' $ws | [a-z] $alpha )*; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{leftguard} -\end{center} -\graphspace - -Left-guarded concatenation is equivalent to the following: - -\begin{verbatim} -expr $(unique_name,1) . expr >(unique_name,0) -\end{verbatim} -\verbspace - -\subsection{Longest-Match Kleene Star} -\label{longest_match_kleene_star} - -\verb|expr**| - -This version of kleene star puts a higher priority on staying in the -machine versus wrapping around and starting over. The LM kleene star is useful -when writing simple tokenizers. These machines are built by applying the -longest-match kleene star to an alternation of token patterns, as in the -following. - -% GENERATE: lmkleene -% OPT: -p -% %%{ -% machine exfinpri; -% action A {} -% action B {} -\begin{inline_code} -\begin{verbatim} -# Repeat tokens, but make sure to get the longest match. -main := ( - lower ( lower | digit )* %A | - digit+ %B | - ' ' -)**; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{lmkleene} -\end{center} -\graphspace - -If a regular kleene star were used the machine above would not be able to -distinguish between extending a word and beginning a new one. This operator is -equivalent to: - -\begin{verbatim} -( expr $(unique_name,1) %(unique_name,0) )* -\end{verbatim} -\verbspace - -When the kleene star is applied, transitions that go out of the machine and -back into it are made. These are assigned a priority of zero by the leaving -transition mechanism. This is less than the priority of one assigned to the -transitions leaving the final states but not leaving the machine. When -these transitions clash on the same character, the -transition that stays in the machine takes precedence. The transition -that wraps around is dropped. - -Note that this operator does not build a scanner in the traditional sense -because there is never any backtracking. To build a scanner with backtracking -use the Longest-Match machine construction described in Section -\ref{generating-scanners}. - -\chapter{Interface to Host Program} - -The Ragel code generator is very flexible. The generated code has no -dependencies and can be inserted in any function, perhaps inside a loop if -desired. The user is responsible for declaring and initializing a number of -required variables, including the current state and the pointer to the input -stream. These can live in any scope. Control of the input processing loop is -also possible: the user may break out of the processing loop and return to it -at any time. - -In the case of the C, D, Go and OCaml host languages, Ragel is able to generate very -fast-running code that implements state machines as directly executable code. -Since very large files strain the host language compiler, table-based code -generation is also supported. In the future, we hope to provide a partitioned, -directly executable format that is able to reduce the burden on the host -compiler by splitting large machines across multiple functions. - -In the case of Java and Ruby, table-based code generation is the only code -style supported. In the future, this may be expanded to include other code -styles. - -Ragel can be used to parse input in one block, or it can be used to parse input -in a sequence of blocks as it arrives from a file or socket. Parsing the input -in a sequence of blocks brings with it a few responsibilities. If the parser -utilizes a scanner, care must be taken to not break the input stream anywhere -but token boundaries. If pointers to the input stream are taken during -parsing, care must be taken to not use a pointer that has been invalidated by -movement to a subsequent block. If the current input data pointer is moved -backwards it must not be moved past the beginning of the current block. - -Figure \ref{basic-example} shows a simple Ragel program that does not have any -actions. The example tests the first argument of the program against a number -pattern and then prints the machine's acceptance status. - -\begin{figure} -\small -\begin{verbatim} -#include <stdio.h> -#include <string.h> -%%{ - machine foo; - write data; -}%% -int main( int argc, char **argv ) -{ - int cs; - if ( argc > 1 ) { - char *p = argv[1]; - char *pe = p + strlen( p ); - %%{ - main := [0-9]+ ( '.' [0-9]+ )?; - - write init; - write exec; - }%% - } - printf("result = %i\n", cs >= foo_first_final ); - return 0; -} -\end{verbatim} -\verbspace -\caption{A basic Ragel example without any actions. -} -\label{basic-example} -\end{figure} - -\section{Variables Used by Ragel} - -There are a number of variables that Ragel expects the user to declare. At a -very minimum the \verb|cs|, \verb|p| and \verb|pe| variables must be declared. -In Go, Java, Ruby and OCaml code the \verb|data| variable must also be declared. If -EOF actions are used then the \verb|eof| variable is required. If -stack-based state machine control flow statements are used then the -\verb|stack| and \verb|top| variables are required. If a scanner is declared -then the \verb|act|, \verb|ts| and \verb|te| variables must be -declared. - -\begin{itemize} - -\item \verb|cs| - Current state. This must be an integer and it should persist -across invocations of the machine when the data is broken into blocks that are -processed independently. This variable may be modified from outside the -execution loop, but not from within. - -\item \verb|p| - Data pointer. In C/D code this variable is expected to be a -pointer to the character data to process. It should be initialized to the -beginning of the data block on every run of the machine. In Go, Java, Ruby and OCaml -it is used as an offset to \verb|data| and must be an integer. In this case it should -be initialized to zero on every run of the machine. - -\item \verb|pe| - Data end pointer. This should be initialized to \verb|p| plus -the data length on every run of the machine. In Go, Java, Ruby and OCaml code this should -be initialized to the data length. - -\item \verb|eof| - End of file pointer. This should be set to \verb|pe| when -the buffer block being processed is the last one, otherwise it should be set to -null. In Go, Java, Ruby and OCaml code \verb|-1| must be used instead of null. If the EOF -event can be known only after the final buffer block has been processed, then -it is possible to set \verb|p = pe = eof| and run the execute block. - -\item \verb|data| - This variable is only required in Go, Java, Ruby and OCaml code. It -must be an array containing the data to process. - -\item \verb|stack| - This must be an array of integers. It is used to store -integer values representing states. If the stack must resize dynamically the -Pre-push and Post-Pop statements can be used to do this (Sections -\ref{prepush} and \ref{postpop}). - -\item \verb|top| - This must be an integer value and will be used as an offset -to \verb|stack|, giving the next available spot on the top of the stack. - -\item \verb|act| - This must be an integer value. It is a variable sometimes -used by scanner code to keep track of the most recent successful pattern match. - -\item \verb|ts| - This must be a pointer to character data. In Go, Java, Ruby and -OCaml code this must be an integer. See Section \ref{generating-scanners} for -more information. - -\item \verb|te| - Also a pointer to character data. - -\end{itemize} - -\section{Alphtype Statement} - -\begin{verbatim} -alphtype unsigned int; -\end{verbatim} -\verbspace - -The alphtype statement specifies the alphabet data type that the machine -operates on. During the compilation of the machine, integer literals are -expected to be in the range of possible values of the alphtype. The default -is \verb|char| for all languages except Go where the default is \verb|byte| and -OCaml where the default is \verb|int|. - -\begin{multicols}{2} -C/C++/Objective-C: -\begin{verbatim} - char unsigned char - short unsigned short - int unsigned int - long unsigned long -\end{verbatim} -\verbspace - -Go: -\begin{verbatim} - byte - int8 uint8 - int16 uint16 - int32 uint32 - int -\end{verbatim} -\verbspace - -Ruby: -\begin{verbatim} - char - int -\end{verbatim} -\verbspace - -\columnbreak - -Java: -\begin{verbatim} - char - byte - short - int -\end{verbatim} -\verbspace - -D: -\begin{verbatim} - char - byte ubyte - short ushort - wchar - int uint - dchar -\end{verbatim} -\verbspace - -OCaml: -\begin{verbatim} - int -\end{verbatim} -\verbspace - -\end{multicols} - -\section{Getkey Statement} - -\begin{verbatim} -getkey fpc->id; -\end{verbatim} -\verbspace - -This statement specifies to Ragel how to retrieve the current character from -from the pointer to the current element (\verb|p|). Any expression that returns -a value of the alphabet type -may be used. The getkey statement may be used for looking into element -structures or for translating the character to process. The getkey expression -defaults to \verb|(*p)|. In goto-driven machines the getkey expression may be -evaluated more than once per element processed, therefore it should not incur a -large cost nor preclude optimization. - -\section{Access Statement} - -\begin{verbatim} -access fsm->; -\end{verbatim} -\verbspace - -The access statement specifies how the generated code should -access the machine data that is persistent across processing buffer blocks. -This applies to all variables except \verb|p|, \verb|pe| and \verb|eof|. This includes -\verb|cs|, \verb|top|, \verb|stack|, \verb|ts|, \verb|te| and \verb|act|. -The access statement is useful if a machine is to be encapsulated inside a -structure in C code. It can be used to give the name of -a pointer to the structure. - -\section{Variable Statement} - -\begin{verbatim} -variable p fsm->p; -\end{verbatim} -\verbspace - -The variable statement specifies how to access a specific -variable. All of the variables that are declared by the user and -used by Ragel can be changed. This includes \verb|p|, \verb|pe|, \verb|eof|, \verb|cs|, -\verb|top|, \verb|stack|, \verb|ts|, \verb|te| and \verb|act|. -In Go, Ruby, Java and OCaml code generation the \verb|data| variable can also be changed. - -\section{Pre-Push Statement} -\label{prepush} - -\begin{verbatim} -prepush { - /* stack growing code */ -} -\end{verbatim} -\verbspace - -The prepush statement allows the user to supply stack management code that is -written out during the generation of fcall, immediately before the current -state is pushed to the stack. This statement can be used to test the number of -available spaces and dynamically grow the stack if necessary. - -\section{Post-Pop Statement} -\label{postpop} - -\begin{verbatim} -postpop { - /* stack shrinking code */ -} -\end{verbatim} -\verbspace - -The postpop statement allows the user to supply stack management code that is -written out during the generation of fret, immediately after the next state is -popped from the stack. This statement can be used to dynamically shrink the -stack. - -\section{Write Statement} -\label{write-statement} - -\begin{verbatim} -write <component> [options]; -\end{verbatim} -\verbspace - -The write statement is used to generate parts of the machine. -There are seven -components that can be generated by a write statement. These components make up the -state machine's data, initialization code, execution code, and export definitions. -A write statement may appear before a machine is fully defined. -This allows one to write out the data first then later define the machine where -it is used. An example of this is shown in Figure \ref{fbreak-example}. - -\subsection{Write Data} -\begin{verbatim} -write data [options]; -\end{verbatim} -\verbspace - -The write data statement causes Ragel to emit the constant static data needed -by the machine. In table-driven output styles (see Section \ref{genout}) this -is a collection of arrays that represent the states and transitions of the -machine. In goto-driven machines much less data is emitted. At the very -minimum a start state \verb|name_start| is generated. All variables written -out in machine data have both the \verb|static| and \verb|const| properties and -are prefixed with the name of the machine and an -underscore. The data can be placed inside a class, inside a function, or it can -be defined as global data. - -Two variables are written that may be used to test the state of the machine -after a buffer block has been processed. The \verb|name_error| variable gives -the id of the state that the machine moves into when it cannot find a valid -transition to take. The machine immediately breaks out of the processing loop when -it finds itself in the error state. The error variable can be compared to the -current state to determine if the machine has failed to parse the input. If the -machine is complete, that is from every state there is a transition to a proper -state on every possible character of the alphabet, then no error state is required -and this variable will be set to -1. - -The \verb|name_first_final| variable stores the id of the first final state. -All of the machine's states are sorted by their final state status before -having their ids assigned. Checking if the machine has accepted its input can -then be done by checking if the current state is greater-than or equal to the -first final state. - -Data generation has several options: - -\noindent\hspace*{24pt}\verb|noerror | - Do not generate the integer variable that gives the id of the error state.\\ -\noindent\hspace*{24pt}\verb|nofinal | - Do not generate the integer variable that gives the id of the first final state.\\ -\noindent\hspace*{24pt}\verb|noprefix | - Do not prefix the variable names with the name of the machine. -\vspace{12pt} - -\begin{figure} -\small -\begin{verbatim} -#include <stdio.h> -%% machine foo; -%% write data; -int main( int argc, char **argv ) -{ - int cs, res = 0; - if ( argc > 1 ) { - char *p = argv[1]; - %%{ - main := - [a-z]+ - 0 @{ res = 1; fbreak; }; - write init; - write exec noend; - }%% - } - printf("execute = %i\n", res ); - return 0; -} -\end{verbatim} -\verbspace -\caption{Use of {\tt noend} write option and the {\tt fbreak} statement for -processing a string. -} -\label{fbreak-example} -\end{figure} - -\subsection{Write Start, First Final and Error} - -\begin{verbatim} -write start; -write first_final; -write error; -\end{verbatim} -\verbspace - -These three write statements provide an alternative means of accessing the -\verb|start|, \verb|first_final| and \verb|error| states. If there are many -different machine specifications in one file it is easy to get the prefix for -these wrong. This is especially true if the state machine boilerplate is -frequently made by a copy-paste-edit process. These write statements allow the -problem to be avoided. They can be used as follows: - -\begin{verbatim} -/* Did parsing succeed? */ -if ( cs < %%{ write first_final; }%% ) { - result = ERR_PARSE_ERROR; - goto fail; -} -\end{verbatim} -\verbspace - -\subsection{Write Init} -\begin{verbatim} -write init [options]; -\end{verbatim} -\verbspace - -The write init statement causes Ragel to emit initialization code. This should -be executed once before the machine is started. At a very minimum this sets the -current state to the start state. If other variables are needed by the -generated code, such as call stack variables or scanner management -variables, they are also initialized here. - -The \verb|nocs| option to the write init statement will cause ragel to skip -intialization of the cs variable. This is useful if the user wishes to use -custom logic to decide which state the specification should start in. - -\subsection{Write Exec} -\begin{verbatim} -write exec [options]; -\end{verbatim} -\verbspace - -The write exec statement causes Ragel to emit the state machine's execution code. -Ragel expects several variables to be available to this code. At a very minimum, the -generated code needs access to the current character position \verb|p|, the ending -position \verb|pe| and the current state \verb|cs| (though \verb|pe| -can be omitted using the \verb|noend| write option). -The \verb|p| variable is the cursor that the execute code will -used to traverse the input. The \verb|pe| variable should be set up to point to one -position past the last valid character in the buffer. - -Other variables are needed when certain features are used. For example using -the \verb|fcall| or \verb|fret| statements requires \verb|stack| and -\verb|top| variables to be defined. If a longest-match construction is used, -variables for managing backtracking are required. - -The write exec statement has one option. The \verb|noend| option tells Ragel -to generate code that ignores the end position \verb|pe|. In this -case the user must explicitly break out of the processing loop using -\verb|fbreak|, otherwise the machine will continue to process characters until -it moves into the error state. This option is useful if one wishes to process a -null terminated string. Rather than traverse the string to discover then length -before processing the input, the user can break out when the null character is -seen. The example in Figure \ref{fbreak-example} shows the use of the -\verb|noend| write option and the \verb|fbreak| statement for processing a string. - -\subsection{Write Exports} -\label{export} - -\begin{verbatim} -write exports; -\end{verbatim} -\verbspace - -The export feature can be used to export simple machine definitions. Machine definitions -are marked for export using the \verb|export| keyword. - -\begin{verbatim} -export machine_to_export = 0x44; -\end{verbatim} -\verbspace - -When the write exports statement is used these machines are -written out in the generated code. Defines are used for C and constant integers -are used for D, Java, Ruby and OCaml. See Section \ref{import} for a description of the -import statement. - -\section{Maintaining Pointers to Input Data} - -In the creation of any parser it is not uncommon to require the collection of -the data being parsed. It is always possible to collect data into a growable -buffer as the machine moves over it, however the copying of data is a somewhat -wasteful use of processor cycles. The most efficient way to collect data from -the parser is to set pointers into the input then later reference them. This -poses a problem for uses of Ragel where the input data arrives in blocks, such -as over a socket or from a file. If a pointer is set in one buffer block but -must be used while parsing a following buffer block, some extra consideration -to correctness must be made. - -The scanner constructions exhibit this problem, requiring the maintenance -code described in Section \ref{generating-scanners}. If a longest-match -construction has been used somewhere in the machine then it is possible to -take advantage of the required prefix maintenance code in the driver program to -ensure pointers to the input are always valid. If laying down a pointer one can -set \verb|ts| at the same spot or ahead of it. When data is shifted in -between loops the user must also shift the pointer. In this way it is possible -to maintain pointers to the input that will always be consistent. - -\begin{figure} -\small -\begin{verbatim} - int have = 0; - while ( 1 ) { - char *p, *pe, *data = buf + have; - int len, space = BUFSIZE - have; - - if ( space == 0 ) { - fprintf(stderr, "BUFFER OUT OF SPACE\n"); - exit(1); - } - - len = fread( data, 1, space, stdin ); - if ( len == 0 ) - break; - - /* Find the last newline by searching backwards. */ - p = buf; - pe = data + len - 1; - while ( *pe != '\n' && pe >= buf ) - pe--; - pe += 1; - - %% write exec; - - /* How much is still in the buffer? */ - have = data + len - pe; - if ( have > 0 ) - memmove( buf, pe, have ); - - if ( len < space ) - break; - } -\end{verbatim} -\verbspace -\caption{An example of line-oriented processing. -} -\label{line-oriented} -\end{figure} - -In general, there are two approaches for guaranteeing the consistency of -pointers to input data. The first approach is the one just described; -lay down a marker from an action, -then later ensure that the data the marker points to is preserved ahead of -the buffer on the next execute invocation. This approach is good because it -allows the parser to decide on the pointer-use boundaries, which can be -arbitrarily complex parsing conditions. A downside is that it requires any -pointers that are set to be corrected in between execute invocations. - -The alternative is to find the pointer-use boundaries before invoking the execute -routine, then pass in the data using these boundaries. For example, if the -program must perform line-oriented processing, the user can scan backwards from -the end of an input block that has just been read in and process only up to the -first found newline. On the next input read, the new data is placed after the -partially read line and processing continues from the beginning of the line. -An example of line-oriented processing is given in Figure \ref{line-oriented}. - -\section{Specifying the Host Language} - -The \verb|ragel| program has a number of options for specifying the host -language. The host-language options are: - -\begin{itemize} -\item \verb|-C | for C/C++/Objective-C code (default) -\item \verb|-D | for D code. -\item \verb|-Z | for Go code. -\item \verb|-J | for Java code. -\item \verb|-R | for Ruby code. -\item \verb|-A | for C\# code. -\item \verb|-O | for OCaml code. -\end{itemize} - -\section{Choosing a Generated Code Style} -\label{genout} - -There are three styles of code output to choose from. Code style affects the -size and speed of the compiled binary. Changing code style does not require any -change to the Ragel program. There are two table-driven formats and a goto -driven format. - -In addition to choosing a style to emit, there are various levels of action -code reuse to choose from. The maximum reuse levels (\verb|-T0|, \verb|-F0| -and \verb|-G0|) ensure that no FSM action code is ever duplicated by encoding -each transition's action list as static data and iterating -through the lists on every transition. This will normally result in a smaller -binary. The less action reuse options (\verb|-T1|, \verb|-F1| and \verb|-G1|) -will usually produce faster running code by expanding each transition's action -list into a single block of code, eliminating the need to iterate through the -lists. This duplicates action code instead of generating the logic necessary -for reuse. Consequently the binary will be larger. However, this tradeoff applies to -machines with moderate to dense action lists only. If a machine's transitions -frequently have less than two actions then the less reuse options will actually -produce both a smaller and a faster running binary due to less action sharing -overhead. The best way to choose the appropriate code style for your -application is to perform your own tests. - -The table-driven FSM represents the state machine as constant static data. There are -tables of states, transitions, indices and actions. The current state is -stored in a variable. The execution is simply a loop that looks up the current -state, looks up the transition to take, executes any actions and moves to the -target state. In general, the table-driven FSM can handle any machine, produces -a smaller binary and requires a less expensive host language compile, but -results in slower running code. Since the table-driven format is the most -flexible it is the default code style. - -The flat table-driven machine is a table-based machine that is optimized for -small alphabets. Where the regular table machine uses the current character as -the key in a binary search for the transition to take, the flat table machine -uses the current character as an index into an array of transitions. This is -faster in general, however is only suitable if the span of possible characters -is small. - -The goto-driven FSM represents the state machine using goto and switch -statements. The execution is a flat code block where the transition to take is -computed using switch statements and directly executable binary searches. In -general, the goto FSM produces faster code but results in a larger binary and a -more expensive host language compile. - -The goto-driven format has an additional action reuse level (\verb|-G2|) that -writes actions directly into the state transitioning logic rather than putting -all the actions together into a single switch. Generally this produces faster -running code because it allows the machine to encode the current state using -the processor's instruction pointer. Again, sparse machines may actually -compile to smaller binaries when \verb|-G2| is used due to less state and -action management overhead. For many parsing applications \verb|-G2| is the -preferred output format. - -\begin{center} - -Code Output Style Options - -\begin{tabular}{|c|c|c|} -\hline -\verb|-T0|&binary search table-driven&C/D/Java/Ruby/C\#/OCaml\\ -\hline -\verb|-T1|&binary search, expanded actions&C/D/Ruby/C\#/OCaml\\ -\hline -\verb|-F0|&flat table-driven&C/D/Ruby/C\#/OCaml\\ -\hline -\verb|-F1|&flat table, expanded actions&C/D/Ruby/C\#/OCaml\\ -\hline -\verb|-G0|&goto-driven&C/D/C\#/OCaml\\ -\hline -\verb|-G1|&goto, expanded actions&C/D/C\#/OCaml\\ -\hline -\verb|-G2|&goto, in-place actions&C/D/Go\\ -\hline -\end{tabular} -\end{center} - -\chapter{Beyond the Basic Model} - -\section{Parser Modularization} -\label{modularization} - -It is possible to use Ragel's machine construction and action embedding -operators to specify an entire parser using a single regular expression. In -many cases this is the desired way to specify a parser in Ragel. However, in -some scenarios the language to parse may be so large that it is difficult to -think about it as a single regular expression. It may also shift between distinct -parsing strategies, in which case modularization into several coherent blocks -of the language may be appropriate. - -It may also be the case that patterns that compile to a large number of states -must be used in a number of different contexts and referencing them in each -context results in a very large state machine. In this case, an ability to reuse -parsers would reduce code size. - -To address this, distinct regular expressions may be instantiated and linked -together by means of a jumping and calling mechanism. This mechanism is -analogous to the jumping to and calling of processor instructions. A jump -command, given in action code, causes control to be immediately passed to -another portion of the machine by way of setting the current state variable. A -call command causes the target state of the current transition to be pushed to -a state stack before control is transferred. Later on, the original location -may be returned to with a return statement. In the following example, distinct -state machines are used to handle the parsing of two types of headers. - -% GENERATE: call -% %%{ -% machine call; -\begin{inline_code} -\begin{verbatim} -action return { fret; } -action call_date { fcall date; } -action call_name { fcall name; } - -# A parser for date strings. -date := [0-9][0-9] '/' - [0-9][0-9] '/' - [0-9][0-9][0-9][0-9] '\n' @return; - -# A parser for name strings. -name := ( [a-zA-Z]+ | ' ' )** '\n' @return; - -# The main parser. -headers = - ( 'from' | 'to' ) ':' @call_name | - ( 'departed' | 'arrived' ) ':' @call_date; - -main := headers*; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% %% write data; -% void f() -% { -% %% write init; -% %% write exec; -% } -% END GENERATE - -Calling and jumping should be used carefully as they are operations that take -one out of the domain of regular languages. A machine that contains a call or -jump statement in one of its actions should be used as an argument to a machine -construction operator only with considerable care. Since DFA transitions may -actually represent several NFA transitions, a call or jump embedded in one -machine can inadvertently terminate another machine that it shares prefixes -with. Despite this danger, theses statements have proven useful for tying -together sub-parsers of a language into a parser for the full language, -especially for the purpose of modularizing code and reducing the number of -states when the machine contains frequently recurring patterns. - -Section \ref{vals} describes the jump and call statements that are used to -transfer control. These statements make use of two variables that must be -declared by the user, \verb|stack| and \verb|top|. The \verb|stack| variable -must be an array of integers and \verb|top| must be a single integer, which -will point to the next available space in \verb|stack|. Sections \ref{prepush} -and \ref{postpop} describe the Pre-Push and Post-Pop statements which can be -used to implement a dynamically resizable array. - -\section{Referencing Names} -\label{labels} - -This section describes how to reference names in epsilon transitions (Section -\ref{state-charts}) and -action-based control-flow statements such as \verb|fgoto|. There is a hierarchy -of names implied in a Ragel specification. At the top level are the machine -instantiations. Beneath the instantiations are labels and references to machine -definitions. Beneath those are more labels and references to definitions, and -so on. - -Any name reference may contain multiple components separated with the \verb|::| -compound symbol. The search for the first component of a name reference is -rooted at the join expression that the epsilon transition or action embedding -is contained in. If the name reference is not contained in a join, -the search is rooted at the machine definition that the epsilon transition or -action embedding is contained in. Each component after the first is searched -for beginning at the location in the name tree that the previous reference -component refers to. - -In the case of action-based references, if the action is embedded more than -once, the local search is performed for each embedding and the result is the -union of all the searches. If no result is found for action-based references then -the search is repeated at the root of the name tree. Any action-based name -search may be forced into a strictly global search by prefixing the name -reference with \verb|::|. - -The final component of the name reference must resolve to a unique entry point. -If a name is unique in the entire name tree it can be referenced as is. If it -is not unique it can be specified by qualifying it with names above it in the -name tree. However, it can always be renamed. - -% FIXME: Should fit this in somewhere. -% Some kinds of name references are illegal. Cannot call into longest-match -% machine, can only call its start state. Cannot make a call to anywhere from -% any part of a longest-match machine except a rule's action. This would result -% in an eventual return to some point inside a longest-match other than the -% start state. This is banned for the same reason a call into the LM machine is -% banned. - - -\section{Scanners} -\label{generating-scanners} - -Scanners are very much intertwined with regular-languages and their -corresponding processors. For this reason Ragel supports the definition of -scanners. The generated code will repeatedly attempt to match patterns from a -list, favouring longer patterns over shorter patterns. In the case of -equal-length matches, the generated code will favour patterns that appear ahead -of others. When a scanner makes a match it executes the user code associated -with the match, consumes the input then resumes scanning. - -\begin{verbatim} -<machine_name> := |* - pattern1 => action1; - pattern2 => action2; - ... - *|; -\end{verbatim} -\verbspace - -On the surface, Ragel scanners are similar to those defined by Lex. Though -there is a key distinguishing feature: patterns may be arbitrary Ragel -expressions and can therefore contain embedded code. With a Ragel-based scanner -the user need not wait until the end of a pattern before user code can be -executed. - -Scanners can be used to process sub-languages, as well as for tokenizing -programming languages. In the following example a scanner is used to tokenize -the contents of a header field. - -\begin{inline_code} -\begin{verbatim} -word = [a-z]+; -head_name = 'Header'; - -header := |* - word; - ' '; - '\n' => { fret; }; -*|; - -main := ( head_name ':' @{ fcall header; } )*; -\end{verbatim} -\end{inline_code} -\verbspace - -The scanner construction has a purpose similar to the longest-match kleene star -operator \verb|**|. The key -difference is that a scanner is able to backtrack to match a previously matched -shorter string when the pursuit of a longer string fails. For this reason the -scanner construction operator is not a pure state machine construction -operator. It relies on several variables that enable it to backtrack and make -pointers to the matched input text available to the user. For this reason -scanners must be immediately instantiated. They cannot be defined inline or -referenced by another expression. Scanners must be jumped to or called. - -Scanners rely on the \verb|ts|, \verb|te| and \verb|act| -variables to be present so that they can backtrack and make pointers to the -matched text available to the user. If input is processed using multiple calls -to the execute code then the user must ensure that when a token is only -partially matched that the prefix is preserved on the subsequent invocation of -the execute code. - -The \verb|ts| variable must be defined as a pointer to the input data. -It is used for recording where the current token match begins. This variable -may be used in action code for retrieving the text of the current match. Ragel -ensures that in between tokens and outside of the longest-match machines that -this pointer is set to null. In between calls to the execute code the user must -check if \verb|ts| is set and if so, ensure that the data it points to is -preserved ahead of the next buffer block. This is described in more detail -below. - -The \verb|te| variable must also be defined as a pointer to the input data. -It is used for recording where a match ends and where scanning of the next -token should begin. This can also be used in action code for retrieving the -text of the current match. - -The \verb|act| variable must be defined as an integer type. It is used for -recording the identity of the last pattern matched when the scanner must go -past a matched pattern in an attempt to make a longer match. If the longer -match fails it may need to consult the \verb|act| variable. In some cases, use -of the \verb|act| -variable can be avoided because the value of the current state is enough -information to determine which token to accept, however in other cases this is -not enough and so the \verb|act| variable is used. - -When the longest-match operator is in use, the user's driver code must take on -some buffer management functions. The following algorithm gives an overview of -the steps that should be taken to properly use the longest-match operator. - -\begin{itemize} -\item Read a block of input data. -\item Run the execute code. -\item If \verb|ts| is set, the execute code will expect the incomplete -token to be preserved ahead of the buffer on the next invocation of the execute -code. -\begin{itemize} -\item Shift the data beginning at \verb|ts| and ending at \verb|pe| to the -beginning of the input buffer. -\item Reset \verb|ts| to the beginning of the buffer. -\item Shift \verb|te| by the distance from the old value of \verb|ts| -to the new value. The \verb|te| variable may or may not be valid. There is -no way to know if it holds a meaningful value because it is not kept at null -when it is not in use. It can be shifted regardless. -\end{itemize} -\item Read another block of data into the buffer, immediately following any -preserved data. -\item Run the scanner on the new data. -\end{itemize} - -Figure \ref{preserve_example} shows the required handling of an input stream in -which a token is broken by the input block boundaries. After processing up to -and including the ``t'' of ``characters'', the prefix of the string token must be -retained and processing should resume at the ``e'' on the next iteration of -the execute code. - -If one uses a large input buffer for collecting input then the number of times -the shifting must be done will be small. Furthermore, if one takes care not to -define tokens that are allowed to be very long and instead processes these -items using pure state machines or sub-scanners, then only a small amount of -data will ever need to be shifted. - -\begin{figure} -\small -\begin{verbatim} - a) A stream "of characters" to be scanned. - | | | - p ts pe - - b) "of characters" to be scanned. - | | | - ts p pe -\end{verbatim} -\verbspace -\caption{Following an invocation of the execute code there may be a partially -matched token (a). The data of the partially matched token -must be preserved ahead of the new data on the next invocation (b). -} -\label{preserve_example} -\end{figure} - -Since scanners attempt to make the longest possible match of input, patterns -such as identifiers require one character of lookahead in order to trigger a -match. In the case of the last token in the input stream the user must ensure -that the \verb|eof| variable is set so that the final token is flushed out. - -An example scanner processing loop is given in Figure \ref{scanner-loop}. - -\begin{figure} -\small -\begin{verbatim} - int have = 0; - bool done = false; - while ( !done ) { - /* How much space is in the buffer? */ - int space = BUFSIZE - have; - if ( space == 0 ) { - /* Buffer is full. */ - cerr << "TOKEN TOO BIG" << endl; - exit(1); - } - - /* Read in a block after any data we already have. */ - char *p = inbuf + have; - cin.read( p, space ); - int len = cin.gcount(); - - char *pe = p + len; - char *eof = 0; - - /* If no data was read indicate EOF. */ - if ( len == 0 ) { - eof = pe; - done = true; - } - - %% write exec; - - if ( cs == Scanner_error ) { - /* Machine failed before finding a token. */ - cerr << "PARSE ERROR" << endl; - exit(1); - } - - if ( ts == 0 ) - have = 0; - else { - /* There is a prefix to preserve, shift it over. */ - have = pe - ts; - memmove( inbuf, ts, have ); - te = inbuf + (te-ts); - ts = inbuf; - } - } -\end{verbatim} -\verbspace -\caption{A processing loop for a scanner. -} -\label{scanner-loop} -\end{figure} - -\section{State Charts} -\label{state-charts} - -In addition to supporting the construction of state machines using regular -languages, Ragel provides a way to manually specify state machines using -state charts. The comma operator combines machines together without any -implied transitions. The user can then manually link machines by specifying -epsilon transitions with the \verb|->| operator. Epsilon transitions are drawn -between the final states of a machine and entry points defined by labels. This -makes it possible to build machines using the explicit state-chart method while -making minimal changes to the Ragel language. - -An interesting feature of Ragel's state chart construction method is that it -can be mixed freely with regular expression constructions. A state chart may be -referenced from within a regular expression, or a regular expression may be -used in the definition of a state chart transition. - -\subsection{Join} - -\verb|expr , expr , ...| - -Join a list of machines together without -drawing any transitions, without setting up a start state, and without -designating any final states. Transitions between the machines may be specified -using labels and epsilon transitions. The start state must be explicity -specified with the ``start'' label. Final states may be specified with an -epsilon transition to the implicitly created ``final'' state. The join -operation allows one to build machines using a state chart model. - -\subsection{Label} - -\verb|label: expr| - -Attaches a label to an expression. Labels can be -used as the target of epsilon transitions and explicit control transfer -statements such as \verb|fgoto| and \verb|fnext| in action -code. - -\subsection{Epsilon} - -\verb|expr -> label| - -Draws an epsilon transition to the state defined -by \verb|label|. Epsilon transitions are made deterministic when join -operators are evaluated. Epsilon transitions that are not in a join operation -are made deterministic when the machine definition that contains the epsilon is -complete. See Section \ref{labels} for information on referencing labels. - -\subsection{Simplifying State Charts} - -There are two benefits to providing state charts in Ragel. The first is that it -allows us to take a state chart with a full listing of states and transitions -and simplify it in selective places using regular expressions. - -The state chart method of specifying parsers is very common. It is an -effective programming technique for producing robust code. The key disadvantage -becomes clear when one attempts to comprehend a large parser specified in this -way. These programs usually require many lines, causing logic to be spread out -over large distances in the source file. Remembering the function of a large -number of states can be difficult and organizing the parser in a sensible way -requires discipline because branches and repetition present many file layout -options. This kind of programming takes a specification with inherent -structure such as looping, alternation and concatenation and expresses it in a -flat form. - -If we could take an isolated component of a manually programmed state chart, -that is, a subset of states that has only one entry point, and implement it -using regular language operators then we could eliminate all the explicit -naming of the states contained in it. By eliminating explicitly named states -and replacing them with higher-level specifications we simplify a state machine -specification. - -For example, sometimes chains of states are needed, with only a small number of -possible characters appearing along the chain. These can easily be replaced -with a concatenation of characters. Sometimes a group of common states -implement a loop back to another single portion of the machine. Rather than -manually duplicate all the transitions that loop back, we may be able to -express the loop using a kleene star operator. - -Ragel allows one to take this state map simplification approach. We can build -state machines using a state map model and implement portions of the state map -using regular languages. In place of any transition in the state machine, -entire sub-machines can be given. These can encapsulate functionality -defined elsewhere. An important aspect of the Ragel approach is that when we -wrap up a collection of states using a regular expression we do not lose -access to the states and transitions. We can still execute code on the -transitions that we have encapsulated. - -\subsection{Dropping Down One Level of Abstraction} -\label{down} - -The second benefit of incorporating state charts into Ragel is that it permits -us to bypass the regular language abstraction if we need to. Ragel's action -embedding operators are sometimes insufficient for expressing certain parsing -tasks. In the same way that is useful for C language programmers to drop down -to assembly language programming using embedded assembler, it is sometimes -useful for the Ragel programmer to drop down to programming with state charts. - -In the following example, we wish to buffer the characters of an XML CDATA -sequence. The sequence is terminated by the string \verb|]]>|. The challenge -in our application is that we do not wish the terminating characters to be -buffered. An expression of the form \verb|any* @buffer :>> ']]>'| will not work -because the buffer will always contain the characters \verb|]]| on the end. -Instead, what we need is to delay the buffering of \verb|]| -characters until a time when we -abandon the terminating sequence and go back into the main loop. There is no -easy way to express this using Ragel's regular expression and action embedding -operators, and so an ability to drop down to the state chart method is useful. - -% GENERATE: dropdown -% OPT: -p -% %%{ -% machine dropdown; -\begin{inline_code} -\begin{verbatim} -action bchar { buff( fpc ); } # Buffer the current character. -action bbrack1 { buff( "]" ); } -action bbrack2 { buff( "]]" ); } - -CDATA_body = -start: ( - ']' -> one | - (any-']') @bchar ->start -), -one: ( - ']' -> two | - [^\]] @bbrack1 @bchar ->start -), -two: ( - '>' -> final | - ']' @bbrack1 -> two | - [^>\]] @bbrack2 @bchar ->start -); -\end{verbatim} -\end{inline_code} -\verbspace -% main := CDATA_body; -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{dropdown} -\end{center} -\graphspace - - -\section{Semantic Conditions} -\label{semantic} - -Many communication protocols contain variable-length fields, where the length -of the field is given ahead of the field as a value. This -problem cannot be expressed using regular languages because of its -context-dependent nature. The prevalence of variable-length fields in -communication protocols motivated us to introduce semantic conditions into -the Ragel language. - -A semantic condition is a block of user code that is interpreted as an -expression and evaluated immediately -before a transition is taken. If the code returns a value of true, the -transition may be taken. We can now embed code that extracts the length of a -field, then proceed to match $n$ data values. - -% GENERATE: conds1 -% OPT: -p -% %%{ -% machine conds1; -% number = digit+; -\begin{inline_code} -\begin{verbatim} -action rec_num { i = 0; n = getnumber(); } -action test_len { i++ < n } -data_fields = ( - 'd' - [0-9]+ %rec_num - ':' - ( [a-z] when test_len )* -)**; -\end{verbatim} -\end{inline_code} -\verbspace -% main := data_fields; -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{conds1} -\end{center} -\graphspace - -The Ragel implementation of semantic conditions does not force us to give up the -compositional property of Ragel definitions. For example, a machine that tests -the length of a field using conditions can be unioned with another machine -that accepts some of the same strings, without the two machines interfering with -one another. The user need not be concerned about whether or not the result of the -semantic condition will affect the matching of the second machine. - -To see this, first consider that when a user associates a condition with an -existing transition, the transition's label is translated from the base character -to its corresponding value in the space that represents ``condition $c$ true''. Should -the determinization process combine a state that has a conditional transition -with another state that has a transition on the same input character but -without a condition, then the condition-less transition first has its label -translated into two values, one to its corresponding value in the space that -represents ``condition $c$ true'' and another to its corresponding value in the -space that represents ``condition $c$ false''. It -is then safe to combine the two transitions. This is shown in the following -example. Two intersecting patterns are unioned, one with a condition and one -without. The condition embedded in the first pattern does not affect the second -pattern. - -% GENERATE: conds2 -% OPT: -p -% %%{ -% machine conds2; -% number = digit+; -\begin{inline_code} -\begin{verbatim} -action test_len { i++ < n } -action one { /* accept pattern one */ } -action two { /* accept pattern two */ } -patterns = - ( [a-z] when test_len )+ %one | - [a-z][a-z0-9]* %two; -main := patterns '\n'; -\end{verbatim} -\end{inline_code} -\verbspace -% }%% -% END GENERATE - -\graphspace -\begin{center} -\includegraphics[scale=0.55]{conds2} -\end{center} -\graphspace - -There are many more potential uses for semantic conditions. The user is free to -use arbitrary code and may therefore perform actions such as looking up names -in dictionaries, validating input using external parsing mechanisms or -performing checks on the semantic structure of input seen so far. In the next -section we describe how Ragel accommodates several common parser engineering -problems. - -The semantic condition feature works only with alphabet types that are smaller -in width than the \verb|long| type. To implement semantic conditions Ragel -needs to be able to allocate characters from the alphabet space. Ragel uses -these allocated characters to express "character C with condition P true" or "C -with P false." Since internally Ragel uses longs to store characters there is -no room left in the alphabet space unless an alphabet type smaller than long is -used. - -\section{Implementing Lookahead} - -There are a few strategies for implementing lookahead in Ragel programs. -Leaving actions, which are described in Section \ref{out-actions}, can be -used as a form of lookahead. Ragel also provides the \verb|fhold| directive -which can be used in actions to prevent the machine from advancing over the -current character. It is also possible to manually adjust the current character -position by shifting it backwards using \verb|fexec|, however when this is -done, care must be taken not to overstep the beginning of the current buffer -block. In both the use of \verb|fhold| and \verb|fexec| the user must be -cautious of combining the resulting machine with another in such a way that the -transition on which the current position is adjusted is not combined with a -transition from the other machine. - -\section{Parsing Recursive Language Structures} - -In general Ragel cannot handle recursive structures because the grammar is -interpreted as a regular language. However, depending on what needs to be -parsed it is sometimes practical to implement the recursive parts using manual -coding techniques. This often works in cases where the recursive structures are -simple and easy to recognize, such as in the balancing of parentheses - -One approach to parsing recursive structures is to use actions that increment -and decrement counters or otherwise recognize the entry to and exit from -recursive structures and then jump to the appropriate machine defnition using -\verb|fcall| and \verb|fret|. Alternatively, semantic conditions can be used to -test counter variables. - -A more traditional approach is to call a separate parsing function (expressed -in the host language) when a recursive structure is entered, then later return -when the end is recognized. - -\end{document} diff --git a/doc/ragel/ragel-guide.txt b/doc/ragel/ragel-guide.txt deleted file mode 100644 index 592c3f2c..00000000 --- a/doc/ragel/ragel-guide.txt +++ /dev/null @@ -1,3603 +0,0 @@ -= Ragel State Machine Compiler User Guide -Adrian Thurston <thurston@colm.net> -Ragel Version 7.0 -:toc: -:toclevels: 3 -:numbered: - -.License - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to - deal in the Software without restriction, including without limitation the - rights to use, copy, modify, merge, publish, distribute, sublicense, and/or - sell copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all - copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. - -== Introduction - -=== Abstract - -In today's computing landscape, regular expressions are used heavily for the -purpose of specifying parsers. They are normally treated as black boxes, linked -together with program logic. User code is executed in between invocations of -the regular expression engine. To add code before a pattern terminates, the -programmer is required to break patterns and paste them back together with -program logic. The more inline code needed, the less the advantages of regular -expressions are seen. - -Ragel is a software development tool that allows user code to be embedded into -the transitions of a regular expression's corresponding state machine, -eliminating the need to switch from the regular expression engine to the user -code execution environment, and then back again. As a result, expressions can -be maximally continuous. One is free to specify an entire parser using a single -regular expression. The single-expression model affords concise and elegant -descriptions of languages and the generation of very simple, fast and robust -code. Ragel compiles executable finite state machines from a high level regular -language notation. Ragel targets C, C++, Objective-C, D, Go, GNU ASM x86-64, -Java, Ruby, C#, OCaml, Crack, Rust, Julia and JavaScript - -In addition to building state machines from regular expressions, Ragel allows -the programmer to directly specify state machines with state charts. These two -notations may be freely combined. There are also facilities for controlling -nondeterminism in the resulting machines and building scanners using patterns -that themselves have embedded actions. Ragel can produce code that is small and -runs very fast. Ragel can handle integer-sized alphabets and can compile very -large state machines. - -=== Motivation - -When a programmer is faced with the task of producing a parser for a -context-free language, there are many tools to choose from. It is quite common -to generate useful and efficient parsers for programming languages from a -formal grammar. It is also quite common for programmers to avoid such tools -when making parsers for simple computer languages, such as file formats and -communication protocols. Such languages are often regular, and tools for -processing the context-free languages are viewed as too heavyweight for the -purpose of parsing regular languages. The extra run-time effort required for -supporting the recursive nature of context-free languages is wasted. - -When we turn to the regular expression-based parsing tools, such as Lex, Re2C, -and scripting languages such as Sed, Awk and Perl we find that they are split -into two levels: a regular expression matching engine and some kind of program -logic for linking patterns together. For example, a Lex program is composed of -sets of regular expressions. The implied program logic repeatedly attempts to -match a pattern in the current set. When a match is found, the associated user -code executed. It requires the user to consider a language as a sequence of -independent tokens. Scripting languages and regular expression libraries allow -one to link patterns together using arbitrary program code. This is very -flexible and powerful; however, we can be more concise and clear if we avoid -gluing together regular expressions with if statements and while loops. - -This model of execution, where the runtime alternates between regular -expression matching and user code execution places restrictions on when -action code may be executed. Since action code can only be associated with -complete patterns, any action code that must be executed before an entire -pattern is matched requires that the pattern be broken into smaller units. -Instead of being forced to disrupt the regular expression syntax and write -smaller expressions, it is desirable to retain a single expression and embed -code for performing actions directly into the transitions that move over the -characters. After all, capable programmers are astutely aware of the machinery -underlying their programs, so why not provide them with access to that -machinery? To achieve this, we require an action execution model for associating -code with the sub-expressions of a regular expression in a way that does not -disrupt its syntax. - -The primary goal of Ragel is to provide developers with an ability to embed -actions into the transitions and states of a regular expression's state machine -in support of the definition of entire parsers or large sections of parsers -using a single regular expression. From the regular expression we gain a clear -and concise statement of our language. From the state machine we obtain a very -fast and robust executable that lends itself to many kinds of analysis and -visualization. - -=== Overview - -Ragel is a language for specifying state machines. The Ragel program is a -compiler that assembles a state machine definition to executable code. Ragel -is based on the principle that any regular language can be converted to a -deterministic finite state automaton. Since every regular language has a state -machine representation and vice versa, the terms regular language and state -machine (or just machine) will be used interchangeably in this document. - -Ragel outputs machines to C, C++, Objective-C, D, Go, GNU ASM x86-64, Java, -Ruby, C#, OCaml, Crack, Rust, Julia and JavaScript code. The output is -designed to be generic and is not bound to any particular input or processing -method. A Ragel machine expects to have data passed to it in buffer blocks. -When there is no more input, the machine can be queried for acceptance. In -this way, a Ragel machine can be used to simply recognize a regular language -like a regular expression library. By embedding code into the regular language, -a Ragel machine can also be used to parse input. - -The Ragel language has many operators for constructing and manipulating -machines. Machines are built up from smaller machines, to bigger ones, to the -final machine representing the language that needs to be recognized or parsed. - -The core state machine construction operators are those found in most theory -of computation textbooks. They date back to the 1950s and are widely studied. -They are based on set operations and permit one to think of languages as a set -of strings. They are Union, Intersection, Difference, Concatenation and Kleene -Star. Put together, these operators make up what most people know as regular -expressions. Ragel also provides a scanner construction operator -and provides operators for explicitly constructing machines -using a state chart method. In the state chart method, one joins machines -together without any implied transitions and then explicitly specifies where -epsilon transitions should be drawn. - -The state machine manipulation operators are specific to Ragel. They allow the -programmer to access the states and transitions of regular language's -corresponding machine. There are two uses of the manipulation operators. The -first and primary use is to embed code into transitions and states, allowing -the programmer to specify the actions of the state machine. - -Ragel attempts to make the action embedding facility as intuitive as possible. -To do so, a number of issues need to be addressed. For example, when making a -nondeterministic specification into a DFA using machines that have embedded -actions, new transitions are often made that have the combined actions of -several source transitions. Ragel ensures that multiple actions associated with -a single transition are ordered consistently with respect to the order of -reference and the natural ordering implied by the construction operators. - -The second use of the manipulation operators is to assign priorities to -transitions. Priorities provide a convenient way of controlling any -nondeterminism introduced by the construction operators. Suppose two -transitions leave from the same state and go to distinct target states on the -same character. If these transitions are assigned conflicting priorities, then -during the determinization process the transition with the higher priority will -take precedence over the transition with the lower priority. The lower priority -transition gets abandoned. The transitions would otherwise be combined into a new -transition that goes to a new state that is a combination of the original -target states. Priorities are often required for segmenting machines. The most -common uses of priorities have been encoded into a set of simple operators -that should be used instead of priority embeddings whenever possible. - -For the purposes of embedding, Ragel divides transitions and states into -different classes. There are four operators for embedding actions and -priorities into the transitions of a state machine. It is possible to embed -into entering transitions, finishing transitions, all transitions and leaving -transitions. The embedding into leaving transitions is a special case. -These transition embeddings get stored in the final states of a machine. They -are transferred to any transitions that are made going out of the machine by -future concatenation or kleene star operations. - -There are several more operators for embedding actions into states. Like the -transition embeddings, there are various different classes of states that the -embedding operators access. For example, one can access start states, final -states or all states, among others. Unlike the transition embeddings, there are -several different types of state action embeddings. These are executed at -various different times during the processing of input. It is possible to embed -actions that are executed on transitions into a state, on transitions out of a -state, on transitions taken on the error event, or on transitions taken on the -EOF event. - -Within actions, it is possible to influence the behaviour of the state machine. -The user can write action code that jumps or calls to another portion of the -machine, changes the current character being processed, or breaks out of the -processing loop. With the state machine calling feature Ragel can be used to -parse languages that are not regular. For example, one can parse balanced -parentheses by calling into a parser when an open parenthesis character is seen -and returning to the state on the top of the stack when the corresponding -closing parenthesis character is seen. More complicated context-free languages -such as expressions in C are out of the scope of Ragel. - -Ragel also provides a scanner construction operator that can be used to build -scanners much the same way that Lex is used. The Ragel generated code, which -relies on user-defined variables for backtracking, repeatedly tries to match -patterns to the input, favouring longer patterns over shorter ones and patterns -that appear ahead of others when the lengths of the possible matches are -identical. When a pattern is matched the associated action is executed. - -The key distinguishing feature between scanners in Ragel and scanners in Lex is -that Ragel patterns may be arbitrary Ragel expressions and can therefore -contain embedded code. With a Ragel-based scanner the user need not wait until -the end of a pattern before user code can be executed. - -Scanners do take Ragel out of the domain of pure state machines and require the -user to maintain the backtracking related variables. However, scanners -integrate well with regular state machine instantiations. They can be called to -or jumped to only when needed, or they can be called out of or jumped out of -when a simpler, pure state machine model is appropriate. - -Two types of output code style are available. Ragel can produce a table-driven -machine or a directly executable machine. The directly executable machine is -much faster than the table-driven. On the other hand, the table-driven machine -is more compact and less demanding on the host language compiler. It is better -suited to compiling large state machines. - -=== Related Work - -==== Lex - -Lex is perhaps the best-known tool for constructing parsers from regular -expressions. In the Lex processing model, generated code attempts to match one -of the user's regular expression patterns, favouring longer matches over -shorter ones. Once a match is made it then executes the code associated with -the pattern and consumes the matching string. This process is repeated until -the input is fully consumed. - -Through the use of start conditions, related sets of patterns may be defined. -The active set may be changed at any time. This allows the user to define -different lexical regions. It also allows the user to link patterns together by -requiring that some patterns come before others. This is quite like a -concatenation operation. However, use of Lex for languages that require a -considerable amount of pattern concatenation is inappropriate. In such cases a -Lex program deteriorates into a manually specified state machine, where start -conditions define the states and pattern actions define the transitions. Lex -is therefore best suited to parsing tasks where the language to be parsed can -be described in terms of regions of tokens. - -Lex is useful in many scenarios and has undoubtedly stood the test of time. -There are, however, several drawbacks to using Lex. Lex can impose too much -overhead for parsing applications where buffering is not required because all -the characters are available in a single string. In these cases there is -structure to the language to be parsed and a parser specification tool can -help, but employing a heavyweight processing loop that imposes a stream -pull model and dynamic input buffer allocation is inappropriate. An -example of this kind of scenario is the conversion of floating point numbers -contained in a string to their corresponding numerical values. - -Another drawback is the very issue that Ragel attempts to solve. -It is not possible to execute a user action while -matching a character contained inside a pattern. For example, if scanning a -programming language and string literals can contain newlines which must be -counted, a Lex user must break up a string literal pattern so as to associate -an action with newlines. This forces the definition of a new start condition. -Alternatively the user can reprocess the text of the matched string literal to -count newlines. - -///////////////////////////////// -How ragel is different from Lex. - -Like Re2c, Ragel provides a simple execution model that does not make any -assumptions as to how the input is collected. Also, Ragel does not do any -buffering in the generated code. Consequently there are no dependencies on -external functions such as `malloc`. - -If buffering is required it can be manually implemented by embedding actions -that copy the current character to a buffer, or data can be passed to the -parser using known block boundaries. If the longest-match operator is used, -Ragel requires the user to ensure that the ending portion of the input buffer -is preserved when the buffer is exhausted before a token is fully matched. The -user should move the token prefix to a new memory location, such as back to the -beginning of the input buffer, then place the subsequently read input -immediately after the prefix. - -These properties of Ragel make it more work to write a program that requires -the longest-match operator or buffering of input, however they make Ragel a -more flexible tool that can produce very simple and fast-running programs under -a variety of input acquisition arrangements. - -In Ragel, it is not necessary -to introduce start conditions to concatenate tokens and retain action -execution. Ragel allows one to structure a parser as a series of tokens, but -does not require it. - -Like Lex and Re2C, Ragel is able to process input using a longest-match -execution model, however the core of the Ragel language specifies parsers at a -much lower level. This core is built around a pure state machine model. When -building basic machines there is no implied algorithm for processing input -other than to move from state to state on the transitions of the machine. This -core of pure state machine operations makes Ragel well suited to handling -parsing problems not based on token scanning. Should one need to use a -longest-match model, the functionality is available and the lower level state -machine construction facilities can be used to specify the patterns of a -longest-match machine. - -This is not possible in Ragel. One can only program -a longest-match instantiation with a fixed set of rules. One can jump to -another longest-match machine that employs the same machine definitions in the -construction of its rules, however no states will be shared. - -In Ragel, input may be re-parsed using a -different machine, but since the action to be executed is associated with -transitions of the compiled state machine, the longest-match construction does -not permit a single rule to be excluded from the active set. It cannot be done -ahead of time nor in the excluded rule's action. -///////////////////////////////// - -==== Re2C - -The Re2C program defines an input processing model similar to that of Lex. -Re2C focuses on making generated state machines run very fast and -integrate easily into any program, free of dependencies. Re2C generates -directly executable code and is able to claim that generated parsers run nearly -as fast as their hand-coded equivalents. This is very important for user -adoption, as programmers are reluctant to use a tool when a faster alternative -exists. A consideration to ease of use is also important because developers -need the freedom to integrate the generated code as they see fit. - -==== Regular Expression Libraries - -Many scripting languages provide ways of composing parsers by linking regular -expressions using program logic. For example, Sed and Awk are two established -Unix scripting tools that allow the programmer to exploit regular expressions -for the purpose of locating and extracting text of interest. High-level -programming languages such as Perl, Python, PHP and Ruby all provide regular -expression libraries that allow the user to combine regular expressions with -arbitrary code. - -In addition to supporting the linking of regular expressions with arbitrary -program logic, the Perl programming language permits the embedding of code into -regular expressions. Perl embeddings do not translate into the embedding of -code into deterministic state machines. Perl regular expressions are in fact -not fully compiled to deterministic machines when embedded code is involved. -They are instead interpreted and involve backtracking. This is shown by the -following Perl program. When it is fed the input +abcd+ the interpreter -attempts to match the first alternative, printing +a1 b1+. When this -possibility fails it backtracks and tries the second possibility, printing -+a2 b2+, at which point it succeeds. - ------------------ -print "YES\n" if ( <STDIN> =~ - /( a (?{ print "a1 "; }) b (?{ print "b1 "; }) cX ) | - ( a (?{ print "a2 "; }) b (?{ print "b2 "; }) cd )/x ) ------------------ - -In Ragel there is no regular expression interpreter. Aside from the scanner -operator, all Ragel expressions are made into deterministic machines and the -run time simply moves from state to state as it consumes input. An equivalent -parser expressed in Ragel would attempt both of the alternatives concurrently, -printing +a1 a2 b1 b2+. - -////////////////////// -=== Development Status - -Ragel is a relatively new tool and is under continuous development. As a rough -release guide, minor revision number changes are for implementation -improvements and feature additions. Major revision number changes are for -implementation and language changes that do not preserve backwards -compatibility. Though in the past this has not always held true: changes that -break code have crept into minor version number changes. Typically, the -documentation lags behind the development in the interest of documenting only -the lasting features. The latest changes are always documented in the ChangeLog -file. -////////////////////// - -== Constructing State Machines - -=== Ragel State Machine Specifications - -A Ragel input file consists of a program in the host language that contains -embedded machine specifications. Ragel normally passes input straight to -output. When it sees a machine specification it stops to read the Ragel -statements and possibly generate code in place of the specification. Afterwards -it continues to pass input through. There can be any number of FSM -specifications in an input file. A multi-line FSM spec starts with +%%{+ and -ends with +}%%+. A single-line FSM spec starts with +%%+ and ends at the -first newline. - -While Ragel is looking for FSM specifications it does basic lexical analysis on -the surrounding input. It interprets literal strings and comments so a -+%%+ sequence in either of those will not trigger the parsing of an FSM -specification. Ragel does not pass the input through any preprocessor nor does it -interpret preprocessor directives itself so includes, defines and ifdef logic -cannot be used to alter the parse of a Ragel input file. It is therefore not -possible to use an +#if 0+ directive to comment out a machine as is -commonly done in C code. As an alternative, a machine can be prevented from -causing any generated output by commenting out write statements. - -In the example below, a multi-line specification is used to define the machine -and single line specifications are used to trigger the writing of the machine -data and execution code. This example shows parsing of a command line argument. - -.Parsing Command Line Args -------------------------- -#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; -} -------------------------- - -==== Naming Ragel Blocks - ------------- -machine fsm_name; ------------- - -The +machine+ statement gives the name of the FSM. If present in a -specification, this statement must appear first. If a machine specification -does not have a name then Ragel uses the previous specification name. If no -previous specification name exists then this is an error. Because FSM -specifications persist in memory, a machine's statements can be spread across -multiple machine specifications. This allows one to break up a machine across -several files or draw in statements that are common to multiple machines using -the +include+ statement. - -[[definition]] -==== Machine Definition - --------------- -<name> = <expression>; --------------- - -The machine definition statement associates an FSM expression with a name. Machine -expressions assigned to names can later be referenced in other expressions. A -definition statement on its own does not cause any states to be generated. It is simply a -description of a machine to be used later. States are generated only when a definition is -instantiated, which happens when a definition is referenced in an instantiated -expression. - -[[instantiation]] -==== Machine Instantiation - --------------- -<name> := <expression>; --------------- - -The machine instantiation statement generates a set of states representing an -expression. Each instantiation generates a distinct set of states. The -starting state of the instantiation is written in the data section of the -generated code using the instantiation name. If a machine named +main+ is -instantiated, its start state is used as the specification's start state and is -assigned to the `cs` variable by the +write init+ command. If no +main+ -machine is given, the start state of the last machine instantiation to appear -is used as the specification's start state. - -From outside the execution loop, control may be passed to any machine by -assigning the entry point to the `cs` variable. From inside the execution -loop, control may be passed to any machine instantiation using `fcall`, -+fgoto+ or +fnext+ statements. - -==== Including Ragel Code - --------------- -include FsmName "inputfile.rl"; --------------- - -The +include+ statement can be used to draw in the statements of another FSM -specification. Both the name and input file are optional, however at least one -must be given. Without an FSM name, the given input file is searched for an FSM -of the same name as the current specification. Without an input file, the -current file is searched for a machine of the given name. If both are present, -the given input file is searched for a machine of the given name. - -Ragel searches for included files from the location of the current file. -Additional directories can be added to the search path using the +-I+ option. - -[[import]] -==== Importing Definitions - --------------- -import "inputfile.h"; --------------- - -The +import+ statement scrapes a file for sequences of tokens that match the -following forms. Ragel treats these forms as state machine definitions. - -* name '=' number -* name '=' lit_string -* 'define' name number -* 'define' name lit_string - -If the input file is a Ragel program then tokens inside any Ragel -specifications are ignored. See the section on <<export, Write Exports>> for a -description of exporting machine definitions. - -Ragel searches for imported files from the location of the current file. -Additional directories can be added to the search path using the +-I+ option. - -[[lexing]] -=== Lexical Analysis of a Ragel Block - -Within a machine specification the following lexical rules apply to the input. - -* The +#+ symbol begins a comment that terminates at the next newline. -* The symbols +""+, +''+, +//+, and +[]+ behave as the -delimiters of literal strings. Within them, the following escape sequences -are interpreted: -+ - \0 \a \b \t \n \v \f \r -+ -A backslash at the end of a line joins the following line onto the current. A -backslash preceding any other character removes special meaning. This applies -to terminating characters and to special characters in regular expression -literals. As an exception, regular expression literals do not support escape -sequences as the operands of a range within a list. See the bullet on regular -expressions in <<basic, Basic Machines>>. - -* The symbols +{}+ delimit a block of host language code that will be -embedded into the machine as an action. Within the block of host language -code, basic lexical analysis of comments and strings is done in order to -correctly find the closing brace of the block. With the exception of FSM -commands embedded in code blocks, the entire block is preserved as is for -identical reproduction in the output code. - -* The pattern `[+-]?[0-9]+` denotes an integer in decimal format. -Integers used for specifying machines may be negative only if the alphabet type -is signed. Integers used for specifying priorities may be positive or negative. - -* The pattern `0x[0-9A-Fa-f]+` denotes an integer in hexadecimal -format. - -* The keywords are -+access+, +action+, +alphtype+, +eof+, +err+, +export+, +from+, +getkey+, -+inwhen+, +lerr+, +machine+, +nfapostpop+, +nfaprepush+, +outwhen+, +postpop+, -+prepush+, +to+, +variable+, +when+ and +write+. - -* The pattern +[a-zA-Z_][a-zA-Z_0-9]*+ denotes an identifier. - -/////////// -.The allowable symbols are: ------------- -( ) ! ^ * ? + : -> - | & . , := = ; > @ $ % ->/ $/ %/ </ @/ <>/ >! $! %! <! @! <>! ->^ $^ %^ <^ @^ <>^ >~ $~ %~ <~ @~ <>~ ->* $* %* <* @* <>* ------------- -/////////// - -* Any amount of whitespace may separate tokens. - -//////////// -=== Parse of an FSM Specification - -The following statements are possible within an FSM specification. The -requirements for trailing semicolons loosely follow that of C. A block -specifying code does not require a trailing semicolon. An expression statement -does require a trailing semicolon. -//////////// - -[[basic]] -=== Basic Machines - -The basic machines are the base operands of regular language expressions. They -are the smallest unit to which machine construction and manipulation operators -can be applied. - -* `'hello'` -- Concatenation Literal. Produces a machine that matches -the sequence of characters in the quoted string. If there are 5 characters -there will be 6 states chained together with the characters in the string. See -the section <<lexing,Lexical Analysis>> for information on valid escape -sequences. -+ -image::bmconcat.png[align="left"] -+ -It is possible to make a concatenation literal case-insensitive by appending an -+i+ to the string, for example `'cmd'i`. - -/////////////// -% GENERATE: bmconcat -% OPT: -p -% %%{ -% machine bmconcat; -.verbatim -main := 'hello'; -.end verbatim -% }%% -% END GENERATE -/////////////// - -* `"hello"` -- Identical to the single quoted version. - -* `[hello]` -- Or Expression. Produces a union of characters. There -will be two states with a transition for each unique character between the two -states. The `[]` delimiters behave like the quotes of a literal string. For -example, `[ \t]` means tab or space. The `or` expression supports -character ranges with the `-` symbol as a separator. The meaning of the union -can be negated using an initial +^+ character as in standard regular -expressions. See <<lexing,Lexical Analysis>> for information on valid escape -sequences in `or` expressions. -+ -image::bmor.png[align="left"] - -///////// -% GENERATE: bmor -% OPT: -p -% %%{ -% machine bmor; -.verbatim -main := [hello]; -.end verbatim -% }%% -% END GENERATE -///////// - -* `''`, `""`, and `[]` -- Zero Length Machine. Produces a machine -that matches the zero length string. Zero length machines have one state that -is both a start state and a final state. -+ -image::bmnull.png[align="left"] - -/////// -% GENERATE: bmnull -% OPT: -p -% %%{ -% machine bmnull; -.verbatim -main := ''; -.end verbatim -% }%% -% END GENERATE -/////// - -//% FIXME: More on the range of values here. -* `42` -- Numerical Literal. Produces a two state machine with one -transition on the given number. The number may be in decimal or hexadecimal -format and should be in the range allowed by the alphabet type. The minimum and -maximum values permitted are defined by the host machine that Ragel is compiled -on. For example, numbers in a `short` alphabet on an i386 machine should be in -the range `-32768` to `32767`. -+ -image::bmnum.png[align="left"] - -/////////// -% GENERATE: bmnum -% %%{ -% machine bmnum; -.verbatim -main := 42; -.end verbatim -% }%% -% END GENERATE -/////////// - -* `/simple_regex/` -- Regular Expression. Regular expressions are -parsed as a series of expressions that are concatenated together. Each -concatenated expression may be a literal character, the `any` character -specified by the `.` symbol, or a union of characters specified by the `[]` -delimiters. If the first character of a union is `^` then it matches any -character not in the list. Within a union, a range of characters can be given -by separating the first and last characters of the range with the `-` symbol. -Each concatenated machine may have repetition specified by following it with -the `*` symbol. The standard escape sequences described in <<lexing, Lexical -Analysis>> are supported everywhere in regular expressions except as the -operands of a range within in a list. This notation also supports the `i` -trailing option. Use it to produce case-insensitive machines, as in `/GET/i`. -+ -Ragel does not support very complex regular expressions because the desired -results can always be achieved using the more general machine construction -operators listed in <<machconst, Regular Language Operators>>. The -following diagram shows the result of compiling `/ab*[c-z].*[123]/`. Note that -in the diagram, `DEF` represents the default transition, which is taken if no -other transition can be taken. -+ -image::bmregex.png[align="left"] - -////////////////// -% GENERATE: bmregex -% OPT: -p -% %%{ -% machine bmregex; -.verbatim -main := /ab*[c-z].*[123]/; -.end verbatim -% }%% -% END GENERATE -////////////////// - -* `'a' .. 'z'` -- Range. Produces a machine that matches any -characters in the specified range. Allowable upper and lower bounds of the -range are concatenation literals of length one and numerical literals. For -example, `0x10..0x20`, `0..63`, and `'a'..'z'` are valid ranges. -The bounds should be in the range allowed by the alphabet type. -+ -image::bmrange.png[align="left"] - -/////////////// -% GENERATE: bmrange -% OPT: -p -% %%{ -% machine bmrange; -.verbatim -main := 'a' .. 'z'; -.end verbatim -% }%% -% END GENERATE -/////////////// - -* `variable_name` -- Lookup the machine definition assigned to the -variable name given and use an instance of it. See <<definition, Machine -Definition>> for an important note on what it means to reference a variable -name. - -* `builtin_machine` -- There are several built-in machines available -for use. They are all two-state machines for the purpose of matching common -classes of characters. They are: - -** `any` -- Any character in the alphabet. - -** `ascii` -- Ascii characters. `0..127` - -** `extend` -- Ascii extended characters. This is the range -`-128..127` for signed alphabets and the range `0..255` for unsigned -alphabets. - -** `alpha` -- Alphabetic characters. `[A-Za-z]` - -** `digit` -- Digits. `[0-9]` - -** `alnum` -- Alpha numerics. `[0-9A-Za-z]` - -** `lower` -- Lowercase characters. `[a-z]` - -** `upper` -- Uppercase characters. `[A-Z]` - -** `xdigit` -- Hexadecimal digits. `[0-9A-Fa-f]` - -** `cntrl` -- Control characters. `0..31`, `127` - -** `graph` -- Graphical characters. `[!-~]` - -** `print` -- Printable characters. `[ -~]` - -** `punct` -- Punctuation. Graphical characters that are not alphanumerics. -+ - [!-/:-@\[-`{-~] - -** `space` -- Whitespace. `[\t\v\f\n\r ]` - -** `zlen` -- Zero length string. `""` - -** `empty` -- Empty set. Matches nothing. `^any` - -=== Operator Precedence - -The following table shows operator precedence from lowest to highest. Operators -in the same precedence group are evaluated from left to right. - -|================================================================================ - ^|1 |`,` | Join - ^|2 |`\| & - --` | Union, Intersection and Subtraction - ^|3 |`. <: :> :>>` | Concatenation - ^|4 |`:` | Label - ^|5 |`->` | Epsilon Transition -1.6+^.^|6 |`> @ $ %` | Transitions Actions and Priorities - |`>/ $/ %/ </ @/ <>/` | EOF Actions - |`>! $! %! <! @! <>!` | Global Error Actions - |`>^ $^ %^ <^ @^ <>^` | Local Error Actions - |`>~ $~ %~ <~ @~ <>~` | To-State Actions - |`>* $* %* <* @* <>*` | From-State Action - ^|7 |`* ** ? + {n} {,n} {n,} {n,m}` | Repetition - ^|8 |`! ^` | Negation and Character-Level Negation - ^|9 |`( <expr> )` | Grouping -|================================================================================ - -[[machconst]] -=== Regular Language Operators - -When using Ragel it is helpful to have a sense of how it constructs machines. -The determinization process can produce results that seem unusual to someone -not familiar with the NFA to DFA conversion algorithm. In this section we -describe Ragel's state machine operators. Though the operators are defined -using epsilon transitions, it should be noted that this is for discussion only. -The epsilon transitions described in this section do not persist, but are -immediately removed by the determinization process which is executed at every -operation. Ragel does not make use of any nondeterministic intermediate state -machines. - -To create an epsilon transition between two states `x` and `y` is to -copy all of the properties of `y` into `x`. This involves drawing in -all of `y`'s to-state actions, EOF actions, etc., in addition to its -transitions. If `x` and `y` both have a transition out on the same -character, then the transitions must be combined. During transition -combination a new transition is made that goes to a new state that is the -combination of both target states. The new combination state is created using -the same epsilon transition method. The new state has an epsilon transition -drawn to all the states that compose it. Since the creation of new epsilon -transitions may be triggered every time an epsilon transition is drawn, the -process of drawing epsilon transitions is repeated until there are no more -epsilon transitions to be made. - -A very common error that is made when using Ragel is to make machines that do -too much. That is, to create machines that have unintentional -nondeterministic properties. This usually results from being unaware of the common strings -between machines that are combined together using the regular language -operators. This can involve never leaving a machine, causing its actions to be -propagated through all the following states. Or it can involve an alternation -where both branches are unintentionally taken simultaneously. - -This problem forces one to think hard about the language that needs to be -matched. To guard against this kind of problem one must ensure that the machine -specification is divided up using boundaries that do not allow ambiguities from -one portion of the machine to the next. See the chapter on -<<controlling_nondeterminism, Controlling Nondeterminism>> for more on this -problem and how to solve it. - -The Graphviz tool is an immense help when debugging improperly compiled -machines or otherwise learning how to use Ragel. Graphviz Dot files can be -generated from Ragel programs using the `-V` option. See the section on -<<visualization, Visualization>> for more information. - -==== Union - --------------- -expr | expr --------------- - -The union operation produces a machine that matches any string in machine one -or machine two. The operation first creates a new start state. Epsilon -transitions are drawn from the new start state to the start states of both -input machines. The resulting machine has a final state set equivalent to the -union of the final state sets of both input machines. In this operation, there -is the opportunity for nondeterminism among both branches. If there are -strings, or prefixes of strings that are matched by both machines then the new -machine will follow both parts of the alternation at once. The union operation is -shown below. - -image::opor.png[align="left"] - -The following example demonstrates the union of three machines representing -common tokens. - -/////////////////// -% GENERATE: exor -% OPT: -p -% %%{ -% machine exor; -/////////////////// ---------------- -# Hex digits, decimal digits, or identifiers -main := '0x' xdigit+ | digit+ | alpha alnum*; ---------------- -/////////////////// -% }%% -% END GENERATE -/////////////////// - -image::exor.png[align="left"] - -==== Intersection - --------------- -expr & expr --------------- - -Intersection produces a machine that matches any string that is in both machine -one and machine two. To achieve intersection, a union is performed on the two -machines. After the result has been made deterministic, any final state that is -not a combination of final states from both machines has its final state status -revoked. To complete the operation, paths that do not lead to a final state are -pruned from the machine. Therefore, if there are any such paths in either of -the expressions they will be removed by the intersection operator. -Intersection can be used to require that two independent patterns be -simultaneously satisfied as in the following example. - -//////////////////// -% GENERATE: exinter -% OPT: -p -% %%{ -% machine exinter; -//////////////////// ----------------- -# Match lines four characters wide that contain -# words separated by whitespace. -main := - /[^\n][^\n][^\n][^\n]\n/* & - (/[a-z][a-z]*/ | [ \n])**; ----------------- -//////////////////// -% }%% -% END GENERATE -//////////////////// - -image::exinter.png[align="left"] - -==== Difference - ----------------- -expr - expr ----------------- - -The difference operation produces a machine that matches -strings that are in machine one but are not in machine two. To achieve subtraction, -a union is performed on the two machines. After the result has been made -deterministic, any final state that came from machine two or is a combination -of states involving a final state from machine two has its final state status -revoked. As with intersection, the operation is completed by pruning any path -that does not lead to a final state. The following example demonstrates the -use of subtraction to exclude specific cases from a set. - -////////////////////// -% GENERATE: exsubtr -% OPT: -p -% %%{ -% machine exsubtr; -////////////////////// ---------------------------- -# Subtract keywords from identifiers. -main := /[a-z][a-z]*/ - ( 'for' | 'int' ); ---------------------------- -///////////////// -% }%% -% END GENERATE -///////////////// - -image::exsubtr.png[align="left"] - -[[strong_difference]] -==== Strong Difference - ---------------- -expr -- expr ---------------- - -Strong difference produces a machine that matches any string of the first -machine that does not have any string of the second machine as a substring. In -the following example, strong subtraction is used to excluded `CRLF` from -a sequence. In the corresponding visualization, the label `DEF` is short -for default. The default transition is taken if no other transition can be -taken. - -///////////////// -% GENERATE: exstrongsubtr -% OPT: -p -% %%{ -% machine exstrongsubtr; -///////////////// ------------------ -crlf = '\r\n'; -main := [a-z]+ ':' ( any* -- crlf ) crlf; ------------------ -///////////////// -% }%% -% END GENERATE -///////////////// - -image::exstrongsubtr.png[align="left"] - -This operator is equivalent to the following. - ---------------- -expr - ( any* expr any* ) ---------------- - -==== Concatenation - --------------- -expr . expr --------------- - -Concatenation produces a machine that matches all the strings in machine one -followed by all the strings in machine two. Concatenation draws epsilon -transitions from the final states of the first machine to the start state of -the second machine. The final states of the first machine lose their final -state status, unless the start state of the second machine is final as well. -Concatenation is the default operator. Two machines next to each other with no -operator between them results in concatenation. - -image::opconcat.png[align="left"] - -The opportunity for nondeterministic behaviour results from the possibility of -the final states of the first machine accepting a string that is also accepted -by the start state of the second machine. -The most common scenario in which this happens is the -concatenation of a machine that repeats some pattern with a machine that gives -a terminating string, but the repetition machine does not exclude the -terminating string. The example in <<strong_difference, Strong Difference>> -guards against this. Another example is the expression `("'" any* "'")`. -When executed the thread of control will -never leave the `any*` machine. This is a problem especially if actions -are embedded to process the characters of the `any*` component. - -In the following example, the first machine is always active due to the -nondeterministic nature of concatenation. This particular nondeterminism is intended, -however, because we wish to permit EOF strings before the end of the input. - -//////////////////////// -% GENERATE: exconcat -% OPT: -p -% %%{ -% machine exconcat; -//////////////////////// ----------------------- -# Require an eof marker on the last line. -main := /[^\n]*\n/* . 'EOF\n'; ----------------------- -//////////////////// -% }%% -% END GENERATE -//////////////////// - -image::exconcat.png[align="left"] - -There is a language ambiguity involving concatenation and subtraction. Because -concatenation is the default operator for two adjacent machines there is an -ambiguity between subtraction of a positive numerical literal and concatenation -of a negative numerical literal. For example, `(x-7)` could be interpreted as -`(x . -7)` or `(x - 7)`. In the Ragel language, the subtraction operator always -takes precedence over concatenation of a negative literal. We adhere to the -rule that the default concatenation operator takes effect only when there are -no other operators between two machines. Beware of writing machines such as -`(any -1)` when what is desired is a concatenation of `any` and `-1`. Instead -write `(any . -1)` or `(any (-1))`. If in doubt of the meaning of your program -do not rely on the default concatenation operator; always use the `.` symbol. - -==== Kleene Star - ---------------- -expr* ---------------- - -The machine resulting from the Kleene Star operator will match zero or more -repetitions of the machine it is applied to. -It creates a new start state and an additional final -state. Epsilon transitions are drawn between the new start state and the old start -state, between the new start state and the new final state, and -between the final states of the machine and the new start state. After the -machine is made deterministic, the final states get all the -transitions of the start state. - -image::opstar.png[align="left"] - -The possibility for nondeterministic behaviour arises if the final states have -transitions on any of the same characters as the start state. This is common -when applying kleene star to an alternation of tokens. Like the other problems -arising from nondeterministic behavior, this is discussed in more detail in the chapter on -<<controlling_nondeterminism, Controlling Nondeterminism>>. This particular -problem can also be solved using the longest-match construction discussed in the section -on <<generating_scanners, Scanners>>. - -In this example, there is no nondeterminism introduced by the exterior kleene -star due to the newline at the end of the regular expression. Without the -newline the exterior kleene star would be redundant and there would be -ambiguity between repeating the inner range of the regular expression and the -entire regular expression. Though it would not cause a problem in this case, -unnecessary nondeterminism in the kleene star operator often causes undesired -results for new Ragel users and must be guarded against. - -/////////////// -% GENERATE: exstar -% OPT: -p -% %%{ -% machine exstar; -/////////////// ------------------- -# Match any number of lines with only lowercase letters. -main := /[a-z]*\n/*; ------------------- -/////////////// -% }%% -% END GENERATE -/////////////// - -image::exstar.png[align="left"] - -==== One Or More Repetition - ------------ -expr+ ------------ - -This operator produces the concatenation of the machine with the kleene star of -itself. The result will match one or more repetitions of the machine. The plus -operator is equivalent to `(expr . expr*)`. - -///////////////////// -% GENERATE: explus -% OPT: -p -% %%{ -% machine explus; -///////////////////// ----------------------- -# Match alpha-numeric words. -main := alnum+; ----------------------- -//////////////// -% }%% -% END GENERATE -//////////////// - -image::explus.png[align="left"] - -==== Optional - ---------------- -expr? ---------------- - -The _optional_ operator produces a machine that accepts the machine -given or the zero length string. The optional operator is equivalent to -`(expr | '' )`. In the following example the optional operator is used to -possibly extend a token. - -/////////////// -% GENERATE: exoption -% OPT: -p -% %%{ -% machine exoption; -/////////////// ---------------- -# Match integers or floats. -main := digit+ ('.' digit+)?; ---------------- -///////////////// -% }%% -% END GENERATE -///////////////// - -image::exoption.png[align="left"] - -==== Repetition - -* `expr {n}` -- Exactly N copies of expr. -* `expr {,n}` -- Zero to N copies of expr. -* `expr {n,}` -- N or more copies of expr. -* `expr {n,m}` -- N to M copies of expr. - -==== Negation - --------------- -!expr --------------- - -Negation produces a machine that matches any string not matched by the given -machine. Negation is equivalent to `(any* - expr)`. - -////////////////////// -% GENERATE: exnegate -% OPT: -p -% %%{ -% machine exnegate; -////////////////////// --------------------- -# Accept anything but a string beginning with a digit. -main := ! ( digit any* ); --------------------- -////////////////////// -% }%% -% END GENERATE -////////////////////// - -image::exnegate.png[align="left"] - -==== Character-Level Negation - --------------- -^expr --------------- - -Character-level negation produces a machine that matches any single character -not matched by the given machine. Character-Level Negation is equivalent to -`(any - expr)`. It must be applied only to machines that match strings of -length one. - -=== State Machine Minimization - -State machine minimization is the process of finding the minimal equivalent FSM accepting -the language. Minimization reduces the number of states in machines -by merging equivalent states. It does not change the behaviour of the machine -in any way. It will cause some states to be merged into one because they are -functionally equivalent. State minimization is on by default. It can be turned -off with the `-n` option. - -The algorithm implemented is similar to Hopcroft's state minimization -algorithm. Hopcroft's algorithm assumes a finite alphabet that can be listed in -memory, whereas Ragel supports arbitrary integer alphabets that cannot be -listed in memory. Though exact analysis is very difficult, Ragel minimization -runs close to O(n * log(n)) and requires O(n) temporary storage where -$n$ is the number of states. - -[[visualization]] -=== Visualization - -///////// -%In many cases, practical -%parsing programs will be too large to completely visualize with Graphviz. The -%proper approach is to reduce the language to the smallest subset possible that -%still exhibits the characteristics that one wishes to learn about or to fix. -%This can be done without modifying the source code using the `-M` and -%`-S` options. If a machine cannot be easily reduced, -%embeddings of unique actions can be very useful for tracing a -%particular component of a larger machine specification, since action names are -%written out on transition labels. -///////// - -Ragel is able to emit compiled state machines in Graphviz's Dot file format. -This is done using the `-V` option. -Graphviz support allows users to perform -incremental visualization of their parsers. User actions are displayed on -transition labels of the graph. - -If the final graph is too large to be -meaningful, or even drawn, the user is able to inspect portions of the parser -by naming particular regular expression definitions with the `-S` and -`-M` options to the `ragel` program. Use of Graphviz greatly -improves the Ragel programming experience. It allows users to learn Ragel by -experimentation and also to track down bugs caused by unintended -nondeterminism. - -Ragel has another option to help debugging. The `-x` option causes Ragel -to emit the compiled machine in an XML format. - -== User Actions - -Ragel permits the user to embed actions into the transitions of a regular -expression's corresponding state machine. These actions are executed when the -generated code moves over a transition. Like the regular expression operators, -the action embedding operators are fully compositional. They take a state -machine and an action as input, embed the action and yield a new state machine -that can be used in the construction of other machines. Due to the -compositional nature of embeddings, the user has complete freedom in the -placement of actions. - -A machine's transitions are categorized into four classes. The action embedding -operators access the transitions defined by these classes. The -_entering transition_ operator `>` isolates the start state, then embeds an action -into all transitions leaving it. The _finishing transition_ operator -`@` embeds an action into all transitions going into a final state. The -_all transition_ operator `$` embeds an action into all transitions of -an expression. The _leaving transition_ operator `%` provides access -to the yet-unmade transitions moving out of the machine via the final states. - -=== Embedding Actions - ---------------- -action ActionName { - /* Code an action here. */ - count += 1; -} ---------------- - -The action statement defines a block of code that can be embedded into an FSM. -Action names can be referenced by the action embedding operators in -expressions. Though actions need not be named in this way (literal blocks -of code can be embedded directly when building machines), defining reusable -blocks of code whenever possible is good practice because it potentially increases the -degree to which the machine can be minimized. - -Within an action some Ragel expressions and statements are parsed and -translated. These allow the user to interact with the machine from action code. -See <<vals, Values and Statements>> for a complete list of values and -statements available in code blocks. - -==== Entering Action - ----------------------- -expr > action ----------------------- - -The entering action operator embeds an action into all transitions -that enter into the machine from the start state. If the start state is final, -then the action is also embedded into the start state as a leaving action. This -means that if a machine accepts the zero-length string and control passes -through the start state then the entering action is executed. Note -that this can happen on both a following character and on the EOF event. - -In some machines, the start state has transtions coming in from within the -machine. In these cases the start state is first isolated from the rest of the -machine ensuring that the entering actions are executed once only. - -//////////////// -% GENERATE: exstact -% OPT: -p -% %%{ -% machine exstact; -//////////////// --------------------- -# Execute A at the beginning of a string of alpha. -action A {} -main := ( lower* >A ) . ' '; --------------------- -////////////////// -% }%% -% END GENERATE -////////////////// - -image::exstact.png[align="left"] - -==== Finishing Action - ------------- -expr @ action ------------- - -The finishing action operator embeds an action into any transitions that move -the machine into a final state. Further input may move the machine out of the -final state, but keep it in the machine. Therefore, finishing actions may be -executed more than once if a machine has any internal transitions out of a -final state. In the following example, the final state has no transitions out -and the finishing action is executed only once. - -//////////////////////// -% GENERATE: exdoneact -% OPT: -p -% %%{ -% machine exdoneact; -% action A {} -//////////////////////// --------------------- -# Execute A when the trailing space is seen. -main := ( lower* ' ' ) @A; --------------------- -//////////////////////// -% }%% -% END GENERATE -//////////////////////// - -image::exdoneact.png[align="left"] - -==== All Transition Action - ------------- -expr $ action ------------- - -The all transition operator embeds an action into all transitions of a machine. -The action is executed whenever a transition of the machine is taken. In the -following example, A is executed on every character matched. - -/////////////////// -% GENERATE: exallact -% OPT: -p -% %%{ -% machine exallact; -% action A {} -/////////////////// ---------------------- -# Execute A on any characters of the machine. -main := ( 'm1' | 'm2' ) $A; ---------------------- -///////////////////// -% }%% -% END GENERATE -///////////////////// - -image::exallact.png[align="left"] - -[[out_actions]] -==== Leaving Actions - ---------------- -expr % action ---------------- - -The leaving action operator queues an action for embedding into the transitions -that go out of a machine via a final state. The action is first stored in -the machine's final states and is later transferred to any transitions that are -made going out of the machine by a kleene star or concatenation operation. - -If a final state of the machine is still final when compilation is complete -then the leaving action is also embedded as an EOF action. Therefore, leaving -the machine is defined as either leaving on a character or as state machine -acceptance. - -This operator allows one to associate an action with the termination of a -sequence, without being concerned about what particular character terminates -the sequence. In the following example, A is executed when leaving the alpha -machine on the newline character. - -////////////// -% GENERATE: exoutact1 -% OPT: -p -% %%{ -% machine exoutact1; -% action A {} -////////////// ----------------- -# Match a word followed by a newline. Execute A when -# finishing the word. -main := ( lower+ %A ) . '\n'; ----------------- -////////////// -% }%% -% END GENERATE -////////////// - -image::exoutact1.png[align="left"] - -In the following example, the `term_word` action could be used to register -the appearance of a word and to clear the buffer that the `lower` action used -to store the text of it. - -//////////////////// -% GENERATE: exoutact2 -% OPT: -p -% %%{ -% machine exoutact2; -% action lower {} -% action space {} -% action term_word {} -% action newline {} -//////////////////// --------------------- -word = ( [a-z] @lower )+ %term_word; -main := word ( ' ' @space word )* '\n' @newline; --------------------- -//////////////// -% }%% -% END GENERATE -//////////////// - -image::exoutact2.png[align="left"] - -In this final example of the action embedding operators, A is executed upon entering -the alpha machine, B is executed on all transitions of the -alpha machine, C is executed when the alpha machine is exited by moving into the -newline machine and N is executed when the newline machine moves into a final -state. - -//////////////////// -% GENERATE: exaction -% OPT: -p -% %%{ -% machine exaction; -% action A {} -% action B {} -% action C {} -% action N {} -//////////////////// ----------------------- -# Execute A on starting the alpha machine, B on every transition -# moving through it and C upon finishing. Execute N on the newline. -main := ( lower* >A $B %C ) . '\n' @N; ----------------------- -//////////////////// -% }%% -% END GENERATE -//////////////////// - -image::exaction.png[align="left"] - -=== State Action Embedding Operators - -The state embedding operators allow one to embed actions into states. Like the -transition embedding operators, there are several different classes of states -that the operators access. The meanings of the symbols are similar to the -meanings of the symbols used for the transition embedding operators. The design -of the state selections was driven by a need to cover the states of an -expression with exactly one error action. - -Unlike the transition embedding operators, the state embedding operators are -also distinguished by the different kinds of events that embedded actions can -be associated with. Therefore the state embedding operators have two -components. The first, which is the first one or two characters, specifies the -class of states that the action will be embedded into. The second component -specifies the type of event the action will be executed on. The symbols of the -second component also have equivalent keywords. - -The different classes of states are: - -* `>` -- the start state -* `<` -- any state except the start state -* `$` -- all states -* `%` -- final states -* `@` -- any state except final states -* `<>` -- any except start and final (middle) - -The different kinds of embeddings are: - -* `~` -- to-state actions (`to`) -* `*` -- from-state actions (`from`) -* `/` -- EOF actions (`eof`) -* `!` -- error actions (`err`) -* `^` -- local error actions (`lerr`) - -==== To-State and From-State Actions - -===== To-State Actions - -* `>~action >to(name) >to{...}` -- the start state -* `<~action <to(name) <to{...}` -- any state except the start state -* `$~action $to(name) $to{...}` -- all states -* `%~action %to(name) %to{...}` -- final states -* `@~action @to(name) @to{...}` -- any state except final states -* `<>~action <>to(name) <>to{...}` -- any except start and final (middle) - - -To-state actions are executed whenever the state machine moves into the -specified state, either by a natural movement over a transition or by an -action-based transfer of control such as `fgoto`. They are executed after the -in-transition's actions but before the current character is advanced and -tested against the end of the input block. To-state embeddings stay with the -state. They are irrespective of the state's current set of transitions and any -future transitions that may be added in or out of the state. - -Note that the setting of the current state variable `cs` outside of the -execute code is not considered by Ragel as moving into a state and consequently -the to-state actions of the new current state are not executed. This includes -the initialization of the current state when the machine begins. This is -because the entry point into the machine execution code is after the execution -of to-state actions. - -===== From-State Actions - -* `>*action >from(name) >from{...}` -- the start state -* `<*action <from(name) <from{...}` -- any state except the start state -* `$*action $from(name) $from{...}` -- all states -* `%*action %from(name) %from{...}` -- final states -* `@*action @from(name) @from{...}` -- any state except final states -* `<>*action <>from(name) <>from{...}` -- any except start and final (middle) - -From-state actions are executed whenever the state machine takes a transition from a -state, either to itself or to some other state. These actions are executed -immediately after the current character is tested against the input block end -marker and before the transition to take is sought based on the current -character. From-state actions are therefore executed even if a transition -cannot be found and the machine moves into the error state. Like to-state -embeddings, from-state embeddings stay with the state. - -==== EOF Actions - -* `>/action >eof(name) >eof{...}` -- the start state -* `</action <eof(name) <eof{...}` -- any state except the start state -* `$/action $eof(name) $eof{...}` -- all states -* `%/action %eof(name) %eof{...}` -- final states -* `@/action @eof(name) @eof{...}` -- any state except final states -* `<>/action <>eof(name) <>eof{...}` -- any except start and final (middle) - -The EOF action embedding operators enable the user to embed actions that are -executed at the end of the input stream. EOF actions are stored in states and -generated in the `write exec` block. They are run when `p == pe == eof` -as the execute block is finishing. EOF actions are free to adjust `p` -and jump to another part of the machine to restart execution. - -==== Handling Errors - -In many applications it is useful to be able to react to parsing errors. The -user may wish to print an error message that depends on the context. It may -also be desirable to consume input in an attempt to return the input stream to -some known state and resume parsing. To support error handling and recovery, -Ragel provides error action embedding operators. There are two kinds of error -actions: global error actions and local error actions. Error actions can be -used to simply report errors, or by jumping to a machine instantiation that -consumes input, can attempt to recover from errors. - -===== Global Error Actions - -* `>!action >err(name) >err{...}` -- the start state -* `<!action <err(name) <err{...}` -- any state except the start state -* `$!action $err(name) $err{...}` -- all states -* `%!action %err(name) %err{...}` -- final states -* `@!action @err(name) @err{...}` -- any state except final states -* `<>!action <>err(name) <>err{...}` -- any except start and final (middle) - -Global error actions are stored in the states they are embedded into until -compilation is complete. They are then transferred to the transitions that move -into the error state. These transitions are taken on all input characters that -are not already covered by the state's transitions. If a state with an error -action is not final when compilation is complete, then the action is also -embedded as an EOF action. - -Error actions can be used to recover from errors by jumping back into the -machine with `fgoto` and optionally altering `p`. - -===== Local Error Actions - -* `>^action >lerr(name) >lerr{...}` -- the start state -* `<^action <lerr(name) <lerr{...}` -- any state except the start state -* `$^action $lerr(name) $lerr{...}` -- all states -* `%^action %lerr(name) %lerr{...}` -- final states -* `@^action @lerr(name) @lerr{...}` -- any state except final states -* `<>^action <>lerr(name) <>lerr{...}` -- any except start and final (middle) - -Like global error actions, local error actions are also stored in the states -they are embedded into until a transfer point. The transfer point is different -however. Each local error action embedding is associated with a name. When a -machine definition has been fully constructed, all local error action -embeddings associated with the same name as the machine definition are -transferred to the error transitions. At this time they are also embedded as -EOF actions in the case of non-final states. - -Local error actions can be used to specify an action to take when a particular -section of a larger state machine fails to match. A particular machine -definition's ``thread'' may die and the local error actions executed, however -the machine as a whole may continue to match input. - -There are two forms of local error action embeddings. In the first form the -name defaults to the current machine. In the second form the machine name can -be specified. This is useful when it is more convenient to specify the local -error action in a sub-definition that is used to construct the machine -definition that the local error action is associated with. To embed local error -actions and explicitly state the machine definition on which the transfer is to -happen use `(name, action)` as the action. - -===== Example - -The following example uses error actions to report an error and jump to a -machine that consumes the remainder of the line when parsing fails. After -consuming the line, the error recovery machine returns to the main loop. - -////////////////////////// -% GENERATE: erract -% %%{ -% machine erract; -% ws = ' '; -% address = 'foo AT bar..com'; -% date = 'Monday May 12'; -////////////////////////// ----------------------------- -action cmd_err { - printf( "command error\n" ); - fhold; fgoto line; -} -action from_err { - printf( "from error\n" ); - fhold; fgoto line; -} -action to_err { - printf( "to error\n" ); - fhold; fgoto line; -} - -line := [^\n]* '\n' @{ fgoto main; }; - -main := ( - ( - 'from' @err(cmd_err) - ( ws+ address ws+ date '\n' ) $err(from_err) | - 'to' @err(cmd_err) - ( ws+ address '\n' ) $err(to_err) - ) -)*; ----------------------------- -////////////////////// -% }%% -% %% write data; -% void f() -% { -% %% write init; -% %% write exec; -% } -% END GENERATE -////////////////////// - - -=== Action Ordering and Duplicates - -When combining expressions that have embedded actions it is often the case that -a number of actions must be executed on a single input character. For example, -following a concatenation the leaving action of the left expression and the -entering action of the right expression will be embedded into one transition. -This requires a method of ordering actions that is intuitive and -predictable for the user, and repeatable for the compiler. - -We associate with the embedding of each action a unique timestamp that is -used to order actions that appear together on a single transition in the final -state machine. To accomplish this, we recursively traverse the parse tree of -regular expressions and assign timestamps to action embeddings. References to -machine definitions are followed in the traversal. When we visit a -parse tree node, we assign timestamps to all _entering_ action embeddings, -recurse on the parse tree, then assign timestamps to the remaining _all_, -_finishing_, and _leaving_ embeddings in the order in which they -appear. - -By default Ragel does not permit a single action to appear multiple times in an action -list. When the final machine has been created, actions that appear more than -once in a single transition, to-state, from-state or EOF action list have their -duplicates removed. -The first appearance of the action is preserved. This is useful in a number of -scenarios. First, it allows us to union machines with common prefixes without -worrying about the action embeddings in the prefix being duplicated. Second, it -prevents leaving actions from being transferred multiple times. This can -happen when a machine is repeated, then followed with another machine that -begins with a common character. For example: - ----------------- -word = [a-z]+ %act; -main := word ( '\n' word )* '\n\n'; ----------------- - -Note that Ragel does not compare action bodies to determine if they have -identical program text. It simply checks for duplicates using each action -block's unique location in the program. - -The removal of duplicates can be turned off using the `-d` option. - -[[vals]] -=== Values and Statements Available in Code Blocks - -The following values are available in code blocks: - -* `fpc` -- A pointer to the current character. This is equivalent to -accessing the `p` variable. - -* `fc` -- The current character. This is equivalent to the expression `(*p)`. - -* `fcurs` -- An integer value representing the current state. This -value should only be read from. To move to a different place in the machine -from action code use the `fgoto`, `fnext` or `fcall` statements. Outside of the -machine execution code the `cs` variable may be modified. - -* `ftargs` -- An integer value representing the target state. This -value should only be read from. Again, `fgoto`, `fnext` and -`fcall` can be used to move to a specific entry point. - -* `fentry(<label>)` -- Retrieve an integer value representing the -entry point `label`. The integer value returned will be a compile time -constant. This number is suitable for later use in control flow transfer -statements that take an expression. This value should not be compared against -the current state because any given label can have multiple states representing -it. The value returned by `fentry` can be any one of the multiple states that -it represents. - -The following statements are available in code blocks: - -* `fhold;` -- Do not advance over the current character. If processing -data in multiple buffer blocks, the `fhold` statement should only be used -once in the set of actions executed on a character. Multiple calls may result -in backing up over the beginning of the buffer block. The `fhold` -statement does not imply any transfer of control. It is equivalent to the -`p--;` statement. - -* `fexec <expr>;` -- Set the next character to process. This can be -used to backtrack to previous input or advance ahead. Unlike `fhold`, which can -be used anywhere, `fexec` requires the user to ensure that the target of the -backtrack is in the current buffer block or is known to be somewhere ahead of -it. The machine will continue iterating forward until `pe` is arrived at, -`fbreak` is called or the machine moves into the error state. In actions -embedded into transitions, the `fexec` statement is equivalent to setting `p` -to one position ahead of the next character to process. If the user also -modifies `pe`, it is possible to change the buffer block entirely. - -* `fgoto <label>;` -- Jump to an entry point defined by -`<label>`. The `fgoto` statement immediately transfers control to -the destination state. - -* `fgoto *<expr>;` -- Jump to an entry point given by `<expr>`. -The expression must evaluate to an integer value representing a state. - -* `fnext <label>;` -- Set the next state to be the entry point defined -by `label`. The `fnext` statement does not immediately jump to the specified -state. Any action code following the statement is executed. - -* `fnext *<expr>;` -- Set the next state to be the entry point given -by `<expr>`. The expression must evaluate to an integer value representing -a state. - -* `fcall <label>;` -- Push the target state and jump to the entry -point defined by `<label>`. The next `fret` will jump to the target -of the transition on which the call was made. Use of `fcall` requires -the declaration of a call stack. An array of integers named `stack` and a -single integer named `top` must be declared. With the `fcall` -construct, control is immediately transferred to the destination state. -See <<modularization, Parser Modularization>> for more information. - -* `fcall *<expr>;` -- Push the current state and jump to the entry -point given by `<expr>`. The expression must evaluate to an integer value -representing a state. - -* `fret;` -- Return to the target state of the transition on which the -last `fcall` was made. Use of `fret` requires the declaration of a -call stack. Control is immediately transferred to the destination state. - -* `fbreak;` -- Advance `p`, save the target state to `cs` -and immediately break out of the execute loop. This statement is useful in -conjunction with the `noend` write option. Rather than process input until `pe` -is arrived at, the `fbreak` statement can be used to stop processing from an -action. After an `fbreak` statement the `p` variable will point to the next -character in the input. The current state will be the target of the current -transition. Note that `fbreak` causes the target state's to-state actions to be -skipped. - -Once actions with control-flow commands are embedded into a -machine, the user must exercise caution when using the machine as the operand -to other machine construction operators. If an action jumps to another state -then unioning any transition that executes that action with another transition -that follows some other path will cause that other path to be lost. Using -commands that manually jump around a machine takes us out of the domain of -regular languages because transitions that the -machine construction operators are not aware of are introduced. These -commands should therefore be used with caution. - - -[[controlling_nondeterminism]] -== Controlling Nondeterminism - -Along with the flexibility of arbitrary action embeddings comes a need to -control nondeterminism in regular expressions. If a regular expression is -ambiguous, then sub-components of a parser other than the intended parts may become -active. This means that actions that are irrelevant to the -current subset of the parser may be executed, causing problems for the -programmer. - -Tools that are based on regular expression engines and that are used for -recognition tasks will usually function as intended regardless of the presence -of ambiguities. It is quite common for users of scripting languages to write -regular expressions that are heavily ambiguous and it generally does not -matter. As long as one of the potential matches is recognized, there can be any -number of other matches present. In some parsing systems the run-time engine -can employ a strategy for resolving ambiguities, for example always pursuing -the longest possible match and discarding others. - -In Ragel, there is no regular expression run-time engine, just a simple state -machine execution model. When we begin to embed actions and face the -possibility of spurious action execution, it becomes clear that controlling -nondeterminism at the machine construction level is very important. Consider -the following example. - -//////////////////////// -% GENERATE: lines1 -% OPT: -p -% %%{ -% machine lines1; -% action first {} -% action tail {} -% word = [a-z]+; -//////////////////////// ---------------------------- -ws = [\n\t ]; -line = word $first ( ws word $tail )* '\n'; -lines = line*; ---------------------------- -//////////////////////// -% main := lines; -% }%% -% END GENERATE -//////////////////////// - -image::lines1.png[align="left"] - -Since the `ws` expression includes the newline character, we will -not finish the `line` expression when a newline character is seen. We will -simultaneously pursue the possibility of matching further words on the same -line and the possibility of matching a second line. Evidence of this fact is -in the state tables. On several transitions both the `first` and -`tail` actions are executed. The solution here is simple: exclude -the newline character from the `ws` expression. - -/////////////////////////// -% GENERATE: lines2 -% OPT: -p -% %%{ -% machine lines2; -% action first {} -% action tail {} -% word = [a-z]+; -/////////////////////////// ----------------------- -ws = [\t ]; -line = word $first ( ws word $tail )* '\n'; -lines = line*; ----------------------- -/////////////////////////// -% main := lines; -% }%% -% END GENERATE -/////////////////////////// - -image::lines2.png[align="left"] - -Solving this kind of problem is straightforward when the ambiguity is created -by strings that are a single character long. When the ambiguity is created by -strings that are multiple characters long we have a more difficult problem. The -following example is an incorrect attempt at a regular expression for C -language comments. - -///////////////////////////// -% GENERATE: comments1 -% OPT: -p -% %%{ -% machine comments1; -% action comm {} -///////////////////////////// -------------------------- -comment = '/*' ( any @comm )* '*/'; -main := comment ' '; -------------------------- -///////////////////////////// -% }%% -% END GENERATE -///////////////////////////// - -image::comments1.png[align="left"] - -Using standard concatenation, we will never leave the `any*` expression. -We will forever entertain the possibility that a `'*/'` string that we see -is contained in a longer comment and that, simultaneously, the comment has -ended. The concatenation of the `comment` machine with `SP` is done -to show this. When we match space, we are also still matching the comment body. - -One way to approach the problem is to exclude the terminating string from the -`any*` expression using set difference. We must be careful to exclude not just -the terminating string, but any string that contains it as a substring. A -verbose, but proper specification of a C comment parser is given by the -following regular expression. - -//////////////////////// -% GENERATE: comments2 -% OPT: -p -% %%{ -% machine comments2; -% action comm {} -//////////////////////// -------------------- -comment = '/*' ( ( any @comm )* - ( any* '*/' any* ) ) '*/'; -------------------- -//////////////////////// -% main := comment; -% }%% -% END GENERATE -//////////////////////// - -image::comments2.png[align="left"] - -Note that Ragel's strong subtraction operator `--` can also be used here. -In doing this subtraction we have phrased the problem of controlling -non-determinism in terms of excluding strings common to two expressions that -interact when combined. We can also phrase the problem in terms of the -transitions of the state machines that implement these expressions. During the -concatenation of `any*` and `'*/'` we will be making transitions that are -composed of both the loop of the first expression and the final character of -the second. At this time we want the transition on the `'/'` character to take -precedence over and disallow the transition that originated in the `any*` loop. - -In another parsing problem, we wish to implement a lightweight tokenizer that -we can utilize in the composition of a larger machine. For example, some HTTP -headers have a token stream as a sub-language. The following example is an -attempt at a regular expression-based tokenizer that does not function -correctly due to unintended nondeterminism. - -///////////////////////////// -% GENERATE: smallscanner -% OPT: -p -% %%{ -% machine smallscanner; -% action start_str {} -% action on_char {} -% action finish_str {} -///////////////////////////// --------------------------- -header_contents = ( - lower+ >start_str $on_char %finish_str | - ' ' -)*; --------------------------- -///////////////////////////// -% main := header_contents; -% }%% -% END GENERATE -///////////////////////////// - -image::smallscanner.png[align="left"] - -In this case, the problem with using a standard kleene star operation is that -there is an ambiguity between extending a token and wrapping around the machine -to begin a new token. Using the standard operator, we get an undesirable -nondeterministic behaviour. Evidence of this can be seen on the transition out -of state one, back to itself. The transition extends the string, and -simultaneously, finishes the string only to immediately begin a new one. What -is required is for the transitions that represent an extension of a token to -take precedence over the transitions that represent the beginning of a new -token. For this problem there is no simple solution that uses standard regular -expression operators. - -=== Priorities - -A priority mechanism was devised and built into the determinization process, -specifically for the purpose of allowing the user to control nondeterminism. -Priorities are integer values embedded into transitions. When the -determinization process is combining transitions that have different -priorities, the transition with the higher priority is preserved and the -transition with the lower priority is dropped. - -Unfortunately, priorities can have unintended side effects because their -operation requires that they linger in transitions indefinitely. They must -linger because the Ragel program cannot know when the user is finished with a -priority embedding. A solution whereby they are explicitly deleted after use -is conceivable; however this is not very user-friendly. Priorities were -therefore made into named entities. Only priorities with the same name are -allowed to interact. This allows any number of priorities to coexist in one -machine for the purpose of controlling various different regular expression -operations and eliminates the need to ever delete them. Such a scheme allows -the user to choose a unique name, embed two different priority values using -that name and be confident that the priority embedding will be free of any side -effects. - -In the first form of priority embedding, the name defaults to the name of the -machine definition that the priority is assigned in. In this sense priorities -are by default local to the current machine definition or instantiation. Beware -of using this form in a longest-match machine, since there is only one name for -the entire set of longest match patterns. In the second form the priority's -name can be specified, allowing priority interaction across machine definition -boundaries. - -* `expr > int` -- Sets starting transitions to have priority int. -* `expr @ int` -- Sets transitions that go into a final state to have priority int. -* `expr $ int` -- Sets all transitions to have priority int. -* `expr % int` -- Sets leaving transitions to -have priority int. When a transition is made going out of the machine (either -by concatenation or kleene star) its priority is immediately set to the leaving -priority. - -The second form of priority assignment allows the programmer to specify the -name to which the priority is assigned. - -* `expr > (name, int)` -- Starting transitions. -* `expr @ (name, int)` -- Finishing transitions (into a final state). -* `expr $ (name, int)` -- All transitions. -* `expr % (name, int)` -- Leaving transitions. - -=== Guarded Operators that Encapsulate Priorities - -Priority embeddings are a very expressive mechanism. At the same time they -can be very confusing for the user. They force the user to imagine -the transitions inside two interacting expressions and work out the precise -effects of the operations between them. When we consider -that this problem is worsened by the -potential for side effects caused by unintended priority name collisions, we -see that exposing the user to priorities is undesirable. - -Fortunately, in practice the use of priorities has been necessary only in a -small number of scenarios. This allows us to encapsulate their functionality -into a small set of operators and fully hide them from the user. This is -advantageous from a language design point of view because it greatly simplifies -the design. - -Going back to the C comment example, we can now properly specify it using a -guarded concatenation operator which we call _finish-guarded concatenation_. -From the user's point of view, this operator terminates the first machine when -the second machine moves into a final state. It chooses a unique name and uses -it to embed a low priority into all transitions of the first machine. A higher -priority is then embedded into the transitions of the second machine that enter -into a final state. The following example yields a machine identical to the -example in the section on <<controlling_nondeterminism,Controlling -Nondeterminism>>. - ----------------- -comment = '/*' ( any @comm )* :>> '*/'; ----------------- - -image::comments2.png[align="left"] - -Another guarded operator is _left-guarded concatenation_, given by the -`<:` compound symbol. This operator places a higher priority on all -transitions of the first machine. This is useful if one must forcibly separate -two lists that contain common elements. For example, one may need to tokenize a -stream, but first consume leading whitespace. - -Ragel also includes a _longest-match kleene star_ operator, given by the `**` -compound symbol. This guarded operator embeds a high priority into all -transitions of the machine. A lower priority is then embedded into the leaving -transitions. When the kleene star operator makes the epsilon transitions from -the final states into the new start state, the lower priority will be -transferred to the epsilon transitions. In cases where following an epsilon -transition out of a final state conflicts with an existing transition out of a -final state, the epsilon transition will be dropped. - -Other guarded operators are conceivable, such as guards on union that cause one -alternative to take precedence over another. These may be implemented when it -is clear they constitute a frequently used operation. In the next section we -discuss the explicit specification of state machines using state charts. - -==== Entry-Guarded Concatenation - --------------------- -expr :> expr --------------------- - -This operator concatenates two machines, but first assigns a low -priority to all transitions -of the first machine and a high priority to the starting transitions of the -second machine. This operator is useful if from the final states of the first -machine it is possible to accept the characters in the entering transitions of -the second machine. This operator effectively terminates the first machine -immediately upon starting the second machine, where otherwise they would be -pursued concurrently. In the following example, entry-guarded concatenation is -used to move out of a machine that matches everything at the first sign of an -end-of-input marker. - -///////////////////////////// -% GENERATE: entryguard -% OPT: -p -% %%{ -% machine entryguard; -.code -///////////////////////////// --------------------- -# Leave the catch-all machine on the first character of FIN. -main := any* :> 'FIN'; --------------------- -///////////////////////////// -% }%% -% END GENERATE -///////////////////////////// - -image::entryguard.png[align="left"] - -Entry-guarded concatenation is equivalent to the following: - ------------------ -expr $(unique_name,0) . expr >(unique_name,1) ------------------ - -==== Finish-Guarded Concatenation - -------------------- -expr :>> expr -------------------- - -This operator is -like the previous operator, except the higher priority is placed on the final -transitions of the second machine. This is useful if one wishes to entertain -the possibility of continuing to match the first machine right up until the -second machine enters a final state. In other words, it terminates the first -machine only when the second accepts. In the following example, finish-guarded -concatenation causes the move out of the machine that matches everything to be -delayed until the full end-of-input marker has been matched. - -//////////////////////// -% GENERATE: finguard -% OPT: -p -% %%{ -% machine finguard; -------------------------- -# Leave the catch-all machine on the last character of FIN. -main := any* :>> 'FIN'; -------------------------- -% }%% -% END GENERATE -//////////////////////// - -image::finguard.png[align="left"] - -Finish-guarded concatenation is equivalent to the following, with one -exception. If the right machine's start state is final, the higher priority is -also embedded into it as a leaving priority. This prevents the left machine -from persisting via the zero-length string. - -------------------- -expr $(unique_name,0) . expr @(unique_name,1) -------------------- - -==== Left-Guarded Concatenation - -------------------- -expr <: expr -------------------- - -This operator places a higher priority on the left expression. It is useful if -you want to prefix a sequence with another sequence composed of some of the -same characters. For example, one can consume leading whitespace before -tokenizing a sequence of whitespace-separated words as in: - -//////////////////////////// -% GENERATE: leftguard -% OPT: -p -% %%{ -% machine leftguard; -% action alpha {} -% action ws {} -% action start {} -% action fin {} -//////////////////////////// --------------------------- -main := ( ' '* >start %fin ) <: ( ' ' $ws | [a-z] $alpha )*; --------------------------- -//////////////////////////// -% }%% -% END GENERATE -//////////////////////////// - -image::leftguard.png[align="left"] - -Left-guarded concatenation is equivalent to the following: - ----------------- -expr $(unique_name,1) . expr >(unique_name,0) ----------------- - -[[longest_match_kleene_star]] -==== Longest-Match Kleene Star - --------- -expr** --------- - -This version of kleene star puts a higher priority on staying in the -machine versus wrapping around and starting over. The LM kleene star is useful -when writing simple tokenizers. These machines are built by applying the -longest-match kleene star to an alternation of token patterns, as in the -following. - -////////////////////// -% GENERATE: lmkleene -% OPT: -p -% %%{ -% machine exfinpri; -% action A {} -% action B {} -////////////////////// ----------------------- -# Repeat tokens, but make sure to get the longest match. -main := ( - lower ( lower | digit )* %A | - digit+ %B | - ' ' -)**; ----------------------- -////////////////////// -% }%% -% END GENERATE -////////////////////// - -image::lmkleene.png[align="left"] - -If a regular kleene star were used the machine above would not be able to -distinguish between extending a word and beginning a new one. This operator is -equivalent to: - ------------- -( expr $(unique_name,1) %(unique_name,0) )* ------------- - -When the kleene star is applied, transitions that go out of the machine and -back into it are made. These are assigned a priority of zero by the leaving -transition mechanism. This is less than the priority of one assigned to the -transitions leaving the final states but not leaving the machine. When -these transitions clash on the same character, the -transition that stays in the machine takes precedence. The transition -that wraps around is dropped. - -Note that this operator does not build a scanner in the traditional sense -because there is never any backtracking. To build a scanner with backtracking -use the Longest-Match machine construction described in -<<generating_scanners, Generating Scanners>>. - -Interface to Host Program -------------------------- - -The Ragel code generator is very flexible. The generated code has no -dependencies and can be inserted in any function, perhaps inside a loop if -desired. The user is responsible for declaring and initializing a number of -required variables, including the current state and the pointer to the input -stream. These can live in any scope. Control of the input processing loop is -also possible: the user may break out of the processing loop and return to it -at any time. - -In the case of the C, D, Go and OCaml host languages, Ragel is able to generate very -fast-running code that implements state machines as directly executable code. -Since very large files strain the host language compiler, table-based code -generation is also supported. In the future, we hope to provide a partitioned, -directly executable format that is able to reduce the burden on the host -compiler by splitting large machines across multiple functions. - -In the case of Java and Ruby, table-based code generation is the only code -style supported. In the future, this may be expanded to include other code -styles. - -Ragel can be used to parse input in one block, or it can be used to parse input -in a sequence of blocks as it arrives from a file or socket. Parsing the input -in a sequence of blocks brings with it a few responsibilities. If the parser -utilizes a scanner, care must be taken to not break the input stream anywhere -but token boundaries. If pointers to the input stream are taken during -parsing, care must be taken to not use a pointer that has been invalidated by -movement to a subsequent block. If the current input data pointer is moved -backwards it must not be moved past the beginning of the current block. - -The following example shows a simple Ragel program that does not have any -actions. The example tests the first argument of the program against a number -pattern and then prints the machine's acceptance status. - -.A basic Ragel example without any actions. ----------------------- -#include <stdio.h> -#include <string.h> -%%{ - machine foo; - write data; -}%% -int main( int argc, char **argv ) -{ - int cs; - if ( argc > 1 ) { - char *p = argv[1]; - char *pe = p + strlen( p ); - %%{ - main := [0-9]+ ( '.' [0-9]+ )?; - - write init; - write exec; - }%% - } - printf("result = %i\n", cs >= foo_first_final ); - return 0; -} ----------------------- - -[[variables_used_by_ragel]] -=== Variables Used by Ragel - -There are a number of variables that Ragel expects the user to declare. At a -very minimum the `cs`, `p` and `pe` variables must be declared. In Go, Java, -Ruby and OCaml code the `data` variable must also be declared. If EOF -actions are used then the `eof` variable is required. If stack-based state -machine control flow statements are used then the `stack` and `top` variables -are required. If a scanner is declared then the `act`, `ts` and `te` variables -must be declared. - -* `cs` - Current state. This must be an integer and it should persist -across invocations of the machine when the data is broken into blocks that are -processed independently. This variable may be modified from outside the -execution loop, but not from within. - -* `p` - Data pointer. In C/C++/D code this variable is expected to be a -pointer to the character data to process. It should be initialized to the -beginning of the data block on every run of the machine. In C++ it is possible -to use an object for the data pointers. The object should support comparison, -dereferencing, and pre/post increment/decrement operations. In Go, Java, Ruby -and OCaml it is used as an offset to `data` and must be an integer. In this -case it should be initialized to zero on every run of the machine. - -* `pe` - Data end pointer. This should be initialized to `p` plus -the data length on every run of the machine. In C++ this can be defined as one -increment operation past the last valid value. Or in the case of a zero-length -input buffer the initial value of `p`. A In Go, Java, Ruby and OCaml code this -should be initialized to the data length. - -* `eof` - End of file pointer. This should be set to `pe` when -the buffer block being processed is the last one, otherwise it should be set to -null. In Go, Java, Ruby and OCaml code `-1` must be used instead of null. If the EOF -event can be known only after the final buffer block has been processed, then -it is possible to set `p = pe = eof` and run the execute block. - -* `data` - This variable is only required in Go, Java, Ruby and OCaml code. It -must be an array containing the data to process. - -* `stack` - This must be an array of integers. It is used to store -integer values representing states. If the stack must resize dynamically the -<<prepush, Pre-push>> and <<postpop, Post-Pop>> statements can be used to do -this. - -* `top` - This must be an integer value and will be used as an offset -to `stack`, giving the next available spot on the top of the stack. - -* `act` - This must be an integer value. It is a variable sometimes -used by scanner code to keep track of the most recent successful pattern match. - -* `ts` - This must be a pointer to character data. In Go, Java, Ruby and -OCaml code this must be an integer. See <<generating_scanners, Generating -Scanners>> for more information. - -* `te` - Also a pointer to character data. - -* `nfa_bp` - NFA backtrack points. Only necessary if NFA features are used. -This var must be an array of records containing at least a state and alphtype -pointer. -+ ---------- -struct nfa_bp_rec -{ - long state; - char *p; -}; - -struct nfa_bp_rec nfa_bp[1024]; ---------- -+ -This array can be guarded against overflow or dynamically resized using -`nfaprepush` and `nfapostpop` code blocks. If the `:nfa()` construct is being -used, the record also needs to contain an `long pop;` field, and `long q_N` -fields for each instance of the `:nfa()` construct, where N corresponds to the -id specified in the `:nfa()` construct. - -* `nfa_len` - Number of active nfa records. Must be initialized to zero. - -* `nfa_count` - Number of NFA pops that have occurred. This is only for -tracking purposes. - -=== Alphtype Statement - ------------------- -alphtype unsigned int; ------------------- - -The alphtype statement specifies the alphabet data type that the machine -operates on. During the compilation of the machine, integer literals are -expected to be in the range of possible values of the alphtype. The default is -`char` for all languages except Go where the default is `byte` and OCaml where -the default is `int`. - -C/C++/Objective-C: ----------------------- - char unsigned char - short unsigned short - int unsigned int - long unsigned long ----------------------- - -Go: ----------------------- - byte - int8 uint8 - int16 uint16 - int32 uint32 - int ----------------------- - -Ruby: ----------------------- - char - int ----------------------- - - -Java: ----------------------- - char - byte - short - int ----------------------- - -D: ----------------------- - char - byte ubyte - short ushort - wchar - int uint - dchar ----------------------- - -OCaml: ----------------------- - int ----------------------- - -=== Getkey Statement - ------------------- -getkey fpc->id; ------------------- - -This statement specifies to Ragel how to retrieve the current character from -from the pointer to the current element (`p`). Any expression that returns -a value of the alphabet type -may be used. The getkey statement may be used for looking into element -structures or for translating the character to process. The getkey expression -defaults to `(*p)`. In goto-driven machines the getkey expression may be -evaluated more than once per element processed, therefore it should not incur a -large cost nor preclude optimization. - -=== Access Statement - ----------------- -access fsm->; ----------------- - -The access statement specifies how the generated code should access the machine -data that is persistent across processing buffer blocks. This applies to all -variables except `p`, `pe` and `eof`. This includes `cs`, `top`, `stack`, `ts`, -`te` and `act`. The access statement is useful if a machine is to be -encapsulated inside a structure in C code. It can be used to give the name of a -pointer to the structure. - -=== Variable Statement - ------------------- -variable p fsm->p; ------------------- - -The variable statement specifies how to access a specific variable. All of the -variables that are declared by the user and used by Ragel can be changed. This -includes `p`, `pe`, `eof`, `cs`, `top`, `stack`, `ts`, `te` and `act`. In Go, -Ruby, Java and OCaml code generation the `data` variable can also be changed. - -[[prepush]] -=== Pre-Push Statement - ------------------- -prepush { - /* stack growing code */ -} ------------------- - -The prepush statement allows the user to supply stack management code that is -written out during the generation of fcall, immediately before the current -state is pushed to the stack. This statement can be used to test the number of -available spaces and dynamically grow the stack if necessary. - -[[postpop]] -=== Post-Pop Statement - ------------------- -postpop { - /* stack shrinking code */ -} ------------------- - -The postpop statement allows the user to supply stack management code that is -written out during the generation of fret, immediately after the next state is -popped from the stack. This statement can be used to dynamically shrink the -stack. - -[[write_statement]] -=== Write Statement - ------------------- -write <component> [options]; ------------------- - -The write statement is used to generate parts of the machine. -There are seven -components that can be generated by a write statement. These components make up the -state machine's data, initialization code, execution code, and export definitions. -A write statement may appear before a machine is fully defined. -This allows one to write out the data first then later define the machine where -it is used. See the <<fbreak_example, fbreak Example>>. - -==== Write Data - ------------------- -write data [options]; ------------------- - -The write data statement causes Ragel to emit the constant static data needed -by the machine. In table-driven output styles (see -<<genout,Generated Output Style>>) this is a collection of arrays that -represent the states and transitions of the machine. In goto-driven machines -much less data is emitted. At the very minimum a start state `name_start` -is generated. All variables written out in machine data have both the -`static` and `const` properties and are prefixed with the name of the -machine and an underscore. The data can be placed inside a class, inside a -function, or it can be defined as global data. - -Two variables are written that may be used to test the state of the machine -after a buffer block has been processed. The `name_error` variable gives -the id of the state that the machine moves into when it cannot find a valid -transition to take. The machine immediately breaks out of the processing loop when -it finds itself in the error state. The error variable can be compared to the -current state to determine if the machine has failed to parse the input. If the -machine is complete, that is from every state there is a transition to a proper -state on every possible character of the alphabet, then no error state is required -and this variable will be set to -1. - -The `name_first_final` variable stores the id of the first final state. -All of the machine's states are sorted by their final state status before -having their ids assigned. Checking if the machine has accepted its input can -then be done by checking if the current state is greater-than or equal to the -first final state. - -Data generation has several options: - -* `noerror` - Do not generate the integer -variable that gives the id of the error state. - -* `nofinal` - Do not generate the integer variable -that gives the id of the first final state. - -* `noprefix` - Do not prefix the variable names with the name of the machine. - -[[fbreak_example]] -.Use of `noend` write option and the `fbreak` statement for processing a string. ------------------------- -#include <stdio.h> -%% machine foo; -%% write data; -int main( int argc, char **argv ) -{ - int cs, res = 0; - if ( argc > 1 ) { - char *p = argv[1]; - %%{ - main := - [a-z]+ - 0 @{ res = 1; fbreak; }; - write init; - write exec noend; - }%% - } - printf("execute = %i\n", res ); - return 0; -} ------------------------- - -==== Write Start, First Final and Error - ------------------- -write start; -write first_final; -write error; ------------------- - -These three write statements provide an alternative means of accessing the -`start`, `first_final` and `error` states. If there are many different machine -specifications in one file it is easy to get the prefix for these wrong. This -is especially true if the state machine boilerplate is frequently made by a -copy-paste-edit process. These write statements allow the problem to be -avoided. They can be used as follows: - -------------------- -/* Did parsing succeed? */ -if ( cs < %%{ write first_final; }%% ) { - result = ERR_PARSE_ERROR; - goto fail; -} -------------------- - -==== Write Init - -------------------- -write init [options]; -------------------- - -The write init statement causes Ragel to emit initialization code. This should -be executed once before the machine is started. At a very minimum this sets the -current state to the start state. If other variables are needed by the -generated code, such as call stack variables or scanner management -variables, they are also initialized here. - -The `nocs` option to the write init statement will cause ragel to skip -intialization of the cs variable. This is useful if the user wishes to use -custom logic to decide which state the specification should start in. - -==== Write Exec - ---------------------------- -write exec [options]; ---------------------------- - -The write exec statement causes Ragel to emit the state machine's execution -code. Ragel expects several variables to be available to this code. At a very -minimum, the generated code needs access to the current character position `p`, -the ending position `pe` and the current state `cs` (though `pe` can be omitted -using the `noend` write option). The `p` variable is the cursor that the -execute code will used to traverse the input. The `pe` variable should be set -up to point to one position past the last valid character in the buffer. - -Other variables are needed when certain features are used. For example using -the `fcall` or `fret` statements requires `stack` and `top` variables to be -defined. If a longest-match construction is used, variables for managing -backtracking are required. - -The write exec statement has one option. The `noend` option tells Ragel to -generate code that ignores the end position `pe`. In this case the user must -explicitly break out of the processing loop using `fbreak`, otherwise the -machine will continue to process characters until it moves into the error -state. This option is useful if one wishes to process a null terminated string. -Rather than traverse the string to discover then length before processing the -input, the user can break out when the null character is seen. The -<<fbreak_example, fbreak Example>> shows the use of the `noend` write option and the -`fbreak` statement for processing a string. - -[[export,Write Exports]] -==== Write Exports - -------------------- -write exports; -------------------- - -The export feature can be used to export simple machine definitions. Machine definitions -are marked for export using the `export` keyword. - -------------------- -export machine_to_export = 0x44; -------------------- - -When the write exports statement is used these machines are written out in the -generated code. Defines are used for C and constant integers are used for D, -Java, Ruby and OCaml. See <<import, Importing Definitions>> for a description -of the import statement. - -=== Maintaining Pointers to Input Data - -In the creation of any parser it is not uncommon to require the collection of -the data being parsed. It is always possible to collect data into a growable -buffer as the machine moves over it, however the copying of data is a somewhat -wasteful use of processor cycles. The most efficient way to collect data from -the parser is to set pointers into the input then later reference them. This -poses a problem for uses of Ragel where the input data arrives in blocks, such -as over a socket or from a file. If a pointer is set in one buffer block but -must be used while parsing a following buffer block, some extra consideration -to correctness must be made. - -The scanner constructions exhibit this problem, requiring the maintenance code -described in <<generating_scanners, Generating Scanners>>. If a longest-match -construction has been used somewhere in the machine then it is possible to take -advantage of the required prefix maintenance code in the driver program to -ensure pointers to the input are always valid. If laying down a pointer one can -set `ts` at the same spot or ahead of it. When data is shifted in between loops -the user must also shift the pointer. In this way it is possible to maintain -pointers to the input that will always be consistent. - -In general, there are two approaches for guaranteeing the consistency of -pointers to input data. The first approach is the one just described; lay down -a marker from an action, then later ensure that the data the marker points to -is preserved ahead of the buffer on the next execute invocation. This approach -is good because it allows the parser to decide on the pointer-use boundaries, -which can be arbitrarily complex parsing conditions. A downside is that it -requires any pointers that are set to be corrected in between execute -invocations. - -The alternative is to find the pointer-use boundaries before invoking the execute -routine, then pass in the data using these boundaries. For example, if the -program must perform line-oriented processing, the user can scan backwards from -the end of an input block that has just been read in and process only up to the -first found newline. On the next input read, the new data is placed after the -partially read line and processing continues from the beginning of the line. -An example of line-oriented processing is given below. - -[[line_oriented]] -.An example of line-oriented processing. ------------------- - int have = 0; - while ( 1 ) { - char *p, *pe, *data = buf + have; - int len, space = BUFSIZE - have; - - if ( space == 0 ) { - fprintf(stderr, "BUFFER OUT OF SPACE\n"); - exit(1); - } - - len = fread( data, 1, space, stdin ); - if ( len == 0 ) - break; - - /* Find the last newline by searching backwards. */ - p = buf; - pe = data + len - 1; - while ( *pe != '\n' && pe >= buf ) - pe--; - pe += 1; - - %% write exec; - - /* How much is still in the buffer? */ - have = data + len - pe; - if ( have > 0 ) - memmove( buf, pe, have ); - - if ( len < space ) - break; - } ---------------- - -=== Specifying the Host Language - -The `ragel` program has a number of options for specifying the host -language. The host-language options are: - -* `-C` for C/C++/Objective-C code (default) -* `--asm` or `--gas-x86-64-sys-v` for GNU AS, x86_64, System V ABI. -* `-D` for D code. -* `-Z` for Go code. -* `-J` for Java code. -* `-R` for Ruby code. -* `-A` for C# code. -* `-O` for OCaml code. -* `-U` for Rust -* `-Y` for Julia -* `-K` for Crack -* `-P` for JavaScript - -[[genout]] -=== Choosing a Generated Code Style - -There are three styles of code output to choose from. Code style affects the -size and speed of the compiled binary. Changing code style does not require any -change to the Ragel program. There are two table-driven formats and a goto -driven format. - -In addition to choosing a style to emit, there are various levels of action -code reuse to choose from. The maximum reuse levels (`-T0`, `-F0` -and `-G0`) ensure that no FSM action code is ever duplicated by encoding -each transition's action list as static data and iterating -through the lists on every transition. This will normally result in a smaller -binary. The less action reuse options (`-T1`, `-F1` and `-G1`) -will usually produce faster running code by expanding each transition's action -list into a single block of code, eliminating the need to iterate through the -lists. This duplicates action code instead of generating the logic necessary -for reuse. Consequently the binary will be larger. However, this tradeoff applies to -machines with moderate to dense action lists only. If a machine's transitions -frequently have less than two actions then the less reuse options will actually -produce both a smaller and a faster running binary due to less action sharing -overhead. The best way to choose the appropriate code style for your -application is to perform your own tests. - -The table-driven FSM represents the state machine as constant static data. There are -tables of states, transitions, indices and actions. The current state is -stored in a variable. The execution is simply a loop that looks up the current -state, looks up the transition to take, executes any actions and moves to the -target state. In general, the table-driven FSM can handle any machine, produces -a smaller binary and requires a less expensive host language compile, but -results in slower running code. Since the table-driven format is the most -flexible it is the default code style. - -The flat table-driven machine is a table-based machine that is optimized for -small alphabets. Where the regular table machine uses the current character as -the key in a binary search for the transition to take, the flat table machine -uses the current character as an index into an array of transitions. This is -faster in general, however is only suitable if the span of possible characters -is small. - -The goto-driven FSM represents the state machine using goto and switch -statements. The execution is a flat code block where the transition to take is -computed using switch statements and directly executable binary searches. In -general, the goto FSM produces faster code but results in a larger binary and a -more expensive host language compile. - -The goto-driven format has an additional action reuse level (`-G2`) that writes -actions directly into the state transitioning logic rather than putting all the -actions together into a single switch. Generally this produces faster running -code because it allows the machine to encode the current state using the -processor's instruction pointer. Again, sparse machines may actually compile to -smaller binaries when `-G2` is used due to less state and action management -overhead. For many parsing applications `-G2` is the preferred output format. - -Code Output Style Options - -* `-T0` - binary search table-driven -* `-T1` - binary search, expanded actions -* `-F0` - flat table-driven -* `-F1` - flat table, expanded actions -* `-G0` - goto-driven -* `-G1` - goto, expanded actions -* `-G2` - goto, in-place actions - -Due to limitations of the host languages, not all styles are supported for all -host languages. The following table shows what is supported. - -[width="50%"] -|=========================================== -| C | `-T0 -T1 -F0 -F1 -G0 -G1 -G2` -| ASM | `-G2` -| D | `-T0 -T1 -F0 -F1 -G0 -G1 -G2` -| Go | `-T0 -T1 -F0 -F1 -G0 -G1 -G2` -| C# | `-T0 -T1 -F0 -F1 -G0 -G1` -| Java | `-T0 -T1 -F0 -F1` -| Ruby | `-T0 -T1 -F0 -F1` -| OCaml | `-T0 -T1 -F0 -F1` -| Rust | `-T0 -T1 -F0 -F1` -| Julia | `-T0 -T1 -F0 -F1` -| Crack | `-T0 -T1 -F0 -F1` -| JavaScript | `-T0 -T1 -F0 -F1` -|=========================================== - -Beyond the Basic Model ----------------------- - -[[modularization]] -=== Parser Modularization - -It is possible to use Ragel's machine construction and action embedding -operators to specify an entire parser using a single regular expression. In -many cases this is the desired way to specify a parser in Ragel. However, in -some scenarios the language to parse may be so large that it is difficult to -think about it as a single regular expression. It may also shift between distinct -parsing strategies, in which case modularization into several coherent blocks -of the language may be appropriate. - -It may also be the case that patterns that compile to a large number of states -must be used in a number of different contexts and referencing them in each -context results in a very large state machine. In this case, an ability to reuse -parsers would reduce code size. - -To address this, distinct regular expressions may be instantiated and linked -together by means of a jumping and calling mechanism. This mechanism is -analogous to the jumping to and calling of processor instructions. A jump -command, given in action code, causes control to be immediately passed to -another portion of the machine by way of setting the current state variable. A -call command causes the target state of the current transition to be pushed to -a state stack before control is transferred. Later on, the original location -may be returned to with a return statement. In the following example, distinct -state machines are used to handle the parsing of two types of headers. - -/////////////////////// -% GENERATE: call -% %%{ -% machine call; -/////////////////////// ----------------------- -action return { fret; } -action call_date { fcall date; } -action call_name { fcall name; } - -# A parser for date strings. -date := [0-9][0-9] '/' - [0-9][0-9] '/' - [0-9][0-9][0-9][0-9] '\n' @return; - -# A parser for name strings. -name := ( [a-zA-Z]+ | ' ' )** '\n' @return; - -# The main parser. -headers = - ( 'from' | 'to' ) ':' @call_name | - ( 'departed' | 'arrived' ) ':' @call_date; - -main := headers*; ----------------------- -////////////////////// -% }%% -% %% write data; -% void f() -% { -% %% write init; -% %% write exec; -% } -% END GENERATE -////////////////////// - -Calling and jumping should be used carefully as they are operations that take -one out of the domain of regular languages. A machine that contains a call or -jump statement in one of its actions should be used as an argument to a machine -construction operator only with considerable care. Since DFA transitions may -actually represent several NFA transitions, a call or jump embedded in one -machine can inadvertently terminate another machine that it shares prefixes -with. Despite this danger, theses statements have proven useful for tying -together sub-parsers of a language into a parser for the full language, -especially for the purpose of modularizing code and reducing the number of -states when the machine contains frequently recurring patterns. - -The section on <<vals, Embedded Values and Statements>> describes the jump and -call statements that are used to transfer control. These statements make use of -two variables that must be declared by the user, `stack` and `top`. The `stack` -variable must be an array of integers and `top` must be a single integer, which -will point to the next available space in `stack`. The <<prepush, Pre-Push>> -and <<postpop, Post-Pop>> statements which can be used to implement a -dynamically resizable array. - -[[labels]] -=== Referencing Names - -This section describes how to reference names in epsilon transitions -(<<state_charts, State Charts>>) and action-based control-flow statements such -as `fgoto`. There is a hierarchy of names implied in a Ragel specification. At -the top level are the machine instantiations. Beneath the instantiations are -labels and references to machine definitions. Beneath those are more labels and -references to definitions, and so on. - -Any name reference may contain multiple components separated with the `::` -compound symbol. The search for the first component of a name reference is -rooted at the join expression that the epsilon transition or action embedding -is contained in. If the name reference is not contained in a join, -the search is rooted at the machine definition that the epsilon transition or -action embedding is contained in. Each component after the first is searched -for beginning at the location in the name tree that the previous reference -component refers to. - -In the case of action-based references, if the action is embedded more than -once, the local search is performed for each embedding and the result is the -union of all the searches. If no result is found for action-based references then -the search is repeated at the root of the name tree. Any action-based name -search may be forced into a strictly global search by prefixing the name -reference with `::`. - -The final component of the name reference must resolve to a unique entry point. -If a name is unique in the entire name tree it can be referenced as is. If it -is not unique it can be specified by qualifying it with names above it in the -name tree. However, it can always be renamed. - -/////////////// -% FIXME: Should fit this in somewhere. -% Some kinds of name references are illegal. Cannot call into longest-match -% machine, can only call its start state. Cannot make a call to anywhere from -% any part of a longest-match machine except a rule's action. This would result -% in an eventual return to some point inside a longest-match other than the -% start state. This is banned for the same reason a call into the LM machine is -% banned. -/////////////// - -[[generating_scanners]] -=== Scanners - -Scanners are very much intertwined with regular-languages and their -corresponding processors. For this reason Ragel supports the definition of -scanners. The generated code will repeatedly attempt to match patterns from a -list, favouring longer patterns over shorter patterns. In the case of -equal-length matches, the generated code will favour patterns that appear ahead -of others. When a scanner makes a match it executes the user code associated -with the match, consumes the input then resumes scanning. - ------------------- -<machine_name> := |* - pattern1 => action1; - pattern2 => action2; - ... - *|; ------------------- - -On the surface, Ragel scanners are similar to those defined by Lex. Though -there is a key distinguishing feature: patterns may be arbitrary Ragel -expressions and can therefore contain embedded code. With a Ragel-based scanner -the user need not wait until the end of a pattern before user code can be -executed. - -Scanners can be used to process sub-languages, as well as for tokenizing -programming languages. In the following example a scanner is used to tokenize -the contents of a header field. - ------------------------- -word = [a-z]+; -head_name = 'Header'; - -header := |* - word; - ' '; - '\n' => { fret; }; -*|; - -main := ( head_name ':' @{ fcall header; } )*; ------------------------- - -The scanner construction has a purpose similar to the longest-match kleene star -operator `**`. The key -difference is that a scanner is able to backtrack to match a previously matched -shorter string when the pursuit of a longer string fails. For this reason the -scanner construction operator is not a pure state machine construction -operator. It relies on several variables that enable it to backtrack and make -pointers to the matched input text available to the user. For this reason -scanners must be immediately instantiated. They cannot be defined inline or -referenced by another expression. Scanners must be jumped to or called. - -Scanners rely on the `ts`, `te` and `act` variables to be present so that they -can backtrack and make pointers to the matched text available to the user. If -input is processed using multiple calls to the execute code then the user must -ensure that when a token is only partially matched that the prefix is preserved -on the subsequent invocation of the execute code. - -The `ts` variable must be defined as a pointer to the input data. -It is used for recording where the current token match begins. This variable -may be used in action code for retrieving the text of the current match. Ragel -ensures that in between tokens and outside of the longest-match machines that -this pointer is set to null. In between calls to the execute code the user must -check if `ts` is set and if so, ensure that the data it points to is -preserved ahead of the next buffer block. This is described in more detail -below. - -The `te` variable must also be defined as a pointer to the input data. -It is used for recording where a match ends and where scanning of the next -token should begin. This can also be used in action code for retrieving the -text of the current match. - -The `act` variable must be defined as an integer type. It is used for recording -the identity of the last pattern matched when the scanner must go past a -matched pattern in an attempt to make a longer match. If the longer match fails -it may need to consult the `act` variable. In some cases, use of the `act` -variable can be avoided because the value of the current state is enough -information to determine which token to accept, however in other cases this is -not enough and so the `act` variable is used. - -When the longest-match operator is in use, the user's driver code must take on -some buffer management functions. The following algorithm gives an overview of -the steps that should be taken to properly use the longest-match operator. - -* Read a block of input data. -* Run the execute code. - -* If `ts` is set, the execute code will expect the incomplete -token to be preserved ahead of the buffer on the next invocation of the execute -code. - -** Shift the data beginning at `ts` and ending at `pe` to the -beginning of the input buffer. - -** Reset `ts` to the beginning of the buffer. - -** Shift `te` by the distance from the old value of `ts` -to the new value. The `te` variable may or may not be valid. There is -no way to know if it holds a meaningful value because it is not kept at null -when it is not in use. It can be shifted regardless. - -* Read another block of data into the buffer, immediately following any -preserved data. - -* Run the scanner on the new data. - -The following listing shows the required handling of an input stream in which a -token is broken by the input block boundaries. After processing up to and -including the ``t'' of ``characters'', the prefix of the string token must be -retained and processing should resume at the ``e'' on the next iteration of the -execute code. - ----------------- - a) A stream "of characters" to be scanned. - | | | - p ts pe - - b) "of characters" to be scanned. - | | | - ts p pe ----------------- - -If one uses a large input buffer for collecting input then the number of times -the shifting must be done will be small. Furthermore, if one takes care not to -define tokens that are allowed to be very long and instead processes these -items using pure state machines or sub-scanners, then only a small amount of -data will ever need to be shifted. - -Following an invocation of the execute code there may be a partially matched -token (a). The data of the partially matched token must be preserved ahead of -the new data on the next invocation (b). - -Since scanners attempt to make the longest possible match of input, patterns -such as identifiers require one character of lookahead in order to trigger a -match. In the case of the last token in the input stream the user must ensure -that the `eof` variable is set so that the final token is flushed out. - -The following is an an example scanner processing loop. - -.A processing loop for a scanner. ------------------ - int have = 0; - bool done = false; - while ( !done ) { - /* How much space is in the buffer? */ - int space = BUFSIZE - have; - if ( space == 0 ) { - /* Buffer is full. */ - cerr << "TOKEN TOO BIG" << endl; - exit(1); - } - - /* Read in a block after any data we already have. */ - char *p = inbuf + have; - cin.read( p, space ); - int len = cin.gcount(); - - char *pe = p + len; - char *eof = 0; - - /* If no data was read indicate EOF. */ - if ( len == 0 ) { - eof = pe; - done = true; - } - - %% write exec; - - if ( cs == Scanner_error ) { - /* Machine failed before finding a token. */ - cerr << "PARSE ERROR" << endl; - exit(1); - } - - if ( ts == 0 ) - have = 0; - else { - /* There is a prefix to preserve, shift it over. */ - have = pe - ts; - memmove( inbuf, ts, have ); - te = inbuf + (te-ts); - ts = inbuf; - } - } ------------------ - -[[state_charts]] -=== State Charts - -In addition to supporting the construction of state machines using regular -languages, Ragel provides a way to manually specify state machines using -state charts. The comma operator combines machines together without any -implied transitions. The user can then manually link machines by specifying -epsilon transitions with the `->` operator. Epsilon transitions are drawn -between the final states of a machine and entry points defined by labels. This -makes it possible to build machines using the explicit state-chart method while -making minimal changes to the Ragel language. - -An interesting feature of Ragel's state chart construction method is that it -can be mixed freely with regular expression constructions. A state chart may be -referenced from within a regular expression, or a regular expression may be -used in the definition of a state chart transition. - -==== Join - ------------------ -expr , expr , ... ------------------ - -Join a list of machines together without -drawing any transitions, without setting up a start state, and without -designating any final states. Transitions between the machines may be specified -using labels and epsilon transitions. The start state must be explicity -specified with the ``start'' label. Final states may be specified with an -epsilon transition to the implicitly created ``final'' state. The join -operation allows one to build machines using a state chart model. - -==== Label - ------------------- -label: expr ------------------- - -Attaches a label to an expression. Labels can be -used as the target of epsilon transitions and explicit control transfer -statements such as `fgoto` and `fnext` in action -code. - -==== Epsilon - ------------------ -expr -> label ------------------ - -Draws an epsilon transition to the state defined by `label`. Epsilon -transitions are made deterministic when join operators are evaluated. Epsilon -transitions that are not in a join operation are made deterministic when the -machine definition that contains the epsilon is complete. See <<labels, -Referencing Names>> for information on referencing labels. - -==== Simplifying State Charts - -There are two benefits to providing state charts in Ragel. The first is that it -allows us to take a state chart with a full listing of states and transitions -and simplify it in selective places using regular expressions. - -The state chart method of specifying parsers is very common. It is an -effective programming technique for producing robust code. The key disadvantage -becomes clear when one attempts to comprehend a large parser specified in this -way. These programs usually require many lines, causing logic to be spread out -over large distances in the source file. Remembering the function of a large -number of states can be difficult and organizing the parser in a sensible way -requires discipline because branches and repetition present many file layout -options. This kind of programming takes a specification with inherent -structure such as looping, alternation and concatenation and expresses it in a -flat form. - -If we could take an isolated component of a manually programmed state chart, -that is, a subset of states that has only one entry point, and implement it -using regular language operators then we could eliminate all the explicit -naming of the states contained in it. By eliminating explicitly named states -and replacing them with higher-level specifications we simplify a state machine -specification. - -For example, sometimes chains of states are needed, with only a small number of -possible characters appearing along the chain. These can easily be replaced -with a concatenation of characters. Sometimes a group of common states -implement a loop back to another single portion of the machine. Rather than -manually duplicate all the transitions that loop back, we may be able to -express the loop using a kleene star operator. - -Ragel allows one to take this state map simplification approach. We can build -state machines using a state map model and implement portions of the state map -using regular languages. In place of any transition in the state machine, -entire sub-machines can be given. These can encapsulate functionality -defined elsewhere. An important aspect of the Ragel approach is that when we -wrap up a collection of states using a regular expression we do not lose -access to the states and transitions. We can still execute code on the -transitions that we have encapsulated. - -[[down]] -==== Dropping Down One Level of Abstraction - -The second benefit of incorporating state charts into Ragel is that it permits -us to bypass the regular language abstraction if we need to. Ragel's action -embedding operators are sometimes insufficient for expressing certain parsing -tasks. In the same way that is useful for C language programmers to drop down -to assembly language programming using embedded assembler, it is sometimes -useful for the Ragel programmer to drop down to programming with state charts. - -In the following example, we wish to buffer the characters of an XML CDATA -sequence. The sequence is terminated by the string `]]>`. The challenge -in our application is that we do not wish the terminating characters to be -buffered. An expression of the form `any* @buffer :>> ']]>'` will not work -because the buffer will always contain the characters `]]` on the end. -Instead, what we need is to delay the buffering of `]` -characters until a time when we -abandon the terminating sequence and go back into the main loop. There is no -easy way to express this using Ragel's regular expression and action embedding -operators, and so an ability to drop down to the state chart method is useful. - -/////////////////////// -% GENERATE: dropdown -% OPT: -p -% %%{ -% machine dropdown; -/////////////////////// ------------------------ -action bchar { buff( fpc ); } # Buffer the current character. -action bbrack1 { buff( "]" ); } -action bbrack2 { buff( "]]" ); } - -CDATA_body = -start: ( - ']' -> one | - (any-']') @bchar ->start -), -one: ( - ']' -> two | - [^\]] @bbrack1 @bchar ->start -), -two: ( - '>' -> final | - ']' @bbrack1 -> two | - [^>\]] @bbrack2 @bchar ->start -); ------------------------ -////////////////// -% main := CDATA_body; -% }%% -% END GENERATE -////////////////// - -image::dropdown.png[align="left"] - -[[semantic]] -=== Semantic Conditions - -==== Semantic Conditions - -Many communication protocols contain variable-length fields, where the length -of the field is given ahead of the field as a value. This -problem cannot be expressed using regular languages because of its -context-dependent nature. The prevalence of variable-length fields in -communication protocols motivated us to introduce semantic conditions into -the Ragel language. - -A semantic condition is a block of user code that is interpreted as an -expression and evaluated immediately -before a transition is taken. If the code returns a value of true, the -transition may be taken. We can now embed code that extracts the length of a -field, then proceed to match $n$ data values. - -////////////////// -% GENERATE: conds1 -% OPT: -p -% %%{ -% machine conds1; -% number = digit+; -////////////////// ----------------------- -action rec_num { i = 0; n = getnumber(); } -action test_len { i++ < n } -data_fields = ( - 'd' - [0-9]+ %rec_num - ':' - ( [a-z] when test_len )* -)**; ----------------------- -/////////////////////////// -% main := data_fields; -% }%% -% END GENERATE -/////////////////////////// - -image::conds1.png[align="left"] - -The Ragel implementation of semantic conditions does not force us to give up the -compositional property of Ragel definitions. For example, a machine that tests -the length of a field using conditions can be unioned with another machine -that accepts some of the same strings, without the two machines interfering with -one another. The user need not be concerned about whether or not the result of the -semantic condition will affect the matching of the second machine. - -To see this, first consider that when a user associates a condition with an -existing transition, the transition's label is translated from the base character -to its corresponding value in the space that represents ``condition $c$ true''. Should -the determinization process combine a state that has a conditional transition -with another state that has a transition on the same input character but -without a condition, then the condition-less transition first has its label -translated into two values, one to its corresponding value in the space that -represents ``condition $c$ true'' and another to its corresponding value in the -space that represents ``condition $c$ false''. It -is then safe to combine the two transitions. This is shown in the following -example. Two intersecting patterns are unioned, one with a condition and one -without. The condition embedded in the first pattern does not affect the second -pattern. - -///////////////////////// -% GENERATE: conds2 -% OPT: -p -% %%{ -% machine conds2; -% number = digit+; -///////////////////////// -------------------------- -action test_len { i++ < n } -action one { /* accept pattern one */ } -action two { /* accept pattern two */ } -patterns = - ( [a-z] when test_len )+ %one | - [a-z][a-z0-9]* %two; -main := patterns '\n'; -------------------------- -////////////////////////// -% }%% -% END GENERATE -////////////////////////// - -image::conds2.png[align="left"] - -There are many more potential uses for semantic conditions. The user is free to -use arbitrary code and may therefore perform actions such as looking up names -in dictionaries, validating input using external parsing mechanisms or -performing checks on the semantic structure of input seen so far. In the next -section we describe how Ragel accommodates several common parser engineering -problems. - -The semantic condition feature works only with alphabet types that are smaller -in width than the `long` type. To implement semantic conditions Ragel -needs to be able to allocate characters from the alphabet space. Ragel uses -these allocated characters to express "character C with condition P true" or "C -with P false." Since internally Ragel uses longs to store characters there is -no room left in the alphabet space unless an alphabet type smaller than long is -used. - -==== Condition Based Repetition - -New in ragel 7 is a construct designed to simplify the use of conditions to -control repetition. While possible to count properly using condition embedding -operators, there is a corner case that proves difficult. If the zero-width case -is to be accepted properly, some knowledge of what is before and after is -necessary and tests need to be embedded there. The `:cond()` operator is -designed to solve this problem, automatically embedding actions such that a -zero count is possible. - --------------- -:cond( <expression>, - <init>, <inc>, <min> [ , <max> ] ): --------------- - -* `expression` is the ragel-expression that is to be repeated. - -* `init` is an action that is used to initialize the state. - -* `inc` is an action that is used to increment the count. - -* `min` is a condition used to test if the minimal count has been achieved. - -* `max` is an optional condition used to test if the maximum count has been achieved. - -The `:cond` construct is a synonym for `:condstar`. Ragel also supports -`:condplus`, which does not allow the zero-width case. There must be at least -one item. - -=== NFA Features - -New in Ragel 7 are features for specifying non-deterministic machines. Prior to -this, ragel always produced DFAs, so these features represent a departure -from the standard runtime model. They allow us to cope with very large state -machines, without having to compromise on the language matched, or devise some -techniques outside of the ragel language. - -The NFA features require that the programmer make available `nfa_bp`, `nfa_len` -and `nfa_count` variables. See the section <<variables_used_by_ragel, Varibles -Used by Ragel>> - -Note that NFA features are non compatible with non-contiguous buffer blocks. It -requires being able to set p to some previously stashed value. If the buffer is -no longer available, ragel will attempt to backtrack into invalid data. - -==== NFA Union - -The NFA union operator allows the programmer to create a large union of -expressions without making the construction fully deterministic. Only a prefix -is made deterministic, in a breadth-first manner, and up to a specified depth. - --------------- -<name> |= ( <depth>, <group-size> ) <expression1> | <expression2> | ... ; --------------- - -The NFA union operator looks like a normal union, except some additional -controls are specified. The depth value says how deep into the machine the -NFA-to-DFA algorithm should go looking for NFA states to make deterministic. -The group-size value allows the programmer to set a limit on the number of -expressions that are packed into a single DFA prefix. If this value is zero, -there is no limit, and all expressions go into a single group. If this number -is less than the number of expressions, there will be an immediate NFA branch -for the groups, before entering into the DFA prefixes. Roughly speaking, -group-size allows you to control initial branch width. - -By making depth or groups-size smaller, you can shift cost from compile-time to -run-time to get otherwise intractable unions to build. - -==== NFA Repetition - -The NFA repetition construct `:nfa()` is designed to allow counting of objects -in an ambiguous context. While the `:cond()` construct is an efficent counting -method, it does not work properly when there are ambiguities around starting, -repeating, or exiting a repetition. Since condition tests are embedding into -transitions, they are made deterministic, therefore the repetition could be -simultaneously incrementing and exiting the repetition. In these cases the NFA -repetition is useful, because it will explore all possibilites and allow use -user to preserve and restore state. To pay for this, you must be willing to -accept backtracking, however, and also give up non-congiguous buffer blocks. - -While the NFA repetition construct is designed for counting, it is useful for -much more. It generalizes to a state capture/manipulation/test construct that -works regardless of ambiguities. For example, if there are two possible data -captures, the :nfa union operator can backtrack to try an alternate. It before -backtracking it can restore relevant state, then perform the new capture. - --------------- -:nfa( <expression>, - <push>, <pop>, - <init>, <stay>, <repeat>, <exit> ): --------------- - -* `expression` is the ragel-expression that is to be repeated. - -* `push` is an action that saves state needed for counting instances of expression. - -* `pop` is a condition action that restores state needed for counting instances -of expression. This is an expression due to a current limitation of the -implementation. In the future theis may change to a plain action. - -* `init` is an condition that is tested before entering the repeat. - -* `stay` is an condition that is tested before deciding to stay in the -expression, as opposed to wrapping around to begin a new expression, or -exiting. If true, this allows the expression to continue to match, once a final -state has been entered. - -* `repeat` is an condition that is tested before deciding to wrap around and -attempt a new instance of expression. - -* `exit` is an condition that is tested before deciding to leave the repeat - -The following actions achieve a generalized repetition that looks for 10 to 100 -repetitions of some expression. It requires that the count variable be placed -in the nfa_bp struct. Note that it is correct to reference nfa_len. It does not -need to manipulated, that is done by the generated code. - ----------------- -action push { nfa_bp[nfa_len].count = count; } -action pop { ({ count = nfa_bp[nfa_len].count; 1; }) } -action init { ({ count = 0; 1; }) } -action stay { ({ 1; }) } -action repeat { ({ ++count < 100; }) } -action exit { ({ ++count >= 10; }) } ------------------- - -The following actions, when used with expression `''`, achieve a test of a -previously stored value (eg. backref). In the exit the stashed value is checked -against the data at p. - ----------------- -action init { ({ 1; }) } -action stay { ({ 0; }) } -action repeat { ({ 0; }) } -action exit -{ ({ - int match = check_stashed( p, pe, stashed_start, stashed_end ); - if ( match ) - p += ( stashed_end - stashed_start ); - match; -}) } ------------------- - -=== Implementing Lookahead - -There are a few strategies for implementing lookahead in Ragel programs. -Leaving actions, which are described in <<out_actions, Leaving Actions>>, can be -used as a form of lookahead. Ragel also provides the `fhold` directive -which can be used in actions to prevent the machine from advancing over the -current character. It is also possible to manually adjust the current character -position by shifting it backwards using `fexec`, however when this is -done, care must be taken not to overstep the beginning of the current buffer -block. In both the use of `fhold` and `fexec` the user must be -cautious of combining the resulting machine with another in such a way that the -transition on which the current position is adjusted is not combined with a -transition from the other machine. - -=== Parsing Recursive Language Structures - -In general Ragel cannot handle recursive structures because the grammar is -interpreted as a regular language. However, depending on what needs to be -parsed it is sometimes practical to implement the recursive parts using manual -coding techniques. This often works in cases where the recursive structures are -simple and easy to recognize, such as in the balancing of parentheses. - -One approach to parsing recursive structures is to use actions that increment -and decrement counters or otherwise recognize the entry to and exit from -recursive structures and then jump to the appropriate machine defnition using -`fcall` and `fret`. Alternatively, semantic conditions can be used to -test counter variables. - -A more traditional approach is to call a separate parsing function (expressed -in the host language) when a recursive structure is entered, then later return -when the end is recognized. diff --git a/doc/ragel/ragel.1.in b/doc/ragel/ragel.1.in deleted file mode 100644 index 9c768e85..00000000 --- a/doc/ragel/ragel.1.in +++ /dev/null @@ -1,702 +0,0 @@ -.\" -.\" Copyright 2001-2007 Adrian Thurston <thurston@colm.net> -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining a copy -.\" of this software and associated documentation files (the "Software"), to -.\" deal in the Software without restriction, including without limitation the -.\" rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -.\" sell copies of the Software, and to permit persons to whom the Software is -.\" furnished to do so, subject to the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included in all -.\" copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -.\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -.\" OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -.\" SOFTWARE. -.\" - -.\" -.\" Process this file with -.\" groff -man -Tascii ragel.1 -.\" - - -.TH RAGEL 1 "@PUBDATE@" "Ragel @VERSION@" "Ragel State Machine Compiler" -.SH NAME -ragel \- compile regular languages into executable state machines -.SH SYNOPSIS -.B ragel -.RI [ options ] -.I file -.SH DESCRIPTION -Ragel compiles executable finite state machines from regular languages. -Ragel can generate C, C++, Objective-C, D, Go, or Java code. Ragel state -machines can not only recognize byte -sequences as regular expression machines do, but can also execute code at -arbitrary points in the recognition of a regular language. User code is -embedded using inline operators that do not disrupt the regular language -syntax. - -The core language consists of standard regular expression operators, such as -union, concatenation and kleene star, accompanied by action embedding -operators. Ragel also provides operators that let you control any -non-determinism that you create, construct scanners using the longest match -paradigm, and build state machines using the statechart model. It is also -possible to influence the execution of a state machine from inside an embedded -action by jumping or calling to other parts of the machine and reprocessing -input. - -Ragel provides a very flexibile interface to the host language that attempts to -place minimal restrictions on how the generated code is used and integrated -into the application. The generated code has no dependencies. - -.SH OPTIONS -.TP -.BR \-h ", " \-H ", " \-? ", " \-\-help -Display help and exit. -.TP -.B \-v -Print version information and exit. -.TP -.B \-o " file" -Write output to file. If -o is not given, a default file name is chosen by -replacing the file extenstion of the input file. For source files ending in .rh -the suffix .h is used. For all other source files a suffix based on the output -language is used (.c, .cpp, .m, etc.). If -o is not given for Graphviz output -the generated dot file is written to standard output. -.TP -.B \-s -Print some statistics on standard error. -.TP -.B \--error-format=gnu -Print error messages using the format "file:line:column:" (default) -.TP -.B \--error-format=msvc -Print error messages using the format "file(line,column):" -.TP -.B \-d -Do not remove duplicate actions from action lists. -.TP -.B \-I " dir" -Add dir to the list of directories to search for included and imported files -.TP -.B \-n -Do not perform state minimization. -.TP -.B \-m -Perform minimization once, at the end of the state machine compilation. -.TP -.B \-l -Minimize after nearly every operation. Lists of like operations such as unions -are minimized once at the end. This is the default minimization option. -.TP -.B \-e -Minimize after every operation. -.TP -.B \-x -Compile the state machines and emit an XML representation of the host data and -the machines. -.TP -.B \-V -Generate a dot file for Graphviz. -.TP -.B \-p -Display printable characters on labels. -.TP -.B \-L -Inhibit writing of #line directives. -.TP -.B \-S <spec> -FSM specification to output. -.TP -.B \-M <machine> -Machine definition/instantiation to output. -.TP -.B \-C -The host language is C, C++, Obj-C or Obj-C++. This is the default host language option. -.TP -.B --asm --gas-x86-64-sys-v -GNU AS, x86_64, System V ABI -ASM is generated in a code style equiv to -G2 -.TP -.B \-D -The host language is D. -.TP -.B \-Z -The host language is Go. -.TP -.B \-J -The host language is Java. -.TP -.B \-R -The host language is Ruby. -.TP -.B -A -The host language is C# -.TP -.B -O -The host language is OCaml. -.TP -.B -U -The host language is Rust. -.TP -.B -Y -The host language is Julia. -.TP -.B -K -The host language is Crack. -.TP -.B -P -The host language is JavaScript. -.TP -.B \-T0 -(C/D/Java/Ruby/C#) Generate a table driven FSM. This is the default code style. -The table driven -FSM represents the state machine as static data. There are tables of states, -transitions, indices and actions. The current state is stored in a variable. -The execution is a loop that looks that given the current state and current -character to process looks up the transition to take using a binary search, -executes any actions and moves to the target state. In general, the table -driven FSM produces a smaller binary and requires a less expensive host language -compile but results in slower running code. The table driven FSM is suitable -for any FSM. -.TP -.B \-T1 -(C/D/Ruby/C#) Generate a faster table driven FSM by expanding action lists in the action -execute code. -.TP -.B \-F0 -(C/D/Ruby/C#) Generate a flat table driven FSM. Transitions are represented as an array -indexed by the current alphabet character. This eliminates the need for a -binary search to locate transitions and produces faster code, however it is -only suitable for small alphabets. -.TP -.B \-F1 -(C/D/Ruby/C#) Generate a faster flat table driven FSM by expanding action lists in the action -execute code. -.TP -.B \-G0 -(C/D/C#) Generate a goto driven FSM. The goto driven FSM represents the state machine -as a series of goto statements. While in the machine, the current state is -stored by the processor's instruction pointer. The execution is a flat function -where control is passed from state to state using gotos. In general, the goto -FSM produces faster code but results in a larger binary and a more expensive -host language compile. -.TP -.B \-G1 -(C/D/C#) Generate a faster goto driven FSM by expanding action lists in the action -execute code. -.TP -.B \-G2 -(C/D/Go) Generate a really fast goto driven FSM by embedding action lists in the state -machine control code. -.TP -.B --nfa-conds-depth=D -Search for high-cost conditions inside a prefix of the machine (depth D from -start state). Search is rooted at NFA union contructs. -.TP -.B --nfa-term-check -Search for condition-based general repetitions that will not function properly -and must be NFA reps. Search is rooted at NFA union constructs. -.TP -.B --nfa-intermed-state-limit=L -Report fail if number of states exceeds this during compilation. -.TP -.B --nfa-final-state-limit=L -Report a fail if number states in final machine exceeds this. -.TP -.B --nfa-breadth-check=E1,E2,.. -Report breadth cost of named entry points by (and start). Reporting starts at -NFA union contructs. -.TP -.B --input-histogram=FN -Input char histogram for breadth check. If unspecified a flat histogram is -used. -.SH RAGEL INPUT -NOTE: This is a very brief description of Ragel input. Ragel is described in -more detail in the user guide available from the homepage (see below). - -Ragel normally passes input files straight to the output. When it sees an FSM -specification that contains machine instantiations it stops to generate the -state machine. If there are write statements (such as "write exec") then ragel emits the -corresponding code. There can be any number of FSM specifications in an input -file. A multi-line FSM specification starts with '%%{' and ends with '}%%'. A -single line FSM specification starts with %% and ends at the first newline. -.SH FSM STATEMENTS -.TP -.I Machine Name: -Set the the name of the machine. If given, it must be the first statement. -.TP -.I Alphabet Type: -Set the data type of the alphabet. -.TP -.I GetKey: -Specify how to retrieve the alphabet character from the element type. -.TP -.I Include: -Include a machine of same name as the current or of a different name in either -the current file or some other file. -.TP -.I Action Definition: -Define an action that can be invoked by the FSM. -.TP -.I Fsm Definition, Instantiation and Longest Match Instantiation: -Used to build FSMs. Syntax description in next few sections. -.TP -.I Access: -Specify how to access the persistent state machine variables. -.TP -.I Write: -Write some component of the machine. -.TP -.I Variable: -Override the default variable names (p, pe, cs, act, etc). -.SH BASIC MACHINES -The basic machines are the base operands of the regular language expressions. -.TP -.I 'hello' -Concat literal. Produces a concatenation of the characters in the string. -Supports escape sequences with '\\'. The result will have a start state and a -transition to a new state for each character in the string. The last state in -the sequence will be made final. To make the string case-insensitive, append -an 'i' to the string, as in 'cmd'i\fR. -.TP -.I \(dqhello\(dq -Identical to single quote version. -.TP -.I [hello] -Or literal. Produces a union of characters. Supports character ranges -with '\-', negating the sense of the union with an initial '^' and escape -sequences with '\\'. The result will have two states with a transition between -them for each character or range. -.LP -NOTE: '', "", and [] produce null FSMs. Null machines have one state that is -both a start state and a final state and match the zero length string. A null machine -may be created with the null builtin machine. -.TP -.I integer -Makes a two state machine with one transition on the given integer number. -.TP -.I hex -Makes a two state machine with one transition on the given hexidecimal number. -.TP -.I "/simple_regex/" -A simple regular expression. Supports the notation '.', '*' and '[]', character -ranges with '\-', negating the sense of an OR expression with and initial '^' -and escape sequences with '\\'. Also supports one trailing flag: i. Use it to -produce a case-insensitive regular expression, as in /GET/i. -.TP -.I lit .. lit -Specifies a range. The allowable upper and lower bounds are concat literals of -length one and number machines. -For example, 0x10..0x20, 0..63, and 'a'..'z' are valid ranges. -.TP -.I "variable_name" -References the machine definition assigned to the variable name given. -.TP -.I "builtin_machine" -There are several builtin machines available. They are all two state machines -for the purpose of matching common classes of characters. They are: -.RS -.TP -.B any -Any character in the alphabet. -.TP -.B ascii -Ascii characters 0..127. -.TP -.B extend -Ascii extended characters. This is the range -128..127 for signed alphabets -and the range 0..255 for unsigned alphabets. -.TP -.B alpha -Alphabetic characters /[A-Za-z]/. -.TP -.B digit -Digits /[0-9]/. -.TP -.B alnum -Alpha numerics /[0-9A-Za-z]/. -.TP -.B lower -Lowercase characters /[a-z]/. -.TP -.B upper -Uppercase characters /[A-Z]/. -.TP -.B xdigit -Hexidecimal digits /[0-9A-Fa-f]/. -.TP -.B cntrl -Control characters 0..31, 127. -.TP -.B graph -Graphical characters /[!-~]/. -.TP -.B print -Printable characters /[ -~]/. -.TP -.B punct -Punctuation. Graphical characters that are not alpha-numerics -/[!-/:-@\\[-`{-~]/. -.TP -.B space -Whitespace /[\\t\\v\\f\\n\\r ]/. -.TP -.B null -Zero length string. Equivalent to '', "" and []. -.TP -.B empty -Empty set. Matches nothing. -.RE -.SH BRIEF OPERATOR REFERENCE -Operators are grouped by precedence, group 1 being the lowest and group 6 the -highest. -.LP -.B GROUP 1: -.TP -.I expr , expr -Join machines together without drawing any transitions, setting up a start -state or any final states. Start state must be explicitly specified with the -"start" label. Final states may be specified with the an epsilon transitions to -the implicitly created "final" state. -.LP -.B GROUP 2: -.TP -.I expr | expr -Produces a machine that matches any string in machine one or machine two. -.TP -.I expr & expr -Produces a machine that matches any string that is in both machine one and -machine two. -.TP -.I expr - expr -Produces a machine that matches any string that is in machine one but not in -machine two. -.TP -.I expr -- expr -Strong Subtraction. Matches any string in machine one that does not have any string -in machine two as a substring. -.LP -.B GROUP 3: -.TP -.I expr . expr -Produces a machine that matches all the strings in machine one followed -by all the strings in machine two. -.TP -.I expr :> expr -Entry-Guarded Concatenation: terminates machine one upon entry to machine two. -.TP -.I expr :>> expr -Finish-Guarded Concatenation: terminates machine one when machine two finishes. -.TP -.I expr <: expr -Left-Guarded Concatenation: gives a higher priority to machine one. -.LP -NOTE: Concatenation is the default operator. Two machines next to each other -with no operator between them results in the concatenation operation. -.LP -.B GROUP 4: -.TP -.I label: expr -Attaches a label to an expression. Labels can be used by epsilon transitions -and fgoto and fcall statements in actions. Also note that the referencing of a -machine definition causes the implicit creation of label by the same name. -.LP -.B GROUP 5: -.TP -.I expr -> label -Draws an epsilon transition to the state defined by label. Label must -be a name in the current scope. Epsilon transitions are resolved when -comma operators are evaluated and at the root of the expression tree of -machine assignment/instantiation. -.LP -.B GROUP 6: Actions -.LP -An action may be a name predefined with an action statement or may -be specified directly with '{' and '}' in the expression. -.TP -.I expr > action -Embeds action into starting transitions. -.TP -.I expr @ action -Embeds action into transitions that go into a final state. -.TP -.I expr $ action -Embeds action into all transitions. Does not include pending out transitions. -.TP -.I expr % action -Embeds action into pending out transitions from final states. -.LP -.B GROUP 6: EOF Actions -.LP -When a machine's finish routine is called the current state's EOF actions are -executed. -.TP -.I expr >/ action -Embed an EOF action into the start state. -.TP -.I expr </ action -Embed an EOF action into all states except the start state. -.TP -.I expr $/ action -Embed an EOF action into all states. -.TP -.I expr %/ action -Embed an EOF action into final states. -.TP -.I expr @/ action -Embed an EOF action into all states that are not final. -.TP -.I expr <>/ action -Embed an EOF action into all states that are not the start -state and that are not final (middle states). -.LP -.B GROUP 6: Global Error Actions -.LP -Global error actions are stored in states until the final state machine has -been fully constructed. They are then transferred to error transitions, giving -the effect of a default action. -.TP -.I expr >! action -Embed a global error action into the start state. -.TP -.I expr <! action -Embed a global error action into all states except the start state. -.TP -.I expr $! action -Embed a global error action into all states. -.TP -.I expr %! action -Embed a global error action into the final states. -.TP -.I expr @! action -Embed a global error action into all states which are not final. -.TP -.I expr <>! action -Embed a global error action into all states which are not the start state and -are not final (middle states). -.LP -.B GROUP 6: Local Error Actions -.LP -Local error actions are stored in states until the named machine is fully -constructed. They are then transferred to error transitions, giving the effect -of a default action for a section of the total machine. Note that the name may -be omitted, in which case the action will be transferred to error actions upon -construction of the current machine. -.TP -.I expr >^ action -Embed a local error action into the start state. -.TP -.I expr <^ action -Embed a local error action into all states except the start state. -.TP -.I expr $^ action -Embed a local error action into all states. -.TP -.I expr %^ action -Embed a local error action into the final states. -.TP -.I expr @^ action -Embed a local error action into all states which are not final. -.TP -.I expr <>^ action -Embed a local error action into all states which are not the start state and -are not final (middle states). -.LP -.B GROUP 6: To-State Actions -.LP -To state actions are stored in states and executed any time the machine moves -into a state. This includes regular transitions, and transfers of control such -as fgoto. Note that setting the current state from outside the machine (for -example during initialization) does not count as a transition into a state. -.TP -.I expr >~ action -Embed a to-state action action into the start state. -.TP -.I expr <~ action -Embed a to-state action into all states except the start state. -.TP -.I expr $~ action -Embed a to-state action into all states. -.TP -.I expr %~ action -Embed a to-state action into the final states. -.TP -.I expr @~ action -Embed a to-state action into all states which are not final. -.TP -.I expr <>~ action -Embed a to-state action into all states which are not the start state and -are not final (middle states). -.LP -.B GROUP 6: From-State Actions -.LP -From state actions are executed whenever a state takes a transition on a character. -This includes the error transition and a transition to self. -.TP -.I expr >* action -Embed a from-state action into the start state. -.TP -.I expr <* action -Embed a from-state action into every state except the start state. -.TP -.I expr $* action -Embed a from-state action into all states. -.TP -.I expr %* action -Embed a from-state action into the final states. -.TP -.I expr @* action -Embed a from-state action into all states which are not final. -.TP -.I expr <>* action -Embed a from-state action into all states which are not the start state and -are not final (middle states). -.LP -.B GROUP 6: Priority Assignment -.LP -Priorities are assigned to names within transitions. Only priorities on the -same name are allowed to interact. In the first form of priorities the name -defaults to the name of the machine definition the priority is assigned in. -Transitions do not have default priorities. -.TP -.I expr > int -Assigns the priority int in all transitions leaving the start state. -.TP -.I expr @ int -Assigns the priority int in all transitions that go into a final state. -.TP -.I expr $ int -Assigns the priority int in all existing transitions. -.TP -.I expr % int -Assigns the priority int in all pending out transitions. -.LP -A second form of priority assignment allows the programmer to specify the name -to which the priority is assigned, allowing interactions to cross machine -definition boundaries. -.TP -.I expr > (name,int) -Assigns the priority int to name in all transitions leaving the start state. -.TP -.I expr @ (name, int) -Assigns the priority int to name in all transitions that go into a final state. -.TP -.I expr $ (name, int) -Assigns the priority int to name in all existing transitions. -.TP -.I expr % (name, int) -Assigns the priority int to name in all pending out transitions. -.LP -.B GROUP 7: -.TP -.I expr * -Produces the kleene star of a machine. Matches zero or more repetitions of the -machine. -.TP -.I expr ** -Longest-Match Kleene Star. This version of kleene star puts a higher -priority on staying in the machine over wrapping around and starting over. This -operator is equivalent to ( ( expr ) $0 %1 )*. -.TP -.I expr ? -Produces a machine that accepts the machine given or the null string. This operator -is equivalent to ( expr | '' ). -.TP -.I expr + -Produces the machine concatenated with the kleen star of itself. Matches one or -more repetitions of the machine. This operator is equivalent to ( expr . expr* ). -.TP -.I expr {n} -Produces a machine that matches exactly n repetitions of expr. -.TP -.I expr {,n} -Produces a machine that matches anywhere from zero to n repetitions of expr. -.TP -.I expr {n,} -Produces a machine that matches n or more repetitions of expr. -.TP -.I expr {n,m} -Produces a machine that matches n to m repetitions of expr. -.LP -.B GROUP 8: -.TP -.I ! expr -Produces a machine that matches any string not matched by the given machine. -This operator is equivalent to ( *extend - expr ). -.TP -.I ^ expr -Character-Level Negation. Matches any single character not matched by the -single character machine expr. -.LP -.B GROUP 9: -.TP -.I ( expr ) -Forces precedence on operators. -.SH VALUES AVAILABLE IN CODE BLOCKS -.TP -.I fc -The current character. Equivalent to *p. -.TP -.I fpc -A pointer to the current character. Equivalent to p. -.TP -.I fcurs -An integer value representing the current state. -.TP -.I ftargs -An integer value representing the target state. -.TP -.I fentry(<label>) -An integer value representing the entry point <label>. -.SH STATEMENTS AVAILABLE IN CODE BLOCKS -.TP -.I fhold; -Do not advance over the current character. Equivalent to --p;. -.TP -.I fexec <expr>; -Sets the current character to something else. Equivalent to p = (<expr>)-1; -.TP -.I fgoto <label>; -Jump to the machine defined by <label>. -.TP -.I fgoto *<expr>; -Jump to the entry point given by <expr>. The expression must -evaluate to an integer value representing a state. -.TP -.I fnext <label>; -Set the next state to be the entry point defined by <label>. The fnext -statement does not immediately jump to the specified state. Any action code -following the statement is executed. -.TP -.I fnext *<expr>; -Set the next state to be the entry point given by <expr>. The expression must -evaluate to an integer value representing a state. -.TP -.I fcall <label>; -Call the machine defined by <label>. The next fret will jump to the -target of the transition on which the action is invoked. -.TP -.I fcall *<expr>; -Call the entry point given by <expr>. The next fret will jump to the target of -the transition on which the action is invoked. -.TP -.I fret; -Return to the target state of the transition on which the last fcall was made. -.TP -.I fbreak; -Save the current state and immediately break out of the machine. -.SH CREDITS -Ragel was written by Adrian Thurston <thurston@colm.net>. There have been many -contributors. Please see CREDITS file in source distribution. -.SH "SEE ALSO" -.BR re2c (1), -.BR flex (1) - -Homepage: http://www.colm.net/open-source/ragel/ diff --git a/doc/ragel/smallscanner.fig b/doc/ragel/smallscanner.fig deleted file mode 100644 index c86750ea..00000000 --- a/doc/ragel/smallscanner.fig +++ /dev/null @@ -1,78 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Portrait -Center -Metric -A4 -100.00 -Single --2 -# Generated by dot version 2.2.1 (Fri Sep 30 13:22:44 UTC 2005) -# For: (age) Adrian Thurston -# Title: smallscanner -# Pages: 1 -1200 2 -0 32 #d2d2d2 -# ENTRY -1 1 0 1 0 0 0 0 20 0.000 0 0.0000 33 3850 33 33 33 3850 66 3883 -# 0 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 3850 383 383 1400 3850 1783 4233 -1 1 0 1 0 32 0 0 -1 0.000 0 0.0000 1400 3850 450 450 1400 3850 1850 4300 -# 1 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5266 3850 383 383 5266 3850 5649 4233 -1 1 0 1 0 0 0 0 -1 0.000 0 0.0000 5266 3850 450 450 5266 3850 5716 4300 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 766 3783 933 3850 766 3900 766 3783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1116 3350 1083 3516 1016 3350 1116 3350 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4633 3783 4800 3850 4633 3883 4633 3783 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 1950 4183 1816 4066 2000 4083 1950 4183 -2 3 0 1 0 0 0 0 20 0.000 0 0 0 0 0 4 - 4983 3350 4950 3516 4883 3350 4983 3350 -2 2 0 0 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 - 7110 2835 -90 2835 -90 4455 7110 4455 7110 2835 -# ENTRY -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 7 - 66 3850 132 3850 225 3850 341 3850 474 3850 617 3850 - 766 3850 - 0.000 1.000 1.000 1.000 1.000 1.000 0.000 -# 0 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 1716 3516 1741 3410 1734 3312 1695 3227 1626 3159 1527 3115 - 1400 3100 1305 3108 1224 3131 1158 3168 1108 3218 1077 3279 - 1066 3350 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -# 0 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 1866 3850 1916 3842 1966 3838 2016 3835 2066 3833 2116 3833 - 2166 3833 2632 3833 3008 3833 3339 3833 3669 3833 4041 3833 - 4500 3833 4523 3833 4545 3833 4566 3833 4587 3833 4609 3833 - 4633 3833 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 1 -> 0 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 19 - 4866 4066 4807 4091 4745 4115 4683 4137 4620 4156 4559 4172 - 4500 4183 4050 4266 3676 4316 3339 4333 3001 4316 2623 4266 - 2166 4183 2133 4175 2100 4166 2066 4158 2033 4150 2000 4141 - 1966 4133 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 0.000 -# 1 -> 1 -3 4 0 1 0 0 0 0 -1 0.000 0 0 0 13 - 5583 3516 5608 3410 5601 3312 5562 3227 5493 3159 5394 3115 - 5266 3100 5172 3108 5091 3131 5025 3168 4975 3218 4944 3279 - 4933 3350 - 0.000 1.000 1.000 1.000 1.000 1.000 1.000 1.000 - 1.000 1.000 1.000 1.000 0.000 -4 1 0 0 0 0 14 0.0000 2 150 120 1400 3933 0\001 -4 1 0 0 0 0 14 0.0000 2 150 255 500 3800 IN\001 -4 1 0 0 0 0 14 0.0000 2 150 150 1400 3050 ' '\001 -4 1 0 0 0 0 14 0.0000 2 165 120 5266 3933 1\001 -4 1 0 0 0 0 14 0.0000 2 180 2310 3333 3783 'a'..'z' / start_str, on_char\001 -4 1 0 0 0 0 14 0.0000 2 180 1200 3333 4116 ' ' / finish_str\001 -4 1 0 0 0 0 14 0.0000 2 180 3300 5266 3050 'a'..'z' / on_char, finish_str, start_str\001 diff --git a/doc/ragel/stembed.fig b/doc/ragel/stembed.fig deleted file mode 100644 index eb3ce8d1..00000000 --- a/doc/ragel/stembed.fig +++ /dev/null @@ -1,72 +0,0 @@ -#FIG 3.2 Produced by xfig version 3.2.5-alpha5 -Landscape -Center -Metric -A4 -100.00 -Single --2 -1200 2 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 463 1772 463 1875 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 955 1772 955 1875 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 1461 1772 1461 1875 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 1948 1772 1948 1875 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 2403 1772 2403 1875 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 2906 1772 2906 1875 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 3377 173 3510 173 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 3377 881 3510 881 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 3377 532 3510 532 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 3377 1609 3510 1609 -2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 - 3377 1260 3510 1260 -4 0 0 50 -1 12 12 0.0000 4 105 240 405 225 >~\001 -4 0 0 50 -1 0 12 0.0000 4 150 1545 3690 585 from-state actions\001 -4 0 0 50 -1 0 12 0.0000 4 150 1290 3690 225 to state actions\001 -4 0 0 50 -1 0 12 0.0000 4 150 1545 3690 1665 local error actions\001 -4 0 0 50 -1 0 12 0.0000 4 150 1095 3690 1305 error actions\001 -4 0 0 50 -1 0 12 0.0000 4 150 1065 3690 945 EOF actions\001 -4 0 0 50 -1 0 12 5.6723 4 120 855 405 2044 start state\001 -4 0 0 50 -1 0 12 5.6723 4 150 360 1409 2071 final\001 -4 0 0 50 -1 0 12 5.6723 4 150 750 901 2038 all states\001 -4 0 0 50 -1 12 12 0.0000 4 165 240 900 225 $~\001 -4 0 0 50 -1 12 12 0.0000 4 120 240 1395 225 %~\001 -4 0 0 50 -1 12 12 0.0000 4 105 240 1890 225 <~\001 -4 0 0 50 -1 12 12 0.0000 4 135 360 2835 225 <>~\001 -4 0 0 50 -1 12 12 0.0000 4 120 360 405 585 >* \001 -4 0 0 50 -1 12 12 0.0000 4 165 240 900 585 $*\001 -4 0 0 50 -1 12 12 0.0000 4 135 360 2835 585 <>*\001 -4 0 0 50 -1 12 12 0.0000 4 120 240 405 1305 >!\001 -4 0 0 50 -1 12 12 0.0000 4 150 240 405 945 >/\001 -4 0 0 50 -1 12 12 0.0000 4 165 240 900 945 $/\001 -4 0 0 50 -1 12 12 0.0000 4 120 240 1395 585 %*\001 -4 0 0 50 -1 12 12 0.0000 4 150 240 1395 945 %/\001 -4 0 0 50 -1 12 12 0.0000 4 150 240 1890 945 </\001 -4 0 0 50 -1 12 12 0.0000 4 150 240 2340 945 @/\001 -4 0 0 50 -1 12 12 0.0000 4 150 360 2835 945 <>/\001 -4 0 0 50 -1 12 12 0.0000 4 105 240 1890 585 <*\001 -4 0 0 50 -1 12 12 0.0000 4 120 240 1890 1305 <!\001 -4 0 0 50 -1 12 12 0.0000 4 120 240 1395 1305 %!\001 -4 0 0 50 -1 12 12 0.0000 4 165 240 900 1305 $!\001 -4 0 0 50 -1 12 12 0.0000 4 165 240 900 1665 $^\001 -4 0 0 50 -1 12 12 0.0000 4 120 240 405 1665 >^\001 -4 0 0 50 -1 12 12 0.0000 4 135 240 1395 1665 %^\001 -4 0 0 50 -1 12 12 0.0000 4 120 240 1890 1665 <^\001 -4 0 0 50 -1 12 12 0.0000 4 135 240 2340 1665 @^\001 -4 0 0 50 -1 12 12 0.0000 4 135 360 2835 1665 <>^\001 -4 0 0 50 -1 12 12 0.0000 4 135 240 2340 1305 @!\001 -4 0 0 50 -1 12 12 0.0000 4 135 360 2835 1305 <>!\001 -4 0 0 50 -1 12 12 0.0000 4 135 240 2340 585 @*\001 -4 0 0 50 -1 12 12 0.0000 4 135 240 2340 225 @~\001 -4 0 0 50 -1 0 12 5.6723 4 150 1635 2860 2053 not start & not final\001 -4 0 0 50 -1 0 12 5.6723 4 120 705 1883 2050 not start\001 -4 0 0 50 -1 0 12 5.6723 4 150 675 2359 2048 not final\001 |