RPA Toolkit
Work on REX documentation.
[rpatk.git] / rex / doc / rex_main.txt
1 /** \page rex_main "Regular Expressions Library (REX)"
2 REX is Automata Compiler - it turns regular expressions into Automaton (NFA or DFA).
3 REX does not support back references. REX doesn't support anchors directly, but the support can be added externally.
4 The REX library is based on the theory of Deterministic Finite Automata (DFA).
5 Regular expressions like '[a-zA-Z_][a-zA-Z0-9_]*' are first compiled to
6 Non-deterministic Finite Automata(NFA) and then transformed to DFA, using
7 algorithm similar to the DFA subset construction method. 
8
9 \section features Features
10 - Regular expressions based on Automata theory
11
12 - Support for wide characters. By default 32-bit, but it could be redefined at compile time to 64-bit or any other integral size.
13
14 \section usage How to use.
15 To implement matching using REX, the user has to run the input through the DFA states until the automaton
16 arrives at accepting state. For example, if the input is a string:
17 @code
18 nstate = REX_DFA_STARTSTATE;
19 while (*str) {
20     nstate = REX_DFA_NEXT(dfa, nstate, *str);
21     if (REX_DFA_STATE(dfa, nstate)->type == REX_STATETYPE_DEAD) {
22         /* Did not match */
23         break;
24     } else if (REX_DFA_STATE(dfa, nstate)->type == REX_STATETYPE_ACCEPT) {
25         /* The DFA is in accepting state, lets find out what exactly is being accepted. */
26  
27         ++str;      
28         break;
29     } else {
30         /* Keep going... */
31         ++str;
32     }
33 }
34 @endcode
35
36 REX doesn't provide API for matching or searching directly, it is up to the user to decide how to
37 implement whatever functionality they need using the automaton.
38
39 The JavaScript tokenizer example @ref js-tokenizer.c is a simple demonstration how to use the REX library for lexical analysis of UTF8 encoded text.
40
41 */