5 Author: Tatu Ylonen <ylo@ngs.fi>
7 Copyright (c) 1991 Tatu Ylonen, Espoo, Finland
9 Permission to use, copy, modify, distribute, and sell this software
10 and its documentation is hereby granted without fee, provided that the
11 above copyright notice appears in all source code copies, the name of
12 Tatu Ylonen is not used to advertise products containing this software
13 or a derivation thereof, and all modified versions are clearly marked
16 This software is provided "as is" without express or implied warranty.
18 Created: Thu Sep 26 17:15:36 1991 ylo
19 Last modified: Fri Jan 3 12:05:45 1992 ylo
21 The SILC Regex API by Pekka Riikonen, under the same license as the original
26 /****h* silcutil/SILC Regular Expression Interface
30 * SILC regular expression interface provides Unix and POSIX compliant
31 * regular expression compilation and matching. The syntax is compliant
32 * with Unix and POSIX regular expression syntax.
34 * The interface also provides many convenience functions to make the use
35 * of regular expressions easier.
39 * SilcRegexStruct reg;
41 * // Compile regular expression
42 * if (!silc_regex_compile(®, "foo[0-9]*", 0))
45 * // Match string against the compiled regex
46 * if (!silc_regex_match(®, "foo20", 0, NULL, 0))
49 * // Free the compiled regular expression
50 * silc_regex_free(®);
57 /****s* silcutil/SilcRegexAPI/SilcRegex
61 * typedef struct { ... } *SilcRegex, SilcRegexStruct;
65 * The regular expression context. This context is given as argument
66 * to all silc_regex_* functions. It is usually statically allocated
67 * but can be dynamically allocated by silc_malloc.
70 typedef struct SilcRegexObject {
71 char *buffer; /* compiled pattern */
72 int allocated; /* allocated size of compiled pattern */
73 int used; /* actual length of compiled pattern */
74 char *fastmap; /* fastmap[ch] is true if ch can start pattern */
75 char *translate; /* translation to apply during comp/match */
76 char fastmap_accurate; /* true if fastmap is valid */
77 char can_be_null; /* true if can match empty string */
78 char uses_registers; /* registers used and need to be initialized */
79 char anchor; /* anchor: 0=none 1=begline 2=begbuf */
80 } *SilcRegex, SilcRegexStruct;
82 /****s* silcutil/SilcRegexAPI/SilcRegexMatch
86 * typedef struct { ... } *SilcRegexMatch, SilcRegexMatchStruct;
90 * The regular expression match context that provides information on the
91 * found match. It provides the start offset and end offset of the
96 typedef struct SilcRegexMatchObject {
97 int start; /* Start offset of region */
98 int end; /* End offset of region */
99 } *SilcRegexMatch, SilcRegexMatchStruct;
102 /****d* silcutil/SilcRegexAPI/SilcRegexFlags
106 * typedef enum { ... } SilcRegexFlags;
110 * Regular expression feature flags.
115 SILC_REGEX_FLAG_DEFAULT = 0,
119 /****f* silcutil/SilcRegexAPI/silc_regex_compile
123 * SilcBool silc_regex_compile(SilcRegex regexp, const char *regex,
124 * SilcRegexFlags flags);
128 * Compiles the regular expression string `regex'. The `regexp' is a
129 * pre-allocated regular expression context. The `flags' define
130 * various feature flags. This function must be called before the
131 * silc_regex_match can be used to find matches.
133 * Returns TRUE after the compilation is completed. Returns FALSE on
134 * error and sets silc_errno.
137 SilcBool silc_regex_compile(SilcRegex regexp, const char *regex,
138 SilcRegexFlags flags);
140 /****f* silcutil/SilcRegexAPI/silc_regex_compile
144 * SilcBool silc_regex_match(SilcRegex regexp, const char *string,
145 * SilcUInt32 string_len, SilcUInt32 num_match,
146 * SilcRegexMatch match, SilcRegexFlags flags);
150 * Finds one or more matches from the `string' using the pre-compiled
151 * regular expression `regexp'. It must be compiled by calling the
152 * silc_regex_compile before calling this function. The `flags' defines
153 * various feature flags.
155 * If only one match is needed the `num_match' may be set to 0 and the
156 * `match' is set to NULL. If multiple matches (substrings) are needed the
157 * `num_match' defines the size of the `match' array, where each of the
158 * matches (with parenthesized regular expression) will be stored. The
159 * `match' provides information on where the match was found in `string',
160 * providing the start offset and end offset of the match. Unused entires
161 * in the array will have -1 as the offset values.
163 * Returns TRUE if the string matched the regular expression or FALSE
164 * if it did not match or error occurred. The silc_errno will indicate
165 * the error. The silc_errno is set to SILC_ERR_NOT_FOUND if the regular
166 * expression did not match.
170 * // Find first match (check if string matches)
171 * if (!silc_regex_match(®, "foo20", 5, 0, NULL, 0))
174 * // Find multiple matches, one by one
175 * SilcRegexMatchStruct match;
177 * while (silc_regex_match(®, string, len, 1, &match, 0)) {
178 * match_string = silc_memdup(string + match.start,
179 * match.end - match.start);
180 * string += match.end;
183 * // Parse URI into its components, available in the match[] array
184 * SilcRegexStruct reg;
185 * SilcRegexMatchStruct match[7];
187 * silc_regex_compile(®, "^(([^:]+)://)?([^:/]+)(:([0-9]+))?(/.*)", 0);
188 * silc_regex_match(®, "http://example.com/page.html", len, 7, match, 0);
191 SilcBool silc_regex_match(SilcRegex regexp, const char *string,
192 SilcUInt32 string_len, SilcUInt32 num_match,
193 SilcRegexMatch match, SilcRegexFlags flags);
195 /****f* silcutil/SilcRegexAPI/silc_regex_free
199 * void silc_regex_free(SilcRegex regexp);
203 * Free's the compiled regular expression context `regexp'. This must
204 * be called even if `regexp' is statically allocated. If the
205 * silc_regex_compile has been called this function must be called.
208 void silc_regex_free(SilcRegex regexp);
210 /****f* silcutil/SilcRegexAPI/silc_regex
214 * SilcBool silc_regex(const char *string, const char *regex,
215 * SilcBuffer match, ...);
219 * Matches the `string' to the regular expression `regex'. Returns TRUE
220 * if the `string' matches the regular expression or FALSE if it does not
221 * match. The silc_errno is also set to SILC_ERR_NOT_FOUND.
223 * The first (whole) match is returned to `match' buffer if it is non-NULL.
224 * The variable argument list are buffers where multiple matches are
225 * returned in case of group (parenthesized) regular expression. The caller
226 * needs to know how many pointers to provide, in order to get all matches.
227 * If `match' is non-NULL the variable argument list must be ended with
228 * NULL. The data in the `match' and in any other buffer is from `string'
229 * and must not be freed by the caller.
234 * if (!silc_regex("foobar", "foo.", NULL))
237 * // Get the pointer to the first match
238 * if (!silc_regex("foobar", ".bar", &match, NULL))
242 * SilcBufferStruct match, sub1, sub2;
244 * if (!silc_regex("Hello World", "(H..).(o..)", &match, &sub1, &sub2, NULL))
248 SilcBool silc_regex(const char *string, const char *regex,
249 SilcBuffer match, ...);
251 /****f* silcutil/SilcRegexAPI/silc_regex_buffer
255 * SilcBool silc_regex_buffer(SilcBuffer buffer, const char *regex,
256 * SilcBuffer match, ...);
260 * Same as silc_regex but the string to match is in `buffer'. Returns
261 * TRUE if the string matches and FALSE if it doesn't. See examples and
262 * other information in silc_regex. The `buffer' and `match' may be the
266 SilcBool silc_regex_buffer(SilcBuffer buffer, const char *regex,
267 SilcBuffer match, ...);
269 /* Backwards support */
270 #define silc_string_regex_match(regex, string) silc_regex(string, regex, NULL)
272 #endif /* SILCREGEX_H */