%
-% Copyright 2001-2007 Adrian Thurston <thurston@cs.queensu.ca>
+% Copyright 2001-2009 Adrian Thurston <thurston@complang.org>
%
% This file is part of Ragel.
\usepackage{graphicx}
\usepackage{comment}
\usepackage{multicol}
+\usepackage[
+ colorlinks=true,
+ linkcolor=black,
+ citecolor=green,
+ filecolor=black,
+ urlcolor=black]{hyperref}
\topmargin -0.20in
\oddsidemargin 0in
%
\chapter*{License}
Ragel version \version, \pubdate\\
-Copyright \copyright\ 2003, 2004, 2005, 2006 Adrian Thurston
+Copyright \copyright\ 2003-2007 Adrian Thurston
\vspace{6mm}
{\bf\it\noindent This document is part of Ragel, and as such, this document is
\section{Abstract}
Regular expressions are used heavily in practice for the purpose of specifying
-parsers. However, they are normally used as black boxes linked together with
-program logic. User actions are executed in between invocations of the regular
+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 which allows user actions to be
+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 experssion. The single-expression model affords concise and elegant
+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 finite state machines from a high level regular language
-notation to executable C, C++, Objective-C or D.
+code. Ragel compiles executable finite state machines from a high level regular language
+notation. Ragel targets C, C++, Objective-C, D, Java and Ruby.
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 runs
-nearly as fast as manually constructed machines. Ragel can handle
-integer-sized alphabets and can compile very large state machines.
+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}
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 often meet the criteria for the
-regular languages. Tools for processing the context-free languages are viewed
-as too heavyweight for the purpose of parsing regular languages because the extra
-run-time effort required for supporting the recursive nature of context-free
-languages is wasted.
+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, then executes the associated user code. 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.
+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 exectution places severe restrictions on when
+expression matching and user code exectution places restrictions on when
action code may be executed. Since action code can only be associated with
-complete patterns, any action code which must be executed before an entire
+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 which move over the
+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
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 in support of the
-definition of entire parsers or large sections of parsers using a single
-regular expression that is compiled to a finite state machine. 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.
+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}
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, or D code. The output is
+Ragel outputs machines to C, C++, Objective-C, D, Java or Ruby 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
like a regular expression library. By embedding code into the regular language,
a Ragel machine can also be used to parse input.
-The Ragel input language has many operators for constructing and manipulating
+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.
+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, Subtraction, Concatenation and Kleene
+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 construction operator
+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
the programmer to specify the actions of the state machine.
Ragel attempts to make the action embedding facility as intuitive as possible.
-To do that, a number issues need to be addresses. For example, when making a
+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 in
+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 to a new
-transition that goes to a new state which is a combination of the original
+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
-which should be used instead of priority embeddings whenever possible.
+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 start transitions, finishing transitions, all transitions and pending out
-transitions. The embedding of pending out transitions is a special case.
+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 may be made going out of the machine by
-a concatenation or kleene star operator.
+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
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 which are exectued on all transitions which enter into a state, all
-transitions out of a state, transitions taken on the error event, or
-transitions taken on the EOF event.
+actions that are exectued 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 which are not regular. For example, one can parse balanced
-parentheses by calling into a parser when an open bracket character is seen and
-returning to the state on the top of the stack when the corresponding closing
-bracket 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 which 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.
+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
contained in a string to their corresponding numerical values.
Another drawback is the very issue that Ragel attempts to solve.
-It is not possbile to execute a user action while
+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
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. As Ragel stabilizes, which is expected in the 5.x line, the version
-numbering rules will become more strict and the documentation will become more
-plentiful.
-
+file.
\chapter{Constructing State Machines}
\section{Ragel State Machine Specifications}
-A Ragel input file consists of a host language code file with embedded machine
+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.
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 the write statements.
+causing any generated output by commenting out write statements.
-In Figure \ref{cmd-line-parsing}, a multi-line machine is used to define the
-machine and single line machines are used to trigger the writing of the machine
+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}
\label{cmd-line-parsing}
\end{figure}
-
\subsection{Naming Ragel Blocks}
\begin{verbatim}
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.
+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}
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.
-\subsection{Machine Definition}
-\label{definition}
+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}
-<name> = <expression>;
+import "inputfile.h";
\end{verbatim}
\verbspace
-The machine definition statement associates an FSM expression with a name. Machine
-expressions assigned to names can later be referenced by 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.
+The \verb|import| statement scrapes a file for sequences of tokens that match
+the following forms. Ragel treats these forms as state machine definitions.
-\subsection{Machine Instantiation}
-\label{instantiation}
+\begin{itemize}
+ \setlength{\itemsep}{-2mm}
+ \item \verb|name '=' number|
+ \item \verb|name '=' lit_string|
+ \item \verb|'define' name number|
+ \item \verb|'define' name lit_string|
+\end{itemize}
-\begin{verbatim}
-<name> := <expression>;
-\end{verbatim}
-\verbspace
+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.
-The machine instantiation statement generates a set of states representing an expression and
-associates a name with the entry point. Each instantiation generates a distinct
-set of states. At a very minimum the \verb|main| machine must be instantiated.
-Other machines may be instantiated and control passed to them by use of
-\verb|fcall|, \verb|fgoto| or \verb|fnext| statements.
+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 an FSM Specification}
+\section{Lexical Analysis of a Ragel Block}
\label{lexing}
-Within a machine specification the following lexical rules apply to the parse
-of the input.
+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. With them, the following escape sequences are interpreted:
+delimiters of literal strings. Within them, the following escape sequences
+are interpreted:
\verb| \0 \a \b \t \n \v \f \r|
\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 C/C++ comments and strings is done in order to
+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.
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
+\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|,
are the smallest unit to which machine construction and manipulation operators
can be applied.
-In the diagrams that follow the symbol \verb|df| represents
-the default transition, which is taken if no other transition can be taken. The
-symbol \verb|cr| represents the carriage return character, \verb|nl| represents the newline character (aka line feed) and the symbol
-\verb|sp| represents the space character.
-
\begin{itemize}
\item \verb|'hello'| -- Concatenation Literal. Produces a machine that matches
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{bmconcat}
+\includegraphics[scale=0.55]{bmconcat}
\end{center}
It is possible
\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 or expression supports character ranges
+\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 or expressions.
+in \verb|or| expressions.
% GENERATE: bmor
% OPT: -p
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{bmor}
+\includegraphics[scale=0.55]{bmor}
\end{center}
\item \verb|''|, \verb|""|, and \verb|[]| -- Zero Length Machine. Produces a machine
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{bmnull}
+\includegraphics[scale=0.55]{bmnull}
\end{center}
% FIXME: More on the range of values here.
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{bmnum}
+\includegraphics[scale=0.55]{bmnum}
\end{center}
\item \verb|/simple_regex/| -- Regular Expression. Regular expressions are
-parsed as a series of expressions that will be concatenated together. Each
+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|.|
+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
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]/|.
+result of compiling \verb|/ab*[c-z].*[123]/|. \verb|DEF| represents the default
+transition, which is taken if no other transition can be taken.
+
% GENERATE: bmregex
% OPT: -p
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{bmregex}
+\includegraphics[scale=0.55]{bmregex}
\end{center}
\item \verb|'a' .. 'z'| -- Range. Produces a machine that matches any
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{bmrange}
+\includegraphics[scale=0.55]{bmrange}
\end{center}
\label{machconst}
When using Ragel it is helpful to have a sense of how it constructs machines.
-Sometimes this the determinization process can cause results that appear unusual to someone
-unfamiliar with it. Ragel does not make use of any nondeterministic
-intermediate state machines. All operators accept and return deterministic
-machines. However, to ease the discussion, the operations are defined in terms
-epsilon transitions.
-
-To draw an epsilon transition between two states \verb|x| and \verb|y|, is to
+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., as well as its
+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 which goes to a new state that is the
+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 every time an epsilon transition
-is drawn the creation of new epsilon transitions may be triggered, the process
-of drawing epsilon transitions is repeated until there are no more epsilon
-transitions to be made.
+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 at once. That is, to create machines that have unintentional
-nondeterminism. This usually results from being unaware of the common strings
+too much. That is, to create machines that have unintentional
+nondetermistic 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
\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. 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 at the frontend. 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.
+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}
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exor}
+\includegraphics[scale=0.55]{exor}
\end{center}
\subsection{Intersection}
\verbspace
Intersection produces a machine that matches any
-string which is in both machine one and machine two. To achieve intersection, a
+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,
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exinter}
+\includegraphics[scale=0.55]{exinter}
\end{center}
\subsection{Difference}
\verbspace
The difference operation produces a machine that matches
-strings which are in machine one but which are not in machine two. To achieve subtraction,
+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
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exsubtr}
+\includegraphics[scale=0.55]{exsubtr}
\end{center}
\graphspace
\verbspace
Strong difference produces a machine that matches any string of the first
-machine which does not have any string of the second machine as a substring. In
+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
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exstrongsubtr}
+\includegraphics[scale=0.55]{exstrongsubtr}
\end{center}
\graphspace
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 loose their final state status, unless 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 the machines being concatenated together.
+operator between them results in concatenation.
\graphspace
\begin{center}
\graphspace
The opportunity for nondeterministic behaviour results from the possibility of
-the final states of the first machine accepting a string which is also accepted
+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 that this happens in is the
+The most common scenario in which this happens is the
concatenation of a machine that repeats some pattern with a machine that gives
-a termination string, but the repetition machine does not exclude the
-termination string. The example in Section \ref{strong_difference}
+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 exectued the thread of control will
+When executed the thread of control will
never leave the \verb|any*| machine. This is a problem especially if actions
-are embedded to processes the characters of the \verb|any*| component.
+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
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exconcat}
+\includegraphics[scale=0.55]{exconcat}
\end{center}
\graphspace
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. Precedence was given to the
-subtraction-based interpretation so as to adhere to the rule that the default
+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 -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.
+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}
by using the longest-match construction discussed in Section
\ref{generating-scanners} on scanners.
-In this simple
-example, there is no nondeterminism introduced by the exterior kleene star due
+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
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exstar}
+\includegraphics[scale=0.55]{exstar}
\end{center}
\graphspace
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*)|. The plus operator makes
-repetitions that cannot be zero length.
+operator is equivalent to \verb|(expr . expr*)|.
% GENERATE: explus
% OPT: -p
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{explus}
+\includegraphics[scale=0.55]{explus}
\end{center}
\graphspace
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
-extend a token.
+possibly extend a token.
% GENERATE: exoption
% OPT: -p
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exoption}
+\includegraphics[scale=0.55]{exoption}
\end{center}
\graphspace
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exnegate}
+\includegraphics[scale=0.55]{exnegate}
\end{center}
\graphspace
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)|.
+\verb|(any - expr)|. It must be applied only to machines that match strings of
+length one.
\section{State Machine Minimization}
$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
+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
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
-which can be used in the construction of other machines. Due to the
+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
+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 pending out transition} operator \verb|%| provides
-access to yet-unmade leaving transitions.
+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}
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.
+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|
\verbspace
-The entering operator embeds an action into the starting transitions. The
-action is executed on all transitions that enter into the machine from the
-start state. If the start state is a final state then it is possible for the
-machine to never be entered and the starting transitions bypassed. In the
-following example, the action is executed on the first transition of the
-machine. If the repetition machine is bypassed the action is not executed.
+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 exected once only.
\verbspace
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exstact}
+\includegraphics[scale=0.55]{exstact}
\end{center}
\graphspace
\verb|expr @ action|
\verbspace
-The finishing action operator embeds an action into any transitions that go into a
-final state. Whether or not the machine accepts is not determined at the point
-the action is executed. Further input may move the machine out of the accepting
-state, but keep it in the machine. As in the following example, the
-into-final-state operator is most often used when no lookahead is necessary.
+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
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exdoneact}
+\includegraphics[scale=0.55]{exdoneact}
\end{center}
\graphspace
% action A {}
\begin{inline_code}
\begin{verbatim}
-# Execute A on any characters of machine one or two.
+# Execute A on any characters of the machine.
main := ( 'm1' | 'm2' ) $A;
\end{verbatim}
\end{inline_code}
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exallact}
+\includegraphics[scale=0.55]{exallact}
\end{center}
\graphspace
-\subsection{Pending Out (Leaving) Actions}
+\subsection{Leaving Actions}
\label{out-actions}
\verb|expr % action|
\verbspace
-The pending out action operator embeds an action into the pending out
-transitions of a machine. The action is first embedded into the final states of
-the machine and later transferred to any transitions made going out of the
-machine. The transfer can be caused either by a concatenation or kleene star
-operation. This mechanism 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 by the newline character.
+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
% action A {}
\begin{inline_code}
\begin{verbatim}
-# Match a word followed by an newline. Execute A when
+# Match a word followed by a newline. Execute A when
# finishing the word.
main := ( lower+ %A ) . '\n';
\end{verbatim}
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exoutact1}
+\includegraphics[scale=0.55]{exoutact1}
\end{center}
\graphspace
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exoutact2}
+\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 accepts by moving into the
+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.
\graphspace
\begin{center}
-\includegraphics[scale=0.45]{exaction}
+\includegraphics[scale=0.55]{exaction}
\end{center}
\graphspace
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 partially related to
-the meanings of the symbols used by the transition embedding operators.
+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.
-The state embedding operators are different from the transition embedding
-operators in that there are various kinds of events that embedded actions can
-be associated with, requiring them to be distinguished by these different types
-of events. 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.
+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 kewords.
+
+\vspace{10pt}
\def\fakeitem{\hspace*{12pt}$\bullet$\hspace*{10pt}}
\begin{multicols}{2}
\raggedcolumns
\noindent The different classes of states are:\\
-\fakeitem \verb|> | -- the start state \\
+\fakeitem \verb|> | -- the start state\\
+\fakeitem \verb|< | -- any state except the start state\\
\fakeitem \verb|$ | -- all states\\
\fakeitem \verb|% | -- final states\\
-\fakeitem \verb|< | -- any state except the start state\\
\fakeitem \verb|@ | -- any state except final states\\
\fakeitem \verb|<>| -- any except start and final (middle)
\columnbreak
\noindent The different kinds of embeddings are:\\
-\fakeitem \verb|~| -- to-state actions\\
-\fakeitem \verb|*| -- from-state actions\\
-\fakeitem \verb|/| -- EOF actions\\
-\fakeitem \verb|!| -- error actions\\
-\fakeitem \verb|^| -- local error actions\\
+\fakeitem \verb|~| -- to-state actions (\verb|to|)\\
+\fakeitem \verb|*| -- from-state actions (\verb|from|)\\
+\fakeitem \verb|/| -- EOF actions (\verb|eof|)\\
+\fakeitem \verb|!| -- error actions (\verb|err|)\\
+\fakeitem \verb|^| -- local error actions (\verb|lerr|)\\
\end{multicols}
\end{minipage}
-%\label{state-act-embed}
-%\caption{The two components of state embedding operators. The class of states
-%to select comes first, followed by the type of embedding.}
-%
-%\begin{figure}[t]
-%\centering
-%\includegraphics{stembed}
-%\caption{Summary of state manipulation operators}
-%\label{state-act-embed-chart}
-%\end{figure}
-
-%\noindent Putting these two components together we get a matrix of state
-%embedding operators. The entire set is given in Figure \ref{state-act-embed-chart}.
-
\subsection{To-State and From-State Actions}
\subsubsection{To-State Actions}
-\verb| >~ $~ %~ <~ @~ <>~ |
-\verbspace
+\def\sasp{\hspace*{40pt}}
+
+\sasp\verb|>~action >to(name) >to{...} | -- the start state\\
+\sasp\verb|<~action <to(name) <to{...} | -- any state except the start state\\
+\sasp\verb|$~action $to(name) $to{...} | -- all states\\
+\sasp\verb|%~action %to(name) %to{...} | -- final states\\
+\sasp\verb|@~action @to(name) @to{...} | -- any state except final states\\
+\sasp\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
\subsubsection{From-State Actions}
-\verb| >* $* %* <* @* <>* |
-\verbspace
+\sasp\verb|>*action >from(name) >from{...} | -- the start state\\
+\sasp\verb|<*action <from(name) <from{...} | -- any state except the start state\\
+\sasp\verb|$*action $from(name) $from{...} | -- all states\\
+\sasp\verb|%*action %from(name) %from{...} | -- final states\\
+\sasp\verb|@*action @from(name) @from{...} | -- any state except final states\\
+\sasp\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
\subsection{EOF Actions}
-\verb| >/ $/ %/ </ @/ <>/ |
-\verbspace
+\sasp\verb|>/action >eof(name) >eof{...} | -- the start state\\
+\sasp\verb|</action <eof(name) <eof{...} | -- any state except the start state\\
+\sasp\verb|$/action $eof(name) $eof{...} | -- all states\\
+\sasp\verb|%/action %eof(name) %eof{...} | -- final states\\
+\sasp\verb|@/action @eof(name) @eof{...} | -- any state except final states\\
+\sasp\verb|<>/action <>eof(name) <>eof{...}| -- any except start and final (middle)
+\vspace{12pt}
-The EOF action embedding operators enable the user to embed EOF actions into
-different classes of
-states. EOF actions are stored in states and generated with the \verb|write eof|
-statement. The generated EOF code switches on the current state and executes the EOF
-actions associated with it.
+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}
-\verb| >! $! %! <! @! <>! |
-\verbspace
+\sasp\verb|>!action >err(name) >err{...} | -- the start state\\
+\sasp\verb|<!action <err(name) <err{...} | -- any state except the start state\\
+\sasp\verb|$!action $err(name) $err{...} | -- all states\\
+\sasp\verb|%!action %err(name) %err{...} | -- final states\\
+\sasp\verb|@!action @err(name) @err{...} | -- any state except final states\\
+\sasp\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 are stored in states until the final state machine has been fully
-constructed. They are then transferred to the transitions that move into the
-error state. This transfer entails the creation of a transition from the state
-to the error state that is taken on all input characters which are not already
-covered by the state's transitions. In other words it provides a default
-action. Error actions can induce a recovery by altering \verb|p| and then jumping back
-into the machine with \verb|fgoto|.
+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}
-\verb| >^ $^ %^ <^ @^ <>^ |
-\verbspace
+\sasp\verb|>^action >lerr(name) >lerr{...} | -- the start state\\
+\sasp\verb|<^action <lerr(name) <lerr{...} | -- any state except the start state\\
+\sasp\verb|$^action $lerr(name) $lerr{...} | -- all states\\
+\sasp\verb|%^action %lerr(name) %lerr{...} | -- final states\\
+\sasp\verb|@^action @lerr(name) @lerr{...} | -- any state except final states\\
+\sasp\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@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}
+% }%%
+% %% write data;
+% void f()
+% {
+% %% write init;
+% %% write exec;
+% }
+% END GENERATE
-Like global error actions, local error actions are also stored in states 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 actions embeddings associated the same name as the
-machine are transferred to error transitions. Local error actions can be used
-to specify an action to take when a particular section of a larger state
-machine fails to make a 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 where the
-transfer should happen. To embed local error actions and explicitly state the
-machine on which the transfer is to happen use \verb|(name, action)| as the
-action.
-\begin{comment}
-\begin{itemize}
-\setlength{\parskip}{0in}
-\item \verb|expr >^ (name, action) | -- Start state.
-\item \verb|expr $^ (name, action) | -- All states.
-\item \verb|expr %^ (name, action) | -- Final states.
-\item \verb|expr <^ (name, action) | -- Not start state.
-\item \verb|expr <>^ (name, action)| -- Not start and not final states.
-\end{itemize}
-\end{comment}
\section{Action Ordering and Duplicates}
-When building a parser by combining smaller expressions which themselves have
-embedded actions, it is often the case that transitions are made which need to
-execute a number of actions on one input character. For example when we leave
-an expression, we may execute the expression's pending out action and the
-subsequent expression's starting action on the same input character. We must
-therefore devise a method for ordering actions that is both intuitive and
-predictable for the user and repeatable by the state machine compiler. The
-determinization processes cannot simply order actions by the time at which they
-are introduced into a transition -- otherwise the programmer will be at the
-mercy of luck.
-
-We associate with the embedding of each action a distinct timestamp which is
+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
-compiled state machine. To accomplish this we traverse the parse tree of
-regular expressions and assign timestamps to action embeddings. This algorithm
-is recursive in nature and quite simple. When it visits a parse tree node it
-assigns timestamps to all {\em starting} action embeddings, recurses on the
-parse tree, then assigns timestamps to the remaining {\em all}, {\em
-finishing}, and {\em leaving} embeddings in the order in which they appear.
-
-Ragel does not permit actions (defined or unnamed) to appear multiple times in
-an action list. When the final machine has been created, actions which appear
-more than once in single transition 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 pending out actions from being transferred multiple times
-when a concatenation follows a kleene star and the two machines begin with a common
-character.
+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:
\verbspace
\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}
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| will be one of the possibly multiple states the
-label represents.
+it. The value returned by \verb|fentry| can be any one of the multiple states that
+it represents.
\end{itemize}
\noindent The following statements are available in code blocks:
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. In actions embedded into
-transitions, it is equivalent to the \verb|p--;| statement. In scanner pattern
-actions any changes made to \verb|p| are lost. In this context, \verb|fhold| is
-equivalent to \verb|tokend--;|.
+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,
+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.
-In scanner pattern actions any changes made to \verb|p| are lost. In this
-context, \verb|fexec| is equivalent to setting \verb|tokend| to the next
-character to process.
\item \verb|fgoto <label>;| -- Jump to an entry point defined by
\verb|<label>|. The \verb|fgoto| statement immediately transfers control to
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
\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 with \verb|fstack| in the struct block. Control is immediately
-transferred to the destination state.
-
-\item \verb|fbreak;| -- Save the current state 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 the end marker of the input
-buffer is arrived at, the fbreak statement can be used to stop processing input
-upon seeing some end-of-string marker. It can also be used for handling
-exceptional circumstances. The fbreak statement does not change the pointer to
-the current character. After an \verb|fbreak| call the \verb|p| variable will point to
-the character that was being traversed over when the action was
-executed. The current state will be the target of the current transition.
+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}
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 may be conditional and that the
+regular languages because transitions that the
machine construction operators are not aware of are introduced. These
commands should therefore be used with caution.
Along with the flexibility of arbitrary action embeddings comes a need to
control nondeterminism in regular expressions. If a regular expression is
-ambiguous, then sup-components of a parser other than the intended parts may become
-active. This means that actions which are irrelevant to the
+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 which are based on regular expression engines and which are used for
+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
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{lines1}
+\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
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{lines2}
+\includegraphics[scale=0.55]{lines2}
\end{center}
+\graphspace
Solving this kind of problem is straightforward when the ambiguity is created
-by strings which are a single character long. When the ambiguity is created by
-strings which are multiple characters long we have a more difficult problem.
+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.
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{comments1}
+\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
% }%%
% END GENERATE
+\graphspace
\begin{center}
-\includegraphics[scale=0.45]{comments2}
+\includegraphics[scale=0.55]{comments2}
\end{center}
+\graphspace
-
-We have phrased the problem of controlling non-determinism in terms of
-excluding strings common to two expressions which interact when combined.
+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
at a regular expression-based tokenizer that does not function correctly due to
unintended nondeterminism.
+\newpage
+
% GENERATE: smallscanner
% OPT: -p
% %%{
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{smallscanner}
+\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
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.
-\section{Priority Assignment}
-
-Priorities are integer values assigned to names within transitions.
-Only priorities with the same name are allowed to interact. When the machine
-construction process is combining transitions that have different priorities
-assiged to the same name, the transition with the higher priority is preserved
-and the lower priority is dropped.
-
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
\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 pending out transitions from final states 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 pending
-out priority.
+\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
\begin{itemize}
\setlength{\parskip}{0in}
-\item \verb|expr > (name, int)| -- Entering transitions.
-\item \verb|expr @ (name, int)| -- Transitions into final state.
+\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)| -- Pending out transitions.
+\item \verb|expr % (name, int)| -- Leaving transitions.
\end{itemize}
\section{Guarded Operators that Encapsulate Priorities}
-Priorities embeddings are a very expressive mechanism. At the same time they
+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 rather undesirable.
+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
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 which enter into a final state. The following
-example yields a machine identical to the example in Section \ref{priorities}
+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}
\end{verbatim}
\end{inline_code}
+\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
\verb|**| compound symbol. This
guarded operator embeds a high
priority into all transitions of the machine.
-A lower priority is then embedded into pending out transitions
-(in a manner similar to pending out action embeddings, described in Section
-\ref{out-actions}). When the kleene star operator makes the epsilon transitions from
-the final states into the start state, the lower priority will be transferred
+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.
In the next section we discuss the explicit specification of state machines
using state charts.
-\subsection{Entry-Guarded Contatenation}
+\subsection{Entry-Guarded Concatenation}
\verb|expr :> expr|
\verbspace
This operator concatenates two machines, but first assigns a low
priority to all transitions
-of the first machine and a high priority to the entering transitions of the
+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 start transitions of
+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 entering the second machine, where otherwise they would be
+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.
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{entryguard}
+\includegraphics[scale=0.55]{entryguard}
\end{center}
-
+\graphspace
Entry-guarded concatenation is equivalent to the following:
expr $(unique_name,0) . expr >(unique_name,1)
\end{verbatim}
-\subsection{Finish-Guarded Contatenation}
+\subsection{Finish-Guarded Concatenation}
\verb|expr :>> expr|
\verbspace
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{finguard}
+\includegraphics[scale=0.55]{finguard}
\end{center}
+\graphspace
-Finish-guarded concatenation is equivalent to the following:
+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.
\verbspace
\begin{verbatim}
% }%%
% END GENERATE
+\graphspace
\begin{center}
-\includegraphics[scale=0.45]{leftguard}
+\includegraphics[scale=0.55]{leftguard}
\end{center}
+\graphspace
Left-guarded concatenation is equivalent to the following:
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{lmkleene}
+\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
\end{verbatim}
\verbspace
-When the kleene star is applied, transitions are made out of the machine which
-go back into it. These are assigned a priority of zero by the pending out
-transition mechanism. This is less than the priority of the transitions out of
-the final states that do not leave the machine. When two transitions clash on
-the same character, the differing priorities causes the transition which
-stays in the machine to take precedence. The transition that wraps around is
-dropped.
+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 in the traditional
-sense use the Longest-Match machine construction described Section
+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 C and D 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}
+\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 Java and Ruby 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 Java and Ruby 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 Java and Ruby 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 Java and Ruby 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 Java and Ruby code. It
+must be an array containting 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 Java and
+Ruby 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}
\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. Supported alphabet types
-are \verb|char|, \verb|unsigned char|, \verb|short|, \verb|unsigned short|,
-\verb|int|, \verb|unsigned int|, \verb|long|, and \verb|unsigned long|.
-The default is \verb|char|.
+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 always \verb|char|.
+
+\begin{multicols}{2}
+\setlength{\columnseprule}{1pt}
+C/C++/Objective-C:
+\begin{verbatim}
+ char unsigned char
+ short unsigned short
+ int unsigned int
+ long unsigned long
+\end{verbatim}
+
+Java:
+\begin{verbatim}
+ char
+ byte
+ short
+ int
+\end{verbatim}
+
+
+\columnbreak
+
+D:
+\begin{verbatim}
+ char
+ byte ubyte
+ short ushort
+ wchar
+ int uint
+ dchar
+\end{verbatim}
+
+Ruby:
+\begin{verbatim}
+ char
+ int
+\end{verbatim}
+\end{multicols}
\section{Getkey Statement}
\end{verbatim}
\verbspace
-Specify to Ragel how to retrieve the character that the machine operates on
+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 and preclude optimization.
+large cost nor preclude optimization.
\section{Access Statement}
\end{verbatim}
\verbspace
-The access statement allows one to tell Ragel how the generated code should
+The access statement specifies how the generated code should
access the machine data that is persistent across processing buffer blocks.
-This includes all variables except \verb|p| and \verb|pe|. This includes
-\verb|cs|, \verb|top|, \verb|stack|, \verb|tokstart|, \verb|tokend| and \verb|act|.
-This is useful if a machine is to be encapsulated inside a
-structure in C code. The access statement can be used to give the name of
+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 Ruby and Java 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}
\end{verbatim}
\verbspace
-
The write statement is used to generate parts of the machine.
-There are four
-components that can be generated by a write statement. These components are the
-state machine's data, initialization code, execution code and EOF action
-execution code. A write statement may appear before a machine is fully defined.
+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 show in Figure \ref{fbreak-example}.
+it is used. An example of this is shown in Figure \ref{fbreak-example}.
\subsection{Write Data}
\begin{verbatim}
Data generation has several options:
\begin{itemize}
-\item \verb|noerror| - Do not generate the integer variable that gives the
+\setlength{\itemsep}{-2mm}
+\item \verb|noerror | - Do not generate the integer variable that gives the
id of the error state.
-\item \verb|nofinal| - Do not generate the integer variable that gives the
+\item \verb|nofinal | - Do not generate the integer variable that gives the
id of the first final state.
-\item \verb|noprefix| - Do not prefix the variable names with the name of the
+\item \verb|noprefix | - Do not prefix the variable names with the name of the
machine.
\end{itemize}
+\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}
+\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:
+
+\verbspace
+
+{
+\small
+\begin{verbatim}
+/* Did parsing succeed? */
+if ( cs < %%{ write first_final; }%% ) {
+ result = ERR_PARSE_ERROR;
+ goto fail;
+}
+\end{verbatim}
+}
+
+
\subsection{Write Init}
\begin{verbatim}
-write init;
+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 longest-match management variables, they are also
-initialized here.
+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}
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 excluded by specifying the \verb|noend| write option.
+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.
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.
-\begin{figure}
-\small
+\subsection{Write Exports}
+\label{export}
+
\begin{verbatim}
-#include <stdio.h>
-%% machine foo;
-int main( int argc, char **argv )
-{
- %% write data noerror nofinal;
- 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 exports;
\end{verbatim}
-\caption{Use of {\tt noend} write option and the {\tt fbreak} statement for
-processing a string.}
-\label{fbreak-example}
-\end{figure}
+\verbspace
+The export feature can be used to export simple machine definitions. Machine definitions
+are marked for export using the \verb|export| keyword.
-\subsection{Write EOF Actions}
+\verbspace
\begin{verbatim}
-write eof;
+export machine_to_export = 0x44;
\end{verbatim}
\verbspace
-The write EOF statement causes Ragel to emit code that executes EOF actions.
-This write statement is only relevant if EOF actions have been embedded,
-otherwise it does not generate anything. The EOF action code requires access to
-the current state.
+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 and Ruby. 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. This poses a problem for
-uses of Ragel where the input data arrives in blocks, such as over a socket or
-from a file. The program will error if a pointer is set in one buffer block but
-must be used while parsing a following buffer block.
+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|tokstart| at the same spot or ahead of it. When data is shifted in
+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.
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}
-\section{Running the Executables}
-
-Ragel is broken down into two executables: a frontend which compiles machines
-and emits them in an XML format, and a backend which generates code or a
-Graphviz Dot file from the XML data. The purpose of the XML-based intermediate
-format is to allow users to inspect their compiled state machines and to
-interface Ragel to other tools such as custom visualizers, code generators or
-analysis tools. The intermediate format will provide a better platform for
-extending Ragel to support new host languages. The split also serves to reduce
-complexity of the Ragel program by strictly separating the data structures and
-algorithms that are used to compile machines from those that are used to
-generate code.
+The \verb|ragel| program has a number of options for specifying the host
+language. The host-language options are:
-\verbspace
-\begin{verbatim}
-[user@host] myproj: ragel file.rl | rlcodegen -G2 -o file.c
-\end{verbatim}
+\begin{itemize}
+\item \verb|-C | for C/C++/Objective-C code (default)
+\item \verb|-D | for D code.
+\item \verb|-J | for Java code.
+\item \verb|-R | for Ruby code.
+\item \verb|-A | for C\# code.
+\end{itemize}
\section{Choosing a Generated Code Style}
\label{genout}
-The Ragel code generator is very flexible. Following the lead of Re2C, the
-generated code has no dependencies and can be inserted in any function, perhaps
-inside a loop if so 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. The user may break out of the processing loop
-and return to it at any time.
-
-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 which is able to reduce the
-burden on the host compiler by splitting large machines across multiple functions.
-
-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 which 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.
-Strategies for handling these scenarios are given in Ragel's manual.
-
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
\verbspace
\begin{center}
-\begin{tabular}{|c|c|}
+\begin{tabular}{|c|c|c|}
\hline
-\multicolumn{2}{|c|}{\bf Code Output Style Options} \\
+\multicolumn{3}{|c|}{\bf Code Output Style Options} \\
\hline
-\verb|-T0|&binary search table-driven\\
+\verb|-T0|&binary search table-driven&C/D/Java/Ruby/C\#\\
\hline
-\verb|-T1|&binary search, expanded actions\\
+\verb|-T1|&binary search, expanded actions&C/D/Ruby/C\#\\
\hline
-\verb|-F0|&flat table-driven\\
+\verb|-F0|&flat table-driven&C/D/Ruby/C\#\\
\hline
-\verb|-F1|&flat table, expanded actions\\
+\verb|-F1|&flat table, expanded actions&C/D/Ruby/C\#\\
\hline
-\verb|-G0|&goto-driven\\
+\verb|-G0|&goto-driven&C/D/C\#\\
\hline
-\verb|-G1|&goto, expanded actions\\
+\verb|-G1|&goto, expanded actions&C/D/C\#\\
\hline
-\verb|-G2|&goto, in-place actions\\
+\verb|-G2|&goto, in-place actions&C/D\\
\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. An
-example is given in Section \ref{examples}. 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 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 which compile to a large number of states
+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.
% GENERATE: call
% %%{
-% machine call;
+% machine call;
\begin{inline_code}
\begin{verbatim}
action return { fret; }
% %% write data;
% void f()
% {
-% %% write init;
-% %% write exec;
+% %% write init;
+% %% write exec;
% }
% END GENERATE
-Calling and jumping should be used carefully as they are operations which 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 modularization and reducing the number of states when the
-machine contains frequently recurring patterns.
+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 and
+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
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 not contained in a join,
-the search is rooted at the machine definition that that the epsilon transition or
+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.
\section{Scanners}
+\label{generating-scanners}
-Scanners are very much intertwinded with regular-languages and their
+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
+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
the user need not wait until the end of a pattern before user code can be
executed.
-Scanners can be used to processes sub-languages, as well as for tokenizing
+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 header field.
+the contents of a header field.
\begin{inline_code}
\begin{verbatim}
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 which enable it to backtrack and make
+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|tokstart|, \verb|tokend| and \verb|act|
-variables to be present so that it can backtrack and make pointers to the
+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|tokstart| variable must be defined as a pointer to the input data.
+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|tokstart| is set and if so, ensure that the data it points to is
+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|tokend| variable must also be defined as a pointer to the input data.
+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 act variable. In some cases use of the act
+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.
\setlength{\parskip}{0pt}
\item Read a block of input data.
\item Run the execute code.
-\item If \verb|tokstart| is set, the execute code will expect the incomplete
+\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|tokstart| and ending at \verb|pe| to the
+\item Shift the data beginning at \verb|ts| and ending at \verb|pe| to the
beginning of the input buffer.
-\item Reset \verb|tokstart| to the beginning of the buffer.
-\item Shift \verb|tokend| by the distance from the old value of \verb|tokstart|
-to the new value. The \verb|tokend| variable may or may not be valid. There is
+\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}
\begin{verbatim}
a) A stream "of characters" to be scanned.
| | |
- p tokstart pe
+ p ts pe
b) "of characters" to be scanned.
| | |
- tokstart p pe
+ ts p pe
\end{verbatim}
\caption{Following an invocation of the execute code there may be a partially
matched token (a). The data of the partially matched token
\label{preserve_example}
\end{figure}
-Since scanners attempt to make the longest possible match of input, in some
-cases they are not able to identify a token upon parsing its final character,
-they must wait for a lookahead character. For example if trying to match words,
-the token match must be triggered on following whitespace in case more
-characters of the word have yet to come. The user must therefore arrange for an
-EOF character to be sent to the scanner to flush out any token that has not yet
-been matched. The user can exclude a single character from the entire scanner
-and use this character as the EOF character, possibly specifying an EOF action.
-For most scanners, zero is a suitable choice for the EOF character.
-
-Alternatively, if whitespace is not significant and ignored by the scanner, the
-final real token can be flushed out by simply sending an additional whitespace
-character on the end of the stream. If the real stream ends with whitespace
-then it will simply be extended and ignored. If it does not, then the last real token is
-guaranteed to be flushed and the dummy EOF whitespace ignored.
+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}
cin.read( p, space );
int len = cin.gcount();
- /* If no data was read, send the EOF character.
+ char *pe = p + len;
+ char *eof = 0;
+
+ /* If no data was read indicate EOF. */
if ( len == 0 ) {
- p[0] = 0, len++;
+ eof = pe;
done = true;
}
- char *pe = p + len;
%% write exec;
- if ( cs == RagelScan_error ) {
+ if ( cs == Scanner_error ) {
/* Machine failed before finding a token. */
cerr << "PARSE ERROR" << endl;
exit(1);
}
- if ( tokstart == 0 )
+ if ( ts == 0 )
have = 0;
else {
/* There is a prefix to preserve, shift it over. */
- have = pe - tokstart;
- memmove( inbuf, tokstart, have );
- tokend = inbuf + (tokend-tokstart);
- tokstart = inbuf;
+ have = pe - ts;
+ memmove( inbuf, ts, have );
+ te = inbuf + (te-ts);
+ ts = inbuf;
}
}
\end{verbatim}
\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 wombines machines together without any
+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
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 the an
+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.
Attaches a label to an expression. Labels can be
used as the target of epsilon transitions and explicit control transfer
-statements such \verb|fgoto| and \verb|fnext| in action
+statements such as \verb|fgoto| and \verb|fnext| in action
code.
\subsection{Epsilon}
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 simplifly it in selective places using regular expressions.
+and simplify it in selective places using regular expressions.
-The state chart method of specifying parsers is a very common. It is an
+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
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-state machines can be given. These can encapsulate functionality
+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 loose
+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.
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 alway contain the characters \verb|]]| on the end.
+because the buffer will always contain the characters \verb|]]| on the end.
Instead, what we need is to delay the buffering of \hspace{0.25mm} \verb|]|
characters until a time when we
abandon the terminating sequence and go back into the main loop. There is no
% }%%
% END GENERATE
+\graphspace
\begin{center}
-\includegraphics[scale=0.45]{dropdown}
+\includegraphics[scale=0.55]{dropdown}
\end{center}
communication protocols motivated us to introduce semantic conditions into
the Ragel language.
-A semantic condition is a block of user code which is executed immediately
+A semantic condition is a block of user code that is executed immediately
before a transition is taken. If the code returns a value of true, the
-transition may be taken. We can now embed code which extracts the length of a
+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
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{conds1}
+\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 which tests
+compositional property of Ragel definitions. For example, a machine that tests
the length of a field using conditions can be unioned with another machine
-which accepts some of the same strings, without the two machines interfering with
-another. The user need not be concerned about whether or not the result of the
+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 which represents ``condition $c$ true''. Should
+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 has a transition on the same input character but
+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 which
+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 which represents ``condition $c$ false''. It
+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
% END GENERATE
\begin{center}
-\includegraphics[scale=0.45]{conds2}
+\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
next section we describe how Ragel accommodates several common parser
engineering problems.
+\vspace{10pt}
+
+\noindent {\large\bf Note:} 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.
-Pending out actions, which were described in Section \ref{out-actions}, can be
+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.
-
-\section{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 which 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. Error actions are embedded into an expression's states. When the
-final machine has been constructed and it is being made complete, error actions
-are transfered from their place of embedding within a state to the transitions
-which go to the error
-state. When the machine fails and is about to move into the error state, the
-current state's error actions get executed.
-
-Error actions can be used to simply report errors, or by jumping to a machine
-instantiation which consumes input, can attempt to recover from errors. Like
-the action embedding operators, there are several classes of states which
-error action embedding operators can access. For example, the \verb|@err|
-operator embeds an error action into non-final states. The \verb|$err| operator
-embeds an error action into all states. Other operators access the start state,
-final states, and states which are neither the start state nor are final. The
-design of the state selections was driven by a need to cover the states of an
-expression with a single error action.
-
-The following example uses error actions to report an error and jump to a
-machine which 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@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}
-% }%%
-% %% write data;
-% void f()
-% {
-% %% write init;
-% %% write exec;
-% }
-% END GENERATE
+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}
projects / external / ragel.git / blobdiff