Provided by: ragel_6.10-1build1_amd64 bug

NAME

       ragel - compile regular languages into executable state machines

SYNOPSIS

       ragel [options] file

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.

OPTIONS

       -h, -H, -?, --help
              Display help and exit.

       -v     Print version information and exit.

       -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.

       -s     Print some statistics on standard error.

       --error-format=gnu
              Print error messages using the format "file:line:column:" (default)

       --error-format=msvc
              Print error messages using the format "file(line,column):"

       -d     Do not remove duplicate actions from action lists.

       -I  dir
              Add dir to the list of directories to search for included and imported files

       -n     Do not perform state minimization.

       -m     Perform minimization once, at the end of the state machine compilation.

       -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.

       -e     Minimize after every operation.

       -x     Compile the state machines and emit an XML representation of the host data and the machines.

       -V     Generate a dot file for Graphviz.

       -p     Display printable characters on labels.

       -S <spec>
              FSM specification to output.

       -M <machine>
              Machine definition/instantiation to output.

       -C     The host language is C, C++, Obj-C or Obj-C++. This is the default host language option.

       -D     The host language is D.

       -J     The host language is Java.

       -Z     The host language is Go.

       -R     The host language is Ruby.

       -L     Inhibit writing of #line directives.

       -T0    (C/D/Java/Ruby/C#/Go)  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,
              indicies  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.

       -T1    (C/D/Ruby/C#/Go)  Generate  a  faster  table  driven  FSM  by expanding action lists in the action
              execute code.

       -F0    (C/D/Ruby/C#/Go) 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.

       -F1    (C/D/Ruby/C#/Go) Generate a faster flat table driven FSM by expanding action lists in  the  action
              execute code.

       -G0    (C/D/C#/Go)  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.

       -G1    (C/D/C#/Go)  Generate  a  faster  goto  driven FSM by expanding action lists in the action execute
              code.

       -G2    (C/D/Go) Generate a really fast goto driven FSM by embedding action lists  in  the  state  machine
              control code.

       -P<N>  (C/D) N-Way Split really fast goto-driven FSM.

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.

FSM STATEMENTS

       Machine Name:
              Set the the name of the machine. If given, it must be the first statement.

       Alphabet Type:
              Set the data type of the alphabet.

       GetKey:
              Specify how to retrieve the alphabet character from the element type.

       Include:
              Include a machine of same name as the current or of a different name in either the current file or
              some other file.

       Action Definition:
              Define an action that can be invoked by the FSM.

       Fsm Definition, Instantiation and Longest Match Instantiation:
              Used to build FSMs. Syntax description in next few sections.

       Access:
              Specify how to access the persistent state machine variables.

       Write: Write some component of the machine.

       Variable:
              Override the default variable names (p, pe, cs, act, etc).

BASIC MACHINES

       The basic machines are the base operands of the regular language expressions.

       '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.

       "hello"
              Identical to single quote version.

       [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.

       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.

       integer
              Makes a two state machine with one transition on the given integer number.

       hex    Makes a two state machine with one transition on the given hexidecimal number.

       /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.

       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.

       variable_name
              References the machine definition assigned to the variable name given.

       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:

              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 Hexidecimal digits /[0-9A-Fa-f]/.

              cntrl  Control characters 0..31.

              graph  Graphical characters /[!-~]/.

              print  Printable characters /[ -~]/.

              punct  Punctuation. Graphical characters that are not alpha-numerics /[!-/:-@\[-`{-~]/.

              space  Whitespace /[\t\v\f\n\r ]/.

              null   Zero length string. Equivalent to '', "" and [].

              empty  Empty set. Matches nothing.

BRIEF OPERATOR REFERENCE

       Operators are grouped by precedence, group 1 being the lowest and group 6 the highest.

       GROUP 1:

       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.

       GROUP 2:

       expr | expr
              Produces a machine that matches any string in machine one or machine two.

       expr & expr
              Produces a machine that matches any string that is in both machine one and machine two.

       expr - expr
              Produces a machine that matches any string that is in machine one but not in machine two.

       expr -- expr
              Strong Subtraction. Matches any string in machine one that does not have any string in machine two
              as a substring.

       GROUP 3:

       expr . expr
              Produces  a  machine  that  matches  all the strings in machine one followed by all the strings in
              machine two.

       expr :> expr
              Entry-Guarded Concatenation: terminates machine one upon entry to machine two.

       expr :>> expr
              Finish-Guarded Concatenation: terminates machine one when machine two finishes.

       expr <: expr
              Left-Guarded Concatenation: gives a higher priority to machine one.

       NOTE: Concatenation is the default operator. Two machines next to each other  with  no  operator  between
       them results in the concatenation operation.

       GROUP 4:

       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.

       GROUP 5:

       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.

       GROUP 6: Actions

       An action may be a name predefined with an action statement or may be specified directly with '{' and '}'
       in the expression.

       expr > action
              Embeds action into starting transitions.

       expr @ action
              Embeds action into transitions that go into a final state.

       expr $ action
              Embeds action into all transitions. Does not include pending out transitions.

       expr % action
              Embeds action into pending out transitions from final states.

       GROUP 6: EOF Actions

       When a machine's finish routine is called the current state's EOF actions are executed.

       expr >/ action
              Embed an EOF action into the start state.

       expr </ action
              Embed an EOF action into all states except the start state.

       expr $/ action
              Embed an EOF action into all states.

       expr %/ action
              Embed an EOF action into final states.

       expr @/ action
              Embed an EOF action into all states that are not final.

       expr <>/ action
              Embed an EOF action into all states that are not the start state and that are  not  final  (middle
              states).

       GROUP 6: Global Error Actions

       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.

       expr >! action
              Embed a global error action into the start state.

       expr <! action
              Embed a global error action into all states except the start state.

       expr $! action
              Embed a global error action into all states.

       expr %! action
              Embed a global error action into the final states.

       expr @! action
              Embed a global error action into all states which are not final.

       expr <>! action
              Embed a global error action into all states which are not  the  start  state  and  are  not  final
              (middle states).

       GROUP 6: Local Error Actions

       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.

       expr >^ action
              Embed a local error action into the start state.

       expr <^ action
              Embed a local error action into all states except the start state.

       expr $^ action
              Embed a local error action into all states.

       expr %^ action
              Embed a local error action into the final states.

       expr @^ action
              Embed a local error action into all states which are not final.

       expr <>^ action
              Embed a local error action into all states which are not the start state and are not final (middle
              states).

       GROUP 6: To-State Actions

       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.

       expr >~ action
              Embed a to-state action action into the start state.

       expr <~ action
              Embed a to-state action into all states except the start state.

       expr $~ action
              Embed a to-state action into all states.

       expr %~ action
              Embed a to-state action into the final states.

       expr @~ action
              Embed a to-state action into all states which are not final.

       expr <>~ action
              Embed  a  to-state  action into all states which are not the start state and are not final (middle
              states).

       GROUP 6: From-State Actions

       From state actions are executed whenever a state takes a transition on a character.   This  includes  the
       error transition and a transition to self.

       expr >* action
              Embed a from-state action into the start state.

       expr <* action
              Embed a from-state action into every state except the start state.

       expr $* action
              Embed a from-state action into all states.

       expr %* action
              Embed a from-state action into the final states.

       expr @* action
              Embed a from-state action into all states which are not final.

       expr <>* action
              Embed  a from-state action into all states which are not the start state and are not final (middle
              states).

       GROUP 6: Priority Assignment

       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.

       expr > int
              Assigns the priority int in all transitions leaving the start state.

       expr @ int
              Assigns the priority int in all transitions that go into a final state.

       expr $ int
              Assigns the priority int in all existing transitions.

       expr % int
              Assigns the priority int in all pending out transitions.

       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.

       expr > (name,int)
              Assigns the priority int to name in all transitions leaving the start state.

       expr @ (name, int)
              Assigns the priority int to name in all transitions that go into a final state.

       expr $ (name, int)
              Assigns the priority int to name in all existing transitions.

       expr % (name, int)
              Assigns the priority int to name in all pending out transitions.

       GROUP 7:

       expr * Produces the kleene star of a machine. Matches zero or more repetitions of the machine.

       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
              )*.

       expr ? Produces  a machine that accepts the machine given or the null string. This operator is equivalent
              to  ( expr | '' ).

       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* ).

       expr {n}
              Produces a machine that matches exactly n repetitions of expr.

       expr {,n}
              Produces a machine that matches anywhere from zero to n repetitions of expr.

       expr {n,}
              Produces a machine that matches n or more repetitions of expr.

       expr {n,m}
              Produces a machine that matches n to m repetitions of expr.

       GROUP 8:

       ! expr Produces  a  machine  that  matches any string not matched by the given machine.  This operator is
              equivalent to ( *extend - expr ).

       ^ expr Character-Level Negation. Matches any single character not matched by the single character machine
              expr.

       GROUP 9:

       ( expr )
              Forces precedence on operators.

VALUES AVAILABLE IN CODE BLOCKS

       fc     The current character. Equivalent to *p.

       fpc    A pointer to the current character. Equivalent to p.

       fcurs  An integer value representing the current state.

       ftargs An integer value representing the target state.

       fentry(<label>)
              An integer value representing the entry point <label>.

STATEMENTS AVAILABLE IN CODE BLOCKS

       fhold; Do not advance over the current character. Equivalent to --p;.

       fexec <expr>;
              Sets the current character to something else. Equivalent to p = (<expr>)-1;

       fgoto <label>;
              Jump to the machine defined by <label>.

       fgoto *<expr>;
              Jump  to  the  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>;
              Call the machine defined by <label>. The next fret will jump to the target of  the  transition  on
              which the action is invoked.

       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.

       fret;  Return to the target state of the transition on which the last fcall was made.

       fbreak;
              Save the current state and immediately break out of the machine.

CREDITS

       Ragel was written by Adrian Thurston <thurston@complang.org>.  Objective-C output  contributed  by  Erich
       Ocean.  D  output  contributed  by  Alan West. Ruby output contributed by Victor Hugo Borja. C Sharp code
       generation contributed by Daniel Tang. Contributions to Java code generation by Colin Fleming.   Go  code
       generation contributed by Justine Tunney.

SEE ALSO

       re2c(1), flex(1)

       Homepage: http://www.complang.org/ragel/