RPA Toolkit
8ee0b54afa77494651c73903485fcec0b810cc9a
[rpatk.git] / rex / rexdb.h
1 /*
2  *  Regular Pattern Analyzer Toolkit (RPA/Tk)
3  *  Copyright (c) 2009-2012 Martin Stoilov
4  *
5  *  This program is free software: you can redistribute it and/or modify
6  *  it under the terms of the GNU General Public License as published by
7  *  the Free Software Foundation, either version 3 of the License, or
8  *  (at your option) any later version.
9  *
10  *  This program is distributed in the hope that it will be useful,
11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  *  GNU General Public License for more details.
14  *
15  *  You should have received a copy of the GNU General Public License
16  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
17  *
18  *  Martin Stoilov <martin@rpasearch.com>
19  */
20
21
22 /**
23  * @file rex/rexdb.h
24  * @brief Public interface for creating regular expressions.
25  *
26  *
27  * <h2>Synopsis</h2>
28  * The following APIs are used to create an automata object, based on regular expressions.
29  */
30
31 #ifndef _REXDB_H_
32 #define _REXDB_H_
33
34 #include "rtypes.h"
35 #include "rlib/robject.h"
36 #include "rlib/rarray.h"
37 #include "rex/rexstate.h"
38 #include "rex/rexdfa.h"
39
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 #define R_OBJECT_REXDB 35
46
47 /**
48  * @example js-tokenizer.c
49  * This is an example how to use rexdb_t and rexdfa_t
50  */
51
52 /**
53  * Define rexdb_t type. It could either REXDB_TYPE_NFA or REXDB_TYPE_DFA
54  */
55 typedef enum {
56         REXDB_TYPE_NFA = 0,                     /**< The automaton is NFA, empty transitions are allowed. */
57         REXDB_TYPE_DFA = 1,                     /**< The automaton is DFA, there are no empty transitions. */
58 } rexdb_type_t;
59
60 struct rexcompiler_s;
61
62 /**
63  * Define the rexdb_t type. This structure is used to create and manage the states
64  * of the finite automata (NFA or DFA depending on the type). If the automaton is DFA
65  * the sub-states member will contain information about the NFA states that produced
66  * this DFA.
67  */
68 typedef struct rexdb_s {
69         robject_t obj;                          /**< Base class */
70         rexdb_type_t type;                      /**< Automata type NFA or DFA */
71         struct rexcompiler_s *co;       /**< Pointer to a compiler object used for the parsing of regular expression string and turning it into NFA states. */
72         rarray_t *states;                       /**< Array holding all the states of the automata */
73         rarray_t *substates;            /**< Used only if the type is REXDB_TYPE_DFA. */
74         rexstate_t *start;
75 } rexdb_t;
76
77
78 /**
79  * Create a new empty object of type rexdb_t
80  *
81  * @param type This is REXDB_TYPE_NFA or REXDB_TYPE_DFA
82  * @return Empty automata object. You should never need
83  * to create an object of type REXDB_TYPE_DFA directly with
84  * this function, instead use @ref rex_db_createdfa.
85  *
86  */
87 rexdb_t *rex_db_create(rexdb_type_t type);
88
89 /**
90  * Create a new DFA object of type rexdb_t, constructed from the
91  * states of the NFA, passed as parameter.
92  *
93  * @param nfa This is REXDB_TYPE_NFA type automata object used to construct the DFA.
94  * @param start Start state of the NFA.
95  * @return DFA object.
96  */
97 rexdb_t *rex_db_createdfa(rexdb_t *nfa, unsigned long start);
98
99 /**
100  * This function is used to destroy @ref rexdb_t objects, created with
101  * @ref rex_db_create or @ref rex_db_createdfa.
102  */
103 void rex_db_destroy(rexdb_t *rexdb);
104
105 /**
106  * This function is use to add new regular expression to the NFA.
107  * All expression added with this create a union.
108  * @param nfa NFA object.
109  * @param prev This is the previous start state of the automata, returned from a previous call to this function.
110  *                              If this is the first call to this function prev is ignored.
111  * @param str UTF8 encoded regular expression string.
112  * @param size The size of the regular expression string.
113  * @param userdata The value of this parameter is stored in the accepting state of the NFA(which also becomes
114  * a sub-state in an accepting DFA state). You can use this value to identify which of the many regular expressions
115  * compiled into the automaton is actually matching. A DFA state can have multiple sub-states, this means it can have
116  * multiple accepting sub-states(multiple regular expressions matched). You can examine the values of the userdata
117  * for these states to find out which are the underlying regular expressions.
118  *
119  * @return New starting state for the automaton.
120  */
121 long rex_db_addexpression(rexdb_t *nfa, unsigned long prev, const char *str, unsigned int size, rexuserdata_t userdata);
122
123 /**
124  * This functions is the same as @ref rex_db_addexpression, but it assumes the str parameter is 0 terminated string.
125  */
126 long rex_db_addexpression_s(rexdb_t *nfa, unsigned long prev, const char *str, rexuserdata_t userdata);
127
128
129 robject_t *rex_db_init(robject_t *obj, unsigned int objtype, r_object_cleanupfun cleanup, rexdb_type_t type);
130 long rex_db_createstate(rexdb_t *rexdb, rex_statetype_t type);
131 long rex_db_insertstate(rexdb_t *rexdb, rexstate_t *s);
132 long rex_db_findstate(rexdb_t *rexdb, const rarray_t *subset);
133 rexstate_t *rex_db_getstate(rexdb_t *rexdb, long uid);
134 rexsubstate_t *rex_db_getsubstate(rexdb_t *rexdb, unsigned long uid);
135 rex_transition_t * rex_db_addrangetrasition(rexdb_t *rexdb, rexchar_t c1, rexchar_t c2, unsigned long srcuid, unsigned long dstuid);
136 rex_transition_t * rex_db_addtrasition_e(rexdb_t *rexdb, unsigned long srcuid, unsigned long dstuid);
137 void rex_db_dumpstate(rexdb_t *rexdb, unsigned long uid);
138 long rex_db_numtransitions(rexdb_t *rexdb);
139 long rex_db_numstates(rexdb_t *rexdb);
140 long rex_db_numsubstates(rexdb_t *rexdb);
141 long rex_db_numaccsubstates(rexdb_t *rexdb);
142 int rex_db_isempty(rexdb_t *db);
143 const char *rex_db_version();
144
145 /**
146  * @brief Convert @ref rexdb_t of type REXDB_TYPE_DFA to @ref rexdfa_t object.
147  *
148  * This function is used to generate rexdfa_t object from a rexdb_t. The rexdfa_t
149  * has a smaller memory footprint and is easier to use. Also, you have the option
150  * to eliminate the sub-states because they tend to take a lot of memory and are
151  * pretty much useless once the DFA is constructed.
152  *
153  * @param db Pointer to the rexdb_t DFA to be converted.
154  * @param withsubstates Supported values are:
155  *                      - 0 No sub-states information will be written.
156  *                      - 1 Sub-states information from the underlying NFA will be written.
157  *      @return Pointer to rexdfa_t object or NULL on error. If the functions succeeds, the return
158  *      object must be destroyed with @ref rex_dfa_destroy when not needed any more.
159  */
160 rexdfa_t *rex_db_todfa(rexdb_t *db, int withsubstates);
161
162
163 /*
164  * Virtual methods implementation
165  */
166 void rex_db_cleanup(robject_t *obj);
167
168
169 /**
170  * @example js-tokenizer.c
171  */
172
173
174 #ifdef __cplusplus
175 }
176 #endif
177 #endif