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.
+state machine's data, initialization code, execution code, and exports.
+A write statement may appear before a machine is fully defined.
This allows one to write out the data first then later define the machine where
it is used. An example of this is shown in Figure \ref{fbreak-example}.
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 Init}
\begin{verbatim}
-write init;
+write init [options];
\end{verbatim}
\verbspace
The write exec statement causes Ragel to emit the state machine's execution code.
Ragel expects several variables to be available to this code. At a very minimum, the
generated code needs access to the current character position \verb|p|, the ending
-position \verb|pe| and the current state \verb|cs|, though \verb|pe|
-can be 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
-\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;
-}
-\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 Exports}
\label{export}
\section{Running the Executables}
-Ragel is broken down into two parts: a frontend that compiles machines
-and emits them in an XML format, and a backend that 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 split also serves to reduce the 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.
+Ragel is broken down into two parts: a frontend that compiles machines and
+emits them in an XML format, and a backend that generates code or a Graphviz
+Dot file from the XML data. The \verb|ragel| program normally manages the
+execution of the backend program to generate code. However, if the intermediate
+file format is needed, it can emitted with the \verb|-f| option to the
+\verb|ragel| program.
+
+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 split also serves to
+reduce the 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.
\vspace{10pt}
-\noindent The frontend program is called \verb|ragel|. It takes as an argument the host
-language. This can be:
+\noindent The frontend program \verb|ragel| takes as an argument the host
+language, compiles the state machine, then calls the appropriate backend program
+for code generation. The host language options are:
\begin{itemize}
\item \verb|-C | for C/C++/Objective-C code (default)
\item \verb|rlgen-dot | generate a Graphviz Dot file.
\end{itemize}
-\section{Choosing a Generated Code Style (C/D only)}
+\section{Choosing a Generated Code Style (C/D/Java only)}
\label{genout}
There are three styles of code output to choose from. Code style affects the