Skip to content

Commit

Permalink
some docs improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
Adrian Thurston committed Feb 8, 2016
1 parent 662617b commit 15676b4
Show file tree
Hide file tree
Showing 4 changed files with 90 additions and 48 deletions.
27 changes: 20 additions & 7 deletions README
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,31 @@
Ragel State Machine Compiler -- README
======================================

Building Ragel
--------------
REQUIRED DEPENDENCIES
---------------------

To build ragel you need these dependencies
Colm is a mandatory dependency.

http://www.colm.net/files/colm/colm-0.13.0.3.tar.gz

Either install this to your path or configure the location using
--with-colm=DEST and pass it the prefix colm was installed to.

OPTIONAL DEPENDENCIES
---------------------

Get these if you want to build ragel with the original parser (as it exists in
ragel 6).

http://www.colm.net/files/ragel/ragel-6.9.tar.gz
http://www.colm.net/files/kelbt/kelbt-0.16.tar.gz
http://www.colm.net/files/colm/colm-0.13.0.2.tar.gz

Install them to your path, or configure ragel with:

--with-{ragel,kelbt,colm}=DEST
--with-{ragel,kelbt}=DEST

To build the user guide, pass "--enable-manual=yes" to the configure script.
You will need the following programs.

To build the user guide pass "--enable-manual=yes" to the configure script. You
will need the following extra programs:
* asciidoc
* fig2dev
2 changes: 0 additions & 2 deletions doc/ragel-guide.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,6 @@ \section{Abstract}
maximally continuous. One is free to specify an entire parser using a single
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 executable finite state machines from a high level regular language
notation. Ragel targets C, C++, Objective-C, D, Go, Java, Ruby and OCaml.

In addition to building state machines from regular expressions, Ragel allows
the programmer to directly specify state machines with state charts. These two
Expand Down
28 changes: 15 additions & 13 deletions doc/ragel-guide.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,23 +25,24 @@ Ragel Version 7.0

=== Abstract

Regular expressions are used heavily for the purpose of specifying parsers.
They are normally treated as black boxes, linked together with program logic.
User code is executed in between invocations of the regular expression engine.
Adding cdoe before a pattern terminates requires patterns to be broken and
pasted back together with program logic. The more inline user code is needed,
the less the advantages of regular expressions are seen.
In today's computing landscape, regular expressions are used heavily for the
purpose of specifying parsers. They are normally treated as black boxes, linked
together with program logic. User code is executed in between invocations of
the regular expression engine. To add code before a pattern terminates, the
programmer is required to break patterns and paste them back together with
program logic. The more inline code needed, the less the advantages of regular
expressions are seen.

Ragel is a software development tool that allows user code to be embedded into
the transitions of a regular expression's corresponding state machine,
eliminating the need to switch from the regular expression engine to the user
code execution environment, and then back again. As a result, expressions can
be maximally continuous. One is free to specify an entire parser using a
single 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 executable finite state machines from a high level
regular language notation. Ragel targets C, C++, Objective-C, D, Go, Java, Ruby
and OCaml.
be maximally continuous. One is free to specify an entire parser using a single
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 executable finite state machines from a high level regular
language notation. Ragel targets C, C++, Objective-C, D, Go, GNU ASM x86-64,
Java, Ruby, C#, OCaml, Crack, Rust, Julia and Javascript

