2 .\" Copyright 2001-2007 Adrian Thurston <thurston@complang.org>
5 .\" This file is part of Ragel.
7 .\" Ragel is free software; you can redistribute it and/or modify
8 .\" it under the terms of the GNU General Public License as published by
9 .\" the Free Software Foundation; either version 2 of the License, or
10 .\" (at your option) any later version.
12 .\" Ragel is distributed in the hope that it will be useful,
13 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
14 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 .\" GNU General Public License for more details.
17 .\" You should have received a copy of the GNU General Public License
18 .\" along with Ragel; if not, write to the Free Software
19 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 .\" Process this file with
22 .\" groff -man -Tascii ragel.1
24 .TH RAGEL 1 "@PUBDATE@" "Ragel @VERSION@" "Ragel State Machine Compiler"
26 ragel \- compile regular languages into executable state machines
32 Ragel compiles executable finite state machines from regular languages.
33 Ragel can generate C, C++, Objective-C, D, or Java code. Ragel state
34 machines can not only recognize byte
35 sequences as regular expression machines do, but can also execute code at
36 arbitrary points in the recognition of a regular language. User code is
37 embedded using inline operators that do not disrupt the regular language
40 The core language consists of standard regular expression operators, such as
41 union, concatenation and kleene star, accompanied by action embedding
42 operators. Ragel also provides operators that let you control any
43 non-determinism that you create, construct scanners using the longest match
44 paradigm, and build state machines using the statechart model. It is also
45 possible to influence the execution of a state machine from inside an embedded
46 action by jumping or calling to other parts of the machine and reprocessing
49 Ragel provides a very flexibile interface to the host language that attempts to
50 place minimal restrictions on how the generated code is used and integrated
51 into the application. The generated code has no dependencies.
55 .BR \-h ", " \-H ", " \-? ", " \-\-help
56 Display help and exit.
59 Print version information and exit.
62 Write output to file. If -o is not given, a default file name is chosen by
63 replacing the suffix of the input. For source files ending in .rh the suffix .h
64 is used. For all other source files a suffix based on the output language
65 is used (.c, .cpp, .m, .dot)
68 Print some statistics on standard error.
70 .B \--error-format=gnu
71 Print error messages using the format "file:line:column:" (default)
73 .B \--error-format=msvc
74 Print error messages using the format "file(line,column):"
77 Do not remove duplicate actions from action lists.
80 Add dir to the list of directories to search for included and imported files
83 Do not perform state minimization.
86 Perform minimization once, at the end of the state machine compilation.
89 Minimize after nearly every operation. Lists of like operations such as unions
90 are minimized once at the end. This is the default minimization option.
93 Minimize after every operation.
96 Run the frontend only: emit XML intermediate format.
99 Generate a dot file for Graphviz.
102 Display printable characters on labels.
105 FSM specification to output
108 Machine definition/instantiation to output
111 The host language is C, C++, Obj-C or Obj-C++. This is the default host language option.
114 The host language is D.
117 The host language is Java.
120 The host language is Ruby.
123 Inhibit writing of #line directives.
126 Table driven FSM (default).
129 Faster table driven FSM.
132 Flat table driven FSM.
135 Faster flat table-driven FSM.
141 Faster goto-driven FSM.
144 Really fast goto-driven FSM.
147 N-Way Split really fast goto-driven FSM.
150 NOTE: This is a very brief description of Ragel input. Ragel is described in
151 more detail in the user guide available from the homepage (see below).
153 Ragel normally passes input files straight to the output. When it sees an FSM
154 specification that contains machine instantiations it stops to generate the
155 state machine. If there are write statements (such as "write exec") then ragel emits the
156 corresponding code. There can be any number of FSM specifications in an input
157 file. A multi-line FSM specification starts with '%%{' and ends with '}%%'. A
158 single line FSM specification starts with %% and ends at the first newline.
162 Set the the name of the machine. If given, it must be the first statement.
165 Set the data type of the alphabet.
168 Specify how to retrieve the alphabet character from the element type.
171 Include a machine of same name as the current or of a different name in either
172 the current file or some other file.
174 .I Action Definition:
175 Define an action that can be invoked by the FSM.
177 .I Fsm Definition, Instantiation and Longest Match Instantiation:
178 Used to build FSMs. Syntax description in next few sections.
181 Specify how to access the persistent state machine variables.
184 Write some component of the machine.
187 Override the default variable names (p, pe, cs, act, etc).
189 The basic machines are the base operands of the regular language expressions.
192 Concat literal. Produces a concatenation of the characters in the string.
193 Supports escape sequences with '\\'. The result will have a start state and a
194 transition to a new state for each character in the string. The last state in
195 the sequence will be made final. To make the string case-insensitive, append
196 an 'i' to the string, as in 'cmd'i\fR.
199 Identical to single quote version.
202 Or literal. Produces a union of characters. Supports character ranges
203 with '\-', negating the sense of the union with an initial '^' and escape
204 sequences with '\\'. The result will have two states with a transition between
205 them for each character or range.
207 NOTE: '', "", and [] produce null FSMs. Null machines have one state that is
208 both a start state and a final state and match the zero length string. A null machine
209 may be created with the null builtin machine.
212 Makes a two state machine with one transition on the given integer number.
215 Makes a two state machine with one transition on the given hexidecimal number.
218 A simple regular expression. Supports the notation '.', '*' and '[]', character
219 ranges with '\-', negating the sense of an OR expression with and initial '^'
220 and escape sequences with '\\'. Also supports one trailing flag: i. Use it to
221 produce a case-insensitive regular expression, as in /GET/i.
224 Specifies a range. The allowable upper and lower bounds are concat literals of
225 length one and number machines.
226 For example, 0x10..0x20, 0..63, and 'a'..'z' are valid ranges.
229 References the machine definition assigned to the variable name given.
232 There are several builtin machines available. They are all two state machines
233 for the purpose of matching common classes of characters. They are:
237 Any character in the alphabet.
240 Ascii characters 0..127.
243 Ascii extended characters. This is the range -128..127 for signed alphabets
244 and the range 0..255 for unsigned alphabets.
247 Alphabetic characters /[A-Za-z]/.
253 Alpha numerics /[0-9A-Za-z]/.
256 Lowercase characters /[a-z]/.
259 Uppercase characters /[A-Z]/.
262 Hexidecimal digits /[0-9A-Fa-f]/.
265 Control characters 0..31.
268 Graphical characters /[!-~]/.
271 Printable characters /[ -~]/.
274 Punctuation. Graphical characters that are not alpha-numerics
278 Whitespace /[\\t\\v\\f\\n\\r ]/.
281 Zero length string. Equivalent to '', "" and [].
284 Empty set. Matches nothing.
286 .SH BRIEF OPERATOR REFERENCE
287 Operators are grouped by precedence, group 1 being the lowest and group 6 the
293 Join machines together without drawing any transitions, setting up a start
294 state or any final states. Start state must be explicitly specified with the
295 "start" label. Final states may be specified with the an epsilon transitions to
296 the implicitly created "final" state.
301 Produces a machine that matches any string in machine one or machine two.
304 Produces a machine that matches any string that is in both machine one and
308 Produces a machine that matches any string that is in machine one but not in
312 Strong Subtraction. Matches any string in machine one that does not have any string
313 in machine two as a substring.
318 Produces a machine that matches all the strings in machine one followed
319 by all the strings in machine two.
322 Entry-Guarded Concatenation: terminates machine one upon entry to machine two.
325 Finish-Guarded Concatenation: terminates machine one when machine two finishes.
328 Left-Guarded Concatenation: gives a higher priority to machine one.
330 NOTE: Concatenation is the default operator. Two machines next to each other
331 with no operator between them results in the concatenation operation.
336 Attaches a label to an expression. Labels can be used by epsilon transitions
337 and fgoto and fcall statements in actions. Also note that the referencing of a
338 machine definition causes the implicit creation of label by the same name.
343 Draws an epsilon transition to the state defined by label. Label must
344 be a name in the current scope. Epsilon transitions are resolved when
345 comma operators are evaluated and at the root of the expression tree of
346 machine assignment/instantiation.
350 An action may be a name predefined with an action statement or may
351 be specified directly with '{' and '}' in the expression.
354 Embeds action into starting transitions.
357 Embeds action into transitions that go into a final state.
360 Embeds action into all transitions. Does not include pending out transitions.
363 Embeds action into pending out transitions from final states.
365 .B GROUP 6: EOF Actions
367 When a machine's finish routine is called the current state's EOF actions are
371 Embed an EOF action into the start state.
374 Embed an EOF action into all states except the start state.
377 Embed an EOF action into all states.
380 Embed an EOF action into final states.
383 Embed an EOF action into all states that are not final.
386 Embed an EOF action into all states that are not the start
387 state and that are not final (middle states).
389 .B GROUP 6: Global Error Actions
391 Global error actions are stored in states until the final state machine has
392 been fully constructed. They are then transferred to error transitions, giving
393 the effect of a default action.
396 Embed a global error action into the start state.
399 Embed a global error action into all states except the start state.
402 Embed a global error action into all states.
405 Embed a global error action into the final states.
408 Embed a global error action into all states which are not final.
411 Embed a global error action into all states which are not the start state and
412 are not final (middle states).
414 .B GROUP 6: Local Error Actions
416 Local error actions are stored in states until the named machine is fully
417 constructed. They are then transferred to error transitions, giving the effect
418 of a default action for a section of the total machine. Note that the name may
419 be omitted, in which case the action will be transferred to error actions upon
420 construction of the current machine.
423 Embed a local error action into the start state.
426 Embed a local error action into all states except the start state.
429 Embed a local error action into all states.
432 Embed a local error action into the final states.
435 Embed a local error action into all states which are not final.
438 Embed a local error action into all states which are not the start state and
439 are not final (middle states).
441 .B GROUP 6: To-State Actions
443 To state actions are stored in states and executed any time the machine moves
444 into a state. This includes regular transitions, and transfers of control such
445 as fgoto. Note that setting the current state from outside the machine (for
446 example during initialization) does not count as a transition into a state.
449 Embed a to-state action action into the start state.
452 Embed a to-state action into all states except the start state.
455 Embed a to-state action into all states.
458 Embed a to-state action into the final states.
461 Embed a to-state action into all states which are not final.
464 Embed a to-state action into all states which are not the start state and
465 are not final (middle states).
467 .B GROUP 6: From-State Actions
469 From state actions are executed whenever a state takes a transition on a character.
470 This includes the error transition and a transition to self.
473 Embed a from-state action into the start state.
476 Embed a from-state action into every state except the start state.
479 Embed a from-state action into all states.
482 Embed a from-state action into the final states.
485 Embed a from-state action into all states which are not final.
488 Embed a from-state action into all states which are not the start state and
489 are not final (middle states).
491 .B GROUP 6: Priority Assignment
493 Priorities are assigned to names within transitions. Only priorities on the
494 same name are allowed to interact. In the first form of priorities the name
495 defaults to the name of the machine definition the priority is assigned in.
496 Transitions do not have default priorities.
499 Assigns the priority int in all transitions leaving the start state.
502 Assigns the priority int in all transitions that go into a final state.
505 Assigns the priority int in all existing transitions.
508 Assigns the priority int in all pending out transitions.
510 A second form of priority assignment allows the programmer to specify the name
511 to which the priority is assigned, allowing interactions to cross machine
512 definition boundaries.
515 Assigns the priority int to name in all transitions leaving the start state.
517 .I expr @ (name, int)
518 Assigns the priority int to name in all transitions that go into a final state.
520 .I expr $ (name, int)
521 Assigns the priority int to name in all existing transitions.
523 .I expr % (name, int)
524 Assigns the priority int to name in all pending out transitions.
529 Produces the kleene star of a machine. Matches zero or more repetitions of the
533 Longest-Match Kleene Star. This version of kleene star puts a higher
534 priority on staying in the machine over wrapping around and starting over. This
535 operator is equivalent to ( ( expr ) $0 %1 )*.
538 Produces a machine that accepts the machine given or the null string. This operator
539 is equivalent to ( expr | '' ).
542 Produces the machine concatenated with the kleen star of itself. Matches one or
543 more repetitions of the machine. This operator is equivalent to ( expr . expr* ).
546 Produces a machine that matches exactly n repetitions of expr.
549 Produces a machine that matches anywhere from zero to n repetitions of expr.
552 Produces a machine that matches n or more repetitions of expr.
555 Produces a machine that matches n to m repetitions of expr.
560 Produces a machine that matches any string not matched by the given machine.
561 This operator is equivalent to ( *extend - expr ).
564 Character-Level Negation. Matches any single character not matched by the
565 single character machine expr.
570 Forces precedence on operators.
571 .SH VALUES AVAILABLE IN CODE BLOCKS
574 The current character. Equivalent to *p.
577 A pointer to the current character. Equivalent to p.
580 An integer value representing the current state.
583 An integer value representing the target state.
586 An integer value representing the entry point <label>.
587 .SH STATEMENTS AVAILABLE IN CODE BLOCKS
590 Do not advance over the current character. Equivalent to --p;.
593 Sets the current character to something else. Equivalent to p = (<expr>)-1;
596 Jump to the machine defined by <label>.
599 Jump to the entry point given by <expr>. The expression must
600 evaluate to an integer value representing a state.
603 Set the next state to be the entry point defined by <label>. The fnext
604 statement does not immediately jump to the specified state. Any action code
605 following the statement is executed.
608 Set the next state to be the entry point given by <expr>. The expression must
609 evaluate to an integer value representing a state.
612 Call the machine defined by <label>. The next fret will jump to the
613 target of the transition on which the action is invoked.
616 Call the entry point given by <expr>. The next fret will jump to the target of
617 the transition on which the action is invoked.
620 Return to the target state of the transition on which the last fcall was made.
623 Save the current state and immediately break out of the machine.
625 Ragel is still under development and has not yet matured. There are probably
628 Ragel was written by Adrian Thurston <thurston@complang.org>. Objective-C
629 output contributed by Erich Ocean. D output contributed by Alan West.
637 Homepage: http://www.cs.queensu.ca/~thurston/ragel/