RPA Toolkit
Refined the rpastat_t public interface. Added more API documentation.
[rpatk.git] / rpa / rpastat.h
1 #ifndef _RPASTAT_H_
2 #define _RPASTAT_H_
3
4 #include "rtypes.h"
5 #include "rarray.h"
6 #include "rvmreg.h"
7 #include "rpadbex.h"
8
9 #define RPA_ENCODING_UTF8 0
10 #define RPA_ENCODING_BYTE 1
11 #define RPA_ENCODING_UTF16LE 2
12 #define RPA_ENCODING_ICASE (1 << 8)
13 #define RPA_ENCODING_ICASE_BYTE (RPA_ENCODING_BYTE | RPA_ENCODING_ICASE)
14 #define RPA_ENCODING_ICASE_UTF8 (RPA_ENCODING_UTF8 | RPA_ENCODING_ICASE)
15 #define RPA_ENCODING_ICASE_UTF16LE (RPA_ENCODING_UTF16LE | RPA_ENCODING_ICASE)
16 #define RPA_ENCODING_MASK ((1 << 8) - 1)
17 #define RPA_DEFAULT_STACKSIZE (256 * 1024)
18
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22
23 /**
24  * \file rpastat.h
25  * \brief The public interface to the execution context.
26  *
27  *
28  * <h2>Synopsis</h2>
29  * The following APIs are used to parse, match, scan an input stream, using an existing
30  * BNF productions database \ref rpadbex_t
31  */
32
33
34 /**
35  * \typedef rpastat_t
36  * \brief Execution context. If you need mutli-threading, multiple objects of this
37  * type must be created for every concurrent thread. All objects can be created/destroyed from the
38  * main thread. Only the execution functions: \ref rpa_stat_parse, \ref rpa_stat_match and
39  * \ref rpa_stat_scan have to be called from separate threads.
40  */
41 typedef struct rpastat_s rpastat_t;
42
43 /**
44  * \brief Create an object of type \ref rpastat_t.
45  *
46  * Multi-threading is supported by creating multiple \ref rpastat_t objects,
47  * referencing the same \ref rpadbex_t BNF productions database. Every thread
48  * must have its own \ref rpastat_t object, created with this function. This
49  * function can be called from the main thread multiple times to allocate the objects and
50  * then the returned pointer(s) passed to the child threads.
51  *
52  * If you don't need multi-threading, call this function and any one of the execution
53  * functions \ref rpa_stat_parse, \ref rpa_stat_match and \ref rpa_stat_scan from the
54  * main thread.
55  *
56  * The allocated \ref rpastat_t object must be destroyed with \ref rpa_stat_destroy.
57  *
58  * \param dbex BNF productions database created with \ref rpa_dbex_create.
59  * \param stacksize Execution stack size. The size is specified in byts.
60  * \return Returns a pointer to newly created \ref rpastat_t object or NULL if error occured.
61  */
62 rpastat_t *rpa_stat_create(rpadbex_t *dbex, rulong stacksize);
63
64
65 /**
66  * \brief Destroy an object of type \ref rpastat_t
67  *
68  * Destroy the object created with \ref rpa_stat_create. After calling this function
69  * the pointer is invalid and must never be used again.
70  *
71  * \param stat Pointer to object of type \ref rpastat_t.
72  */
73 void rpa_stat_destroy(rpastat_t *stat);
74
75
76 /**
77  * \brief Scan an input stream
78  *
79  * Scan the stream using the specified rule id.
80  * \param stat Pointer to object of type \ref rpastat_t
81  * \param rid Rule ID of the BNF root.
82  * \param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
83  * ignore the case of the parsed data use encodings with _ICASE_. Supported encodings are:
84  *              - RPA_ENCODING_UTF8
85  *              - RPA_ENCODING_UTF16LE
86  *              - RPA_ENCODING_BYTE
87  *              - RPA_ENCODING_ICASE_UTF8
88  *              - RPA_ENCODING_ICASE_UTF16LE
89  *              - RPA_ENCODING_ICASE_BYTE
90  * \param input The starting point of the operation. The input pointer must be: input >= start and input < end
91  * \param start The start of the buffer.
92  * \param end The end of the buffer, it should be: end = start + buffersize.
93  * \param where If this function returns a number greater than 0 (a match was found) this parameter will be
94  *                              initialized with a pointer the place in the buffer where the match was found.
95  * \return If successful return the size of the matched string in bytes, if no match was found
96  *                      return 0, return negative in case of error.
97  */
98 rlong rpa_stat_scan(rpastat_t *stat, rparule_t rid, ruint encoding, const rchar *input, const rchar *start, const rchar *end, const rchar **where);
99
100 /**
101  * \brief Parse an input stream
102  *
103  * Parse the stream using the specified rule id.
104  * \param stat Pointer to object of type \ref rpastat_t
105  * \param rid Rule ID of the BNF root.
106  * \param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
107  * ignore the case of the parsed data use encodings with _ICASE_. Supported encodings are:
108  *              - RPA_ENCODING_UTF8
109  *              - RPA_ENCODING_UTF16LE
110  *              - RPA_ENCODING_BYTE
111  *              - RPA_ENCODING_ICASE_UTF8
112  *              - RPA_ENCODING_ICASE_UTF16LE
113  *              - RPA_ENCODING_ICASE_BYTE
114  * \param input The starting point of the operation. The input pointer must be: input >= start and input < end
115  * \param start The start of the buffer.
116  * \param end The end of the buffer, it should be: end = start + buffersize.
117  * \param records If the function is successful this parameter will be used to
118  *                      store the AST records the parser generates. The records stored in the array
119  *                      are of type \ref rparecord_t
120  * \return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
121  *                      return 0, return negative in case of error.
122  */
123 rlong rpa_stat_parse(rpastat_t *stat, rparule_t rid, ruint encoding, const rchar *input, const rchar *start, const rchar *end, rarray_t *records);
124
125 /**
126  * \brief Match an input stream
127  *
128  * Match the stream using the specified rule id. This function is similar to /ref rpa_stat_parse, but it
129  * doesn't generate parsing records. It just returs the size of the matched input stream.
130  * \param stat Pointer to object of type \ref rpastat_t
131  * \param rid Rule ID of the BNF root.
132  * \param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
133  * ignore the case of the parsed data use encodings with _ICASE_. Supported encodings are:
134  *              - RPA_ENCODING_UTF8
135  *              - RPA_ENCODING_UTF16LE
136  *              - RPA_ENCODING_BYTE
137  *              - RPA_ENCODING_ICASE_UTF8
138  *              - RPA_ENCODING_ICASE_UTF16LE
139  *              - RPA_ENCODING_ICASE_BYTE
140  * \param input The starting point of the operation. The input pointer must be: input >= start and input < end
141  * \param start The start of the buffer.
142  * \param end The end of the buffer, it should be: end = start + buffersize.
143  * \return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
144  *                      return 0, return negative in case of error.
145  */
146 rlong rpa_stat_match(rpastat_t *stat, rparule_t rid, ruint encoding, const rchar *input, const rchar *start, const rchar *end);
147
148
149 /**
150  * \brief Execute the parser byte code to parse/match an input stream.
151  *
152  * This is a low level function used by \ref rpa_stat_parse \ref rpa_stat_match and \ref rpa_stat_scan. You shouldn't
153  * need to use it directly.
154  * \param stat Pointer to object of type \ref rpastat_t
155  * \param prog Byte code
156  * \param off Execution start point
157  * \param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
158  * ignore the case of the parsed data use encodings with _ICASE_. Supported encodings are:
159  *              - RPA_ENCODING_UTF8
160  *              - RPA_ENCODING_UTF16LE
161  *              - RPA_ENCODING_BYTE
162  *              - RPA_ENCODING_ICASE_UTF8
163  *              - RPA_ENCODING_ICASE_UTF16LE
164  *              - RPA_ENCODING_ICASE_BYTE
165  * \param input The starting point of the operation. The input pointer must be: input >= start and input < end
166  * \param start The start of the buffer.
167  * \param end The end of the buffer, it should be: end = start + buffersize.
168  * \param records If the function is successful this parameter will be used to
169  *                      store the AST records the parser generates. The records stored in the array
170  *                      are of type \ref rparecord_t
171  * \return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
172  *                      return 0, return negative in case of error.
173  */
174 rlong rpa_stat_exec(rpastat_t *stat, rvm_asmins_t *prog, rword off, ruint encoding, const rchar *input, const rchar *start, const rchar *end, rarray_t *records);
175
176
177 /**
178  * \brief Abort the current operation.
179  *
180  * Use this function to abort \ref rpa_stat_parse \ref rpa_stat_match and \ref rpa_stat_scan or \ref rpa_stat_exec
181  * \param stat Pointer to object of type \ref rpastat_t
182  * \return If sucessful return 0, otherwise return negative.
183  */
184 rint rpa_stat_abort(rpastat_t *stat);
185
186
187 /**
188  * \brief Return the error code of the last occurred error.
189  *
190  * \param stat Pointer to \ref rpastat_t object.
191  * \return The error code of the last occurred error. If this function fails the
192  * return value is negative.
193  */
194 rlong rpa_stat_lasterror(rpastat_t *stat);
195
196 /**
197  * \brief Get error information for the last occurred error.
198  *
199  * \param stat Pointer to \ref rpastat_t object.
200  * \param errinfo Pointer to \ref rpa_errinfo_t buffer that will be
201  * filled with the error information. This parameter cannot be NULL.
202  * \return Return 0 if the function is successful or negative otherwise. If this function fails the
203  * return value is negative.
204  */
205 rlong rpa_stat_lasterrorinfo(rpastat_t *stat, rpa_errinfo_t *errinfo);
206
207
208 #ifdef __cplusplus
209 }
210 #endif
211
212 #endif