doc/ragel.1.in

   1 .\"
   2 .\"   Copyright 2001-2007 Adrian Thurston <thurston@cs.queensu.ca>
   3 .\"
   4
   5 .\"   This file is part of Ragel.
   6 .\"
   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.
  11 .\"
  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.
  16 .\"
  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
  20
  21 .\"   Process this file with
  22 .\"   groff -man -Tascii ragel.1
  23 .\"
  24 .TH RAGEL 1 "@PUBDATE@" "Ragel @VERSION@" "Ragel State Machine Compiler"
  25 .SH NAME
  26 ragel \- compile regular languages into executable state machines
  27 .SH SYNOPSIS
  28 .B ragel
  29 .RI [ options ]
  30 .I file
  31 .SH DESCRIPTION
  32 .B Note:
  33 this is the frontend component of Ragel, which generates an intermediate
  34 file format that must be processed by rlcodegen(1).
  35
  36 Ragel compiles finite state machines from regular languages into executable
  37 code.  Ragel can generate C, C++, Objective-C, D, or Java code. Ragel state
  38 machines can not only recognize byte
  39 sequences as regular expression machines do, but can also execute code at
  40 arbitrary points in the recognition of a regular language.  User code is
  41 embedded using inline operators that do not disrupt the regular language
  42 syntax.
  43
  44 The core language consists of standard regular expression operators, such as
  45 union, concatenation and kleene star, accompanied by action embedding
  46 operators. Ragel also provides operators that let you control any
  47 non-determinism that you create, construct scanners using the longest match
  48 paradigm, and build state machines using the statechart model. It is also
  49 possible to influence the execution of a state machine from inside an embedded
  50 action by jumping or calling to other parts of the machine and reprocessing
  51 input.
  52
  53 Ragel provides a very flexibile interface to the host language that attempts to
  54 place minimal restrictions on how the generated code is used and integrated
  55 into the application. The generated code has no dependencies.
  56
  57 .SH OPTIONS
  58 .TP
  59 .BR \-h ", " \-H ", " \-? ", " \-\-help
  60 Display help and exit.
  61 .TP
  62 .B \-o " file"
  63 Write output to file. If -o is not given, a default file name is chosen by
  64 replacing the suffix of the input. For source files ending in .rh the suffix .h
  65 is used. For all other source files a suffix based on the output language
  66 is used (.c, .cpp, .m, .dot)
  67 .TP
  68 .B \-n
  69 Do not perform state minimization.
  70 .TP
  71 .B \-m
  72 Perform minimization once, at the end of the state machine compilation.
  73 .TP
  74 .B \-l
  75 Minimize after nearly every operation. Lists of like operations such as unions
  76 are minimized once at the end. This is the default minimization option.
  77 .TP
  78 .B \-e
  79 Minimize after every operation.
  80 .TP
  81 .B \-S <spec>
  82 FSM specification to output for -V
  83 .TP
  84 .B \-M <machine>
  85 Machine definition/instantiation to output for -V
  86 .TP
  87 .B \-C
  88 The host language is C, C++, Obj-C or Obj-C++. This is the default host language option.
  89 .TP
  90 .B \-D
  91 The host language is D.
  92 .TP
  93 .B \-J
  94 The host language is Java.
  95 .SH RAGEL INPUT
  96 NOTE: This is a very brief description of Ragel input. Ragel is described in
  97 more detail in the user guide available from the homepage (see below).
  98
  99 Ragel normally passes input files straight to the output. When it sees an FSM
 100 specification that contains machine instantiations it stops to generate the
 101 state machine. If there are write statements (such as "write exec") then ragel emits the
 102 corresponding code. There can be any number of FSM specifications in an input
 103 file. A multi-line FSM specification starts with '%%{' and ends with '}%%'. A
 104 single line FSM specification starts with %% and ends at the first newline.
 105 .SH FSM STATEMENTS
 106 .TP
 107 .I Machine Name:
 108 Set the the name of the machine. If given, it must be the first statement.
 109 .TP
 110 .I Alphabet Type:
 111 Set the data type of the alphabet.
 112 .TP
 113 .I GetKey:
 114 Specify how to retrieve the alphabet character from the element type.
 115 .TP
 116 .I Include:
 117 Include a machine of same name as the current or of a different name in either
 118 the current file or some other file.
 119 .TP
 120 .I Action Definition:
 121 Define an action that can be invoked by the FSM.
 122 .TP
 123 .I Fsm Definition, Instantiation and Longest Match Instantiation:
 124 Used to build FSMs. Syntax description in next few sections.
 125 .TP
 126 .I Access:
 127 Specify how to access the persistent state machine variables.
 128 .TP
 129 .I Write:
 130 Write some component of the machine.
 131 .SH BASIC MACHINES
 132 The basic machines are the base operands of the regular language expressions.
 133 .TP
 134 .I 'hello'
 135 Concat literal. Produces a concatenation of the characters in the string.
 136 Supports escape sequences with '\\'.  The result will have a start state and a
 137 transition to a new state for each character in the string. The last state in
 138 the sequence will be made final. To make the string case-insensitive, append
 139 an 'i' to the string, as in 'cmd'i\fR.
 140 .TP
 141 .I \(dqhello\(dq
 142 Identical to single quote version.
 143 .TP
 144 .I [hello]
 145 Or literal. Produces a union of characters.  Supports character ranges
 146 with '\-', negating the sense of the union with an initial '^' and escape
 147 sequences with '\\'. The result will have two states with a transition between
 148 them for each character or range.
 149 .LP
 150 NOTE: '', "", and [] produce null FSMs. Null machines have one state that is
 151 both a start state and a final state and match the zero length string. A null machine
 152 may be created with the null builtin machine.
 153 .TP
 154 .I integer
 155 Makes a two state machine with one transition on the given integer number.
 156 .TP
 157 .I hex
 158 Makes a two state machine with one transition on the given hexidecimal number.
 159 .TP
 160 .I "/simple_regex/"
 161 A simple regular expression. Supports the notation '.', '*' and '[]', character
 162 ranges with '\-', negating the sense of an OR expression with and initial '^'
 163 and escape sequences with '\\'. Also supports one trailing flag: i. Use it to
 164 produce a case-insensitive regular expression, as in /GET/i.
 165 .TP
 166 .I lit .. lit
 167 Specifies a range. The allowable upper and lower bounds are concat literals of
 168 length one and number machines.
 169 For example, 0x10..0x20,  0..63, and 'a'..'z' are valid ranges.
 170 .TP
 171 .I "variable_name"
 172 References the machine definition assigned to the variable name given.
 173 .TP
 174 .I "builtin_machine"
 175 There are several builtin machines available. They are all two state machines
 176 for the purpose of matching common classes of characters. They are:
 177 .RS
 178 .TP
 179 .B any
 180 Any character in the alphabet.
 181 .TP
 182 .B ascii
 183 Ascii characters 0..127.
 184 .TP
 185 .B extend
 186 Ascii extended characters. This is the range -128..127 for signed alphabets
 187 and the range 0..255 for unsigned alphabets.
 188 .TP
 189 .B alpha
 190 Alphabetic characters /[A-Za-z]/.
 191 .TP
 192 .B digit
 193 Digits /[0-9]/.
 194 .TP
 195 .B alnum
 196 Alpha numerics /[0-9A-Za-z]/.
 197 .TP
 198 .B lower
 199 Lowercase characters /[a-z]/.
 200 .TP
 201 .B upper
 202 Uppercase characters /[A-Z]/.
 203 .TP
 204 .B xdigit
 205 Hexidecimal digits /[0-9A-Fa-f]/.
 206 .TP
 207 .B cntrl
 208 Control characters 0..31.
 209 .TP
 210 .B graph
 211 Graphical characters /[!-~]/.
 212 .TP
 213 .B print
 214 Printable characters /[ -~]/.
 215 .TP
 216 .B punct
 217 Punctuation. Graphical characters that are not alpha-numerics
 218 /[!-/:-@\\[-`{-~]/.
 219 .TP
 220 .B space
 221 Whitespace /[\\t\\v\\f\\n\\r ]/.
 222 .TP
 223 .B null
 224 Zero length string. Equivalent to '', "" and [].
 225 .TP
 226 .B empty
 227 Empty set. Matches nothing.
 228 .RE
 229 .SH BRIEF OPERATOR REFERENCE
 230 Operators are grouped by precedence, group 1 being the lowest and group 6 the
 231 highest.
 232 .LP
 233 .B GROUP 1:
 234 .TP
 235 .I expr , expr
 236 Join machines together without drawing any transitions, setting up a start
 237 state or any final states. Start state must be explicitly specified with the
 238 "start" label. Final states may be specified with the an epsilon transitions to
 239 the implicitly created "final" state.
 240 .LP
 241 .B GROUP 2:
 242 .TP
 243 .I expr | expr
 244 Produces a machine that matches any string in machine one or machine two.
 245 .TP
 246 .I expr & expr
 247 Produces a machine that matches any string that is in both machine one and
 248 machine two.
 249 .TP
 250 .I expr - expr
 251 Produces a machine that matches string that is in machine one but not in
 252 machine two.
 253 .LP
 254 .B GROUP 3:
 255 .TP
 256 .I expr . expr
 257 Produces a machine that matches all the strings in machine one followed
 258 by all the strings in machine two.
 259 .LP
 260 NOTE: Concatenation is the default operator. Two machines next to each other
 261 with no operator between them results in the concatenation operation.
 262 .LP
 263 .B GROUP 4:
 264 .TP
 265 .I label: expr
 266 Attaches a label to an expression. Labels can be used by epsilon transitions
 267 and fgoto and fcall statements in actions. Also note that the referencing of a
 268 machine definition causes the implicit creation of label by the same name.
 269 .LP
 270 .B GROUP 5:
 271 .TP
 272 .I expr -> label
 273 Draws an epsilon transition to the state defined by label. Label must
 274 be a name in the current scope. Epsilon transitions are resolved when
 275 comma operators are evaluated and at the root of the expression tree of
 276 machine assignment/instantiation.
 277 .LP
 278 .B GROUP 6: Actions
 279 .LP
 280 An action may be a name predefined with an action statement or may
 281 be specified directly with '{' and '}' in the expression.
 282 .TP
 283 .I expr > action
 284 Embeds action into starting transitions.
 285 .TP
 286 .I expr @ action
 287 Embeds action into transitions that go into a final state.
 288 .TP
 289 .I expr $ action
 290 Embeds action into all transitions. Does not include pending out transitions.
 291 .TP
 292 .I expr % action
 293 Embeds action into pending out transitions from final states.
 294 .LP
 295 .B GROUP 6: EOF Actions
 296 .LP
 297 When a machine's finish routine is called the current state's EOF actions are
 298 executed.
 299 .TP
 300 .I expr >/ action
 301 Embed an EOF action into the start state.
 302 .TP
 303 .I expr </ action
 304 Embed an EOF action into all states except the start state.
 305 .TP
 306 .I expr $/ action
 307 Embed an EOF action into all states.
 308 .TP
 309 .I expr %/ action
 310 Embed an EOF action into final states.
 311 .TP
 312 .I expr @/ action
 313 Embed an EOF action into all states that are not final.
 314 .TP
 315 .I expr <>/ action
 316 Embed an EOF action into all states that are not the start
 317 state and that are not final (middle states).
 318 .LP
 319 .B GROUP 6: Global Error Actions
 320 .LP
 321 Global error actions are stored in states until the final state machine has
 322 been fully constructed. They are then transferred to error transitions, giving
 323 the effect of a default action.
 324 .TP
 325 .I expr >! action
 326 Embed a global error action into the start state.
 327 .TP
 328 .I expr <! action
 329 Embed a global error action into all states except the start state.
 330 .TP
 331 .I expr $! action
 332 Embed a global error action into all states.
 333 .TP
 334 .I expr %! action
 335 Embed a global error action into the final states.
 336 .TP
 337 .I expr @! action
 338 Embed a global error action into all states which are not final.
 339 .TP
 340 .I expr <>! action
 341 Embed a global error action into all states which are not the start state and
 342 are not final (middle states).
 343 .LP
 344 .B GROUP 6: Local Error Actions
 345 .LP
 346 Local error actions are stored in states until the named machine is fully
 347 constructed. They are then transferred to error transitions, giving the effect
 348 of a default action for a section of the total machine. Note that the name may
 349 be omitted, in which case the action will be transferred to error actions upon
 350 construction of the current machine.
 351 .TP
 352 .I expr >^ action
 353 Embed a local error action into the start state.
 354 .TP
 355 .I expr <^ action
 356 Embed a local error action into all states except the start state.
 357 .TP
 358 .I expr $^ action
 359 Embed a local error action into all states.
 360 .TP
 361 .I expr %^ action
 362 Embed a local error action into the final states.
 363 .TP
 364 .I expr @^ action
 365 Embed a local error action into all states which are not final.
 366 .TP
 367 .I expr <>^ action
 368 Embed a local error action into all states which are not the start state and
 369 are not final (middle states).
 370 .LP
 371 .B GROUP 6: To-State Actions
 372 .LP
 373 To state actions are stored in states and executed any time the machine moves
 374 into a state. This includes regular transitions, and transfers of control such
 375 as fgoto. Note that setting the current state from outside the machine (for
 376 example during initialization) does not count as a transition into a state.
 377 .TP
 378 .I expr >~ action
 379 Embed a to-state action action into the start state.
 380 .TP
 381 .I expr <~ action
 382 Embed a to-state action into all states except the start state.
 383 .TP
 384 .I expr $~ action
 385 Embed a to-state action into all states.
 386 .TP
 387 .I expr %~ action
 388 Embed a to-state action into the final states.
 389 .TP
 390 .I expr @~ action
 391 Embed a to-state action into all states which are not final.
 392 .TP
 393 .I expr <>~ action
 394 Embed a to-state action into all states which are not the start state and
 395 are not final (middle states).
 396 .LP
 397 .B GROUP 6: From-State Actions
 398 .LP
 399 From state actions are executed whenever a state takes a transition on a character.
 400 This includes the error transition and a transition to self.
 401 .TP
 402 .I expr >* action
 403 Embed a from-state action into the start state.
 404 .TP
 405 .I expr <* action
 406 Embed a from-state action into every state except the start state.
 407 .TP
 408 .I expr $* action
 409 Embed a from-state action into all states.
 410 .TP
 411 .I expr %* action
 412 Embed a from-state action into the final states.
 413 .TP
 414 .I expr @* action
 415 Embed a from-state action into all states which are not final.
 416 .TP
 417 .I expr <>* action
 418 Embed a from-state action into all states which are not the start state and
 419 are not final (middle states).
 420 .LP
 421 .B GROUP 6: Priority Assignment
 422 .LP
 423 Priorities are assigned to names within transitions. Only priorities on the
 424 same name are allowed to interact. In the first form of priorities the name
 425 defaults to the name of the machine definition the priority is assigned in.
 426 Transitions do not have default priorities.
 427 .TP
 428 .I expr > int
 429 Assigns the priority int in all transitions entering into the machine.
 430 .TP
 431 .I expr @ int
 432 Assigns the priority int in all transitions that go into a final state.
 433 .TP
 434 .I expr $ int
 435 Assigns the priority int in all existing transitions.
 436 .TP
 437 .I expr % int
 438 Assigns the priority int in all pending out transitions.
 439 .LP
 440 A second form of priority assignment allows the programmer to specify the name
 441 to which the priority is assigned, allowing interactions to cross machine
 442 definition boundaries.
 443 .TP
 444 .I expr > (name,int)
 445 Assigns the priority int to name in all transitions entering into the machine.
 446 .TP
 447 .I expr @ (name, int)
 448 Assigns the priority int to name in all transitions that go into a final state.
 449 .TP
 450 .I expr $ (name, int)
 451 Assigns the priority int to name in all existing transitions.
 452 .TP
 453 .I expr % (name, int)
 454 Assigns the priority int to name in all pending out transitions.
 455 .LP
 456 .B GROUP 7:
 457 .TP
 458 .I expr *
 459 Produces the kleene star of a machine. Matches zero or more repetitions of the
 460 machine.
 461 .TP
 462 .I expr **
 463 Longest Matching Kleene Star. This version of kleene star puts a higher
 464 priority on staying in the machine over wrapping around and starting over. This
 465 operator is equivalent to ( ( expr ) $0 %1 )*.
 466 .TP
 467 .I expr ?
 468 Produces a machine that accepts the machine given or the null string. This operator
 469 is equivalent to  ( expr | '' ).
 470 .TP
 471 .I expr +
 472 Produces the machine concatenated with the kleen star of itself. Matches one or
 473 more repetitions of the machine.  This operator is equivalent to ( expr . expr* ).
 474 .TP
 475 .I expr {n}
 476 Produces a machine that matches exactly n repetitions of expr.
 477 .TP
 478 .I expr {,n}
 479 Produces a machine that matches anywhere from zero to n repetitions of expr.
 480 .TP
 481 .I expr {n,}
 482 Produces a machine that matches n or more repetitions of expr.
 483 .TP
 484 .I expr {n,m}
 485 Produces a machine that matches n to m repetitions of expr.
 486 .LP
 487 .B GROUP 8:
 488 .TP
 489 .I ! expr
 490 Produces a machine that matches any string not matched by the given machine.
 491 This operator is equivalent to ( *extend - expr ).
 492 .LP
 493 .B GROUP 9:
 494 .TP
 495 .I ( expr )
 496 Forces precedence on operators.
 497 .SH VALUES AVAILABLE IN CODE BLOCKS
 498 .TP
 499 .I fc
 500 The current character. Equivalent to *p.
 501 .TP
 502 .I fpc
 503 A pointer to the current character. Equivalent to p.
 504 .TP
 505 .I fcurs
 506 An integer value representing the current state.
 507 .TP
 508 .I ftargs
 509 An integer value representing the target state.
 510 .TP
 511 .I fentry(<label>)
 512 An integer value representing the entry point <label>.
 513 .SH STATEMENTS AVAILABLE IN CODE BLOCKS
 514 .TP
 515 .I fhold;
 516 Do not advance over the current character. Equivalent to --p;.
 517 .TP
 518 .I fexec <expr>;
 519 Sets the current character to something else. Equivalent to p = (<expr>)-1;
 520 .TP
 521 .I fgoto <label>;
 522 Jump to the machine defined by <label>.
 523 .TP
 524 .I fgoto *<expr>;
 525 Jump to the entry point given by <expr>. The expression must
 526 evaluate to an integer value representing a state.
 527 .TP
 528 .I fnext <label>;
 529 Set the next state to be the entry point defined by <label>.  The fnext
 530 statement does not immediately jump to the specified state. Any action code
 531 following the statement is executed.
 532 .TP
 533 .I fnext *<expr>;
 534 Set the next state to be the entry point given by <expr>. The expression must
 535 evaluate to an integer value representing a state.
 536 .TP
 537 .I fcall <label>;
 538 Call the machine defined by <label>. The next fret will jump to the
 539 target of the transition on which the action is invoked.
 540 .TP
 541 .I fcall *<expr>;
 542 Call the entry point given by <expr>. The next fret will jump to the target of
 543 the transition on which the action is invoked.
 544 .TP
 545 .I fret;
 546 Return to the target state of the transition on which the last fcall was made.
 547 .TP
 548 .I fbreak;
 549 Save the current state and immediately break out of the machine.
 550 .SH BUGS
 551 Ragel is still under development and has not yet matured. There are probably
 552 many bugs.
 553 .SH CREDITS
 554 Ragel was written by Adrian Thurston <thurston@cs.queensu.ca>.  Objective-C
 555 output contributed by Erich Ocean. D output contributed by Alan West.
 556 .SH "SEE ALSO"
 557 .BR rlgen-cd (1),
 558 .BR rlgen-dot (1),
 559 .BR rlgen-java (1),
 560 .BR re2c (1),
 561 .BR flex (1)
 562
 563 Homepage: http://www.cs.queensu.ca/~thurston/ragel/