In addition to building state machines from regular expressions, Ragel allows
the programmer to directly specify state machines with state charts. These two
Expand Down Expand Up @@ -106,7 +107,8 @@ deterministic finite state automaton. Since every regular language has a state
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, D, Go, Java, Ruby or OCaml code. The output is
Ragel outputs machines to C, C++, Objective-C, D, Go, GNU ASM x86-64, Java,
Ruby, C#, OCaml, Crack, Rust, Julia or Javascript 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
Expand Down
81 changes: 55 additions & 26 deletions src/main.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,11 +76,13 @@ void usage()
" -h, -H, -?, --help Print this usage and exit\n"
" -v, --version Print version information and exit\n"
" -o <file> Write output to <file>\n"
" -s Print some statistics on stderr\n"
" -s Print some statistics and compilation info to stderr\n"
" -d Do not remove duplicates from action lists\n"
" -I <dir> Add <dir> to the list of directories to search\n"
" for included an imported files\n"
" --rlhc display rlhc command\n"
" --rlhc Show the rlhc command used to compile\n"
" --save-temps Do not delete intermediate file during compilation\n"
" --no-intermediate Disable call to rlhc, leave behind intermediate\n"
"error reporting format:\n"
" --error-format=gnu file:line:column: message (default)\n"
" --error-format=msvc file(line,column): message\n"
Expand All @@ -94,29 +96,23 @@ void usage()
" -V Generate a dot file for Graphviz\n"
" -p Display printable characters on labels\n"
" -S <spec> FSM specification to output (for graphviz output)\n"
" -M <machine> Machine definition/instantiation to output (for graphviz output)\n"
" -M <machine> Machine definition/instantiation to output (for\n"
" graphviz output)\n"
"host language:\n"
" -C The host language is C, C++, Obj-C or Obj-C++ (default)\n"
" All code styles supported.\n"
" --gas-x86-64-sys-v The host language is GNU AS, x86_64, System V ABI\n"
" ASM uses a single code style equiv to -G2\n"
" --asm Short version of --gas-x86-64-sys-v\n"
" -D The host language is D\n"
" All code styles supported.\n"
" -Z The host language is Go\n"
" All code styles supported.\n"
" -J The host language is Java\n"
" -T0 code style supported\n"
" -R The host language is Ruby\n"
" -T0 code style supported\n"
" -A The host language is C#\n"
" -T0 -T1 -F0 -F1 -G0 -G1 code styles supported\n"
" -O The host language is OCaml\n"
" -T0 code style supported\n"
" -K The host language is Crack\n"
" -T0 code style supported\n"
" -P The host language is JavaScript\n"
" -T0 code style supported\n"
" -C C, C++, Obj-C or Obj-C++ (default)\n"
" All code styles supported.\n"
" --gas-x86-64-sys-v GNU AS, x86_64, System V ABI\n"
" --asm ASM is generated in a code style equiv to -G2\n"
" -D D All code styles supported\n"
" -Z Go All code styles supported\n"
" -J Java -T0\n"
" -R Ruby -T0\n"
" -A C# -T0 -T1 -F0 -F1 -G0 -G1\n"
" -O OCaml -T0 code style supported\n"
" -U Rust -T0 -T1 -F0 -F1 -G0 -G1\n"
" -Y Julia -T0 -T1 -F0 -F1\n"
" -K Crack -T0\n"
" -P JavaScript -T0\n"
"line directives:\n"
" -L Inhibit writing of #line directives\n"
"code style:\n"
Expand All @@ -127,6 +123,39 @@ void usage()
" -G0 Switch-driven\n"
" -G1 Switch-driven with expanded actions\n"
" -G2 Goto-driven with expanded actions\n"
"large machines:\n"
" --integral-tables Use integers for table data (default)\n"
" --string-tables Encode table data into strings for faster host lang\n"
" compilation\n"
"nfa-analysis (large machines):\n"
" --nfa-conds-depth Search for high-cost conditions inside a prefix\n"
" of the machine.\n"
" --nfa-term-check Search for condition-based general repetitions\n"
" that will not function properly and must be nfa\n"
" reps.\n"
" --nfa-intermed-state-limit Report fail if number of states exceeds this\n"
" during compilation.\n"
" --nfa-final-state-limit Report a fail if number states in final machine\n"
" exceeds this.\n"
" --nfa-breadth-check Report breadth cost of named entry points (and\n"
" start).\n"
" --input-histogram Input char histogram for breadth check. If\n"
" unspecified a flat histogram is used.\n"
"testing:\n"
" --kelbt-frontend Compile using original ragel + kelbt frontend\n"
" Requires ragel be built with ragel + kelbt support\n"
" --colm-frontend Compile using a colm-based recursive descent\n"
" frontend\n"
" --reduce-frontend Compile using a colm-based reducer (default)\n"
" --direct-backend Use the direct backend for supported langs (default)\n"
" --colm-backend Use the translation backed for C\n"
" --var-backend Use the variable-based backend for langs that\n"
" support goto-based\n"
" --goto-backend Use the goto-based backend for supported langs\n"
" (default)\n"
" --supported-host-langs Show supported host languages by command line arg\n"
" --supported-frontends Show supported frontends\n"
" --supported-backends Show supported backends\n"
;

exit( 0 );
Expand Down Expand Up @@ -165,9 +194,9 @@ void showHostLangArgs()
void showFrontends()
{
cout << "--colm-frontend";
cout << "--reduce-frontend";
cout << " --reduce-frontend";
#ifdef WITH_RAGEL_KELBT
cout << "--kelbt-frontend";
cout << " --kelbt-frontend";
#endif
cout << endl;
exit(0);
Expand Down

0 comments on commit 15676b4

Please sign in to comment.