1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD 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 Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19  
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 /*
25  * Conversion parameters:
26  * inFile  = 
27  * outPack = glib
28  * outFile = MatchInfo
29  * strct   = GMatchInfo
30  * realStrct=
31  * ctorStrct=
32  * clss    = MatchInfo
33  * interf  = 
34  * class Code: No
35  * interface Code: No
36  * template for:
37  * extend  = 
38  * implements:
39  * prefixes:
40  * 	- g_match_info_
41  * omit structs:
42  * omit prefixes:
43  * omit code:
44  * omit signals:
45  * imports:
46  * 	- glib.Str
47  * 	- glib.ErrorG
48  * 	- glib.GException
49  * 	- glib.Regex
50  * structWrap:
51  * 	- GRegex* -> Regex
52  * module aliases:
53  * local aliases:
54  * overrides:
55  */
56 
57 module glib.MatchInfo;
58 
59 public  import gtkc.glibtypes;
60 
61 private import gtkc.glib;
62 private import glib.ConstructionException;
63 
64 
65 private import glib.Str;
66 private import glib.ErrorG;
67 private import glib.GException;
68 private import glib.Regex;
69 
70 
71 
72 
73 /**
74  * Description
75  * The g_regex_*() functions implement regular
76  * expression pattern matching using syntax and semantics similar to
77  * Perl regular expression.
78  * Some functions accept a start_position argument, setting it differs
79  * from just passing over a shortened string and setting G_REGEX_MATCH_NOTBOL
80  * in the case of a pattern that begins with any kind of lookbehind assertion.
81  * For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
82  * in the middle of words. ("\B" matches only if the current position in the
83  * subject is not a word boundary.) When applied to the string "Mississipi"
84  * from the fourth byte, namely "issipi", it does not match, because "\B" is
85  * always false at the start of the subject, which is deemed to be a word
86  * boundary. However, if the entire string is passed , but with
87  * start_position set to 4, it finds the second occurrence of "iss" because
88  * it is able to look behind the starting point to discover that it is
89  * preceded by a letter.
90  * Note that, unless you set the G_REGEX_RAW flag, all the strings passed
91  * to these functions must be encoded in UTF-8. The lengths and the positions
92  * inside the strings are in bytes and not in characters, so, for instance,
93  * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
94  * single character. If you set G_REGEX_RAW the strings can be non-valid
95  * UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
96  * bytes and two characters long.
97  * When matching a pattern, "\n" matches only against a "\n" character in
98  * the string, and "\r" matches only a "\r" character. To match any newline
99  * sequence use "\R". This particular group matches either the two-character
100  * sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
101  * U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
102  * CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
103  * separator, U+2028), or PS (paragraph separator, U+2029).
104  * The behaviour of the dot, circumflex, and dollar metacharacters are
105  * affected by newline characters, the default is to recognize any newline
106  * character (the same characters recognized by "\R"). This can be changed
107  * with G_REGEX_NEWLINE_CR, G_REGEX_NEWLINE_LF and G_REGEX_NEWLINE_CRLF
108  * compile options, and with G_REGEX_MATCH_NEWLINE_ANY,
109  * G_REGEX_MATCH_NEWLINE_CR, G_REGEX_MATCH_NEWLINE_LF and
110  * G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also
111  * relevant when compiling a pattern if G_REGEX_EXTENDED is set, and an
112  * unescaped "#" outside a character class is encountered. This indicates
113  * a comment that lasts until after the next newline.
114  * Creating and manipulating the same GRegex structure from different
115  * threads is not a problem as GRegex does not modify its internal
116  * state between creation and destruction, on the other hand GMatchInfo
117  * is not threadsafe.
118  * The regular expressions low-level functionalities are obtained through
119  * the excellent PCRE library
120  * written by Philip Hazel.
121  */
122 public class MatchInfo
123 {
124 	
125 	/** the main Gtk struct */
126 	protected GMatchInfo* gMatchInfo;
127 	
128 	
129 	public GMatchInfo* getMatchInfoStruct()
130 	{
131 		return gMatchInfo;
132 	}
133 	
134 	
135 	/** the main Gtk struct as a void* */
136 	protected void* getStruct()
137 	{
138 		return cast(void*)gMatchInfo;
139 	}
140 	
141 	/**
142 	 * Sets our main struct and passes it to the parent class
143 	 */
144 	public this (GMatchInfo* gMatchInfo)
145 	{
146 		this.gMatchInfo = gMatchInfo;
147 	}
148 	
149 	/**
150 	 */
151 	
152 	/**
153 	 * Returns GRegex object used in match_info. It belongs to Glib
154 	 * and must not be freed. Use g_regex_ref() if you need to keep it
155 	 * after you free match_info object.
156 	 * Since 2.14
157 	 * Returns: GRegex object used in match_info
158 	 */
159 	public Regex getRegex()
160 	{
161 		// GRegex * g_match_info_get_regex (const GMatchInfo *match_info);
162 		auto p = g_match_info_get_regex(gMatchInfo);
163 		
164 		if(p is null)
165 		{
166 			return null;
167 		}
168 		
169 		return new Regex(cast(GRegex*) p);
170 	}
171 	
172 	/**
173 	 * Returns the string searched with match_info. This is the
174 	 * string passed to g_regex_match() or g_regex_replace() so
175 	 * you may not free it before calling this function.
176 	 * Since 2.14
177 	 * Returns: the string searched with match_info
178 	 */
179 	public string getString()
180 	{
181 		// const gchar * g_match_info_get_string (const GMatchInfo *match_info);
182 		return Str.toString(g_match_info_get_string(gMatchInfo));
183 	}
184 	
185 	/**
186 	 * Frees all the memory associated with the GMatchInfo structure.
187 	 * Since 2.14
188 	 */
189 	public void free()
190 	{
191 		// void g_match_info_free (GMatchInfo *match_info);
192 		g_match_info_free(gMatchInfo);
193 	}
194 	
195 	/**
196 	 * Returns whether the previous match operation succeeded.
197 	 * Since 2.14
198 	 * Returns: TRUE if the previous match operation succeeded, FALSE otherwise
199 	 */
200 	public int matches()
201 	{
202 		// gboolean g_match_info_matches (const GMatchInfo *match_info);
203 		return g_match_info_matches(gMatchInfo);
204 	}
205 	
206 	/**
207 	 * Scans for the next match using the same parameters of the previous
208 	 * call to g_regex_match_full() or g_regex_match() that returned
209 	 * match_info.
210 	 * The match is done on the string passed to the match function, so you
211 	 * cannot free it before calling this function.
212 	 * Since 2.14
213 	 * Returns: TRUE is the string matched, FALSE otherwise
214 	 * Throws: GException on failure.
215 	 */
216 	public int next()
217 	{
218 		// gboolean g_match_info_next (GMatchInfo *match_info,  GError **error);
219 		GError* err = null;
220 		
221 		auto p = g_match_info_next(gMatchInfo, &err);
222 		
223 		if (err !is null)
224 		{
225 			throw new GException( new ErrorG(err) );
226 		}
227 		
228 		return p;
229 	}
230 	
231 	/**
232 	 * Retrieves the number of matched substrings (including substring 0,
233 	 * that is the whole matched text), so 1 is returned if the pattern
234 	 * has no substrings in it and 0 is returned if the match failed.
235 	 * If the last match was obtained using the DFA algorithm, that is
236 	 * using g_regex_match_all() or g_regex_match_all_full(), the retrieved
237 	 * count is not that of the number of capturing parentheses but that of
238 	 * the number of matched substrings.
239 	 * Since 2.14
240 	 * Returns: Number of matched substrings, or -1 if an error occurred
241 	 */
242 	public int getMatchCount()
243 	{
244 		// gint g_match_info_get_match_count (const GMatchInfo *match_info);
245 		return g_match_info_get_match_count(gMatchInfo);
246 	}
247 	
248 	/**
249 	 * Usually if the string passed to g_regex_match*() matches as far as
250 	 * it goes, but is too short to match the entire pattern, FALSE is
251 	 * returned. There are circumstances where it might be helpful to
252 	 * distinguish this case from other cases in which there is no match.
253 	 * Consider, for example, an application where a human is required to
254 	 * type in data for a field with specific formatting requirements. An
255 	 * example might be a date in the form ddmmmyy, defined by the pattern
256 	 * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
257 	 * If the application sees the user’s keystrokes one by one, and can
258 	 * check that what has been typed so far is potentially valid, it is
259 	 * able to raise an error as soon as a mistake is made.
260 	 * GRegex supports the concept of partial matching by means of the
261 	 * G_REGEX_MATCH_PARTIAL flag. When this is set the return code for
262 	 * g_regex_match() or g_regex_match_full() is, as usual, TRUE
263 	 * for a complete match, FALSE otherwise. But, when these functions
264 	 * return FALSE, you can check if the match was partial calling
265 	 * g_match_info_is_partial_match().
266 	 * When using partial matching you cannot use g_match_info_fetch*().
267 	 * Because of the way certain internal optimizations are implemented
268 	 * the partial matching algorithm cannot be used with all patterns.
269 	 * So repeated single characters such as "a{2,4}" and repeated single
270 	 * meta-sequences such as "\d+" are not permitted if the maximum number
271 	 * of occurrences is greater than one. Optional items such as "\d?"
272 	 * (where the maximum is one) are permitted. Quantifiers with any values
273 	 * are permitted after parentheses, so the invalid examples above can be
274 	 * coded thus "(a){2,4}" and "(\d)+". If G_REGEX_MATCH_PARTIAL is set
275 	 * for a pattern that does not conform to the restrictions, matching
276 	 * functions return an error.
277 	 * Since 2.14
278 	 * Returns: TRUE if the match was partial, FALSE otherwise
279 	 */
280 	public int isPartialMatch()
281 	{
282 		// gboolean g_match_info_is_partial_match (const GMatchInfo *match_info);
283 		return g_match_info_is_partial_match(gMatchInfo);
284 	}
285 	
286 	/**
287 	 * Returns a new string containing the text in string_to_expand with
288 	 * references and escape sequences expanded. References refer to the last
289 	 * match done with string against regex and have the same syntax used by
290 	 * g_regex_replace().
291 	 * The string_to_expand must be UTF-8 encoded even if G_REGEX_RAW was
292 	 * passed to g_regex_new().
293 	 * The backreferences are extracted from the string passed to the match
294 	 * function, so you cannot call this function after freeing the string.
295 	 * match_info may be NULL in which case string_to_expand must not
296 	 * contain references. For instance "foo\n" does not refer to an actual
297 	 * pattern and '\n' merely will be replaced with \n character,
298 	 * while to expand "\0" (whole match) one needs the result of a match.
299 	 * Use g_regex_check_replacement() to find out whether string_to_expand
300 	 * contains references.
301 	 * Since 2.14
302 	 * Params:
303 	 * stringToExpand = the string to expand
304 	 * Returns: the expanded string, or NULL if an error occurred. [allow-none]
305 	 * Throws: GException on failure.
306 	 */
307 	public string expandReferences(string stringToExpand)
308 	{
309 		// gchar * g_match_info_expand_references (const GMatchInfo *match_info,  const gchar *string_to_expand,  GError **error);
310 		GError* err = null;
311 		
312 		auto p = g_match_info_expand_references(gMatchInfo, Str.toStringz(stringToExpand), &err);
313 		
314 		if (err !is null)
315 		{
316 			throw new GException( new ErrorG(err) );
317 		}
318 		
319 		return Str.toString(p);
320 	}
321 	
322 	/**
323 	 * Retrieves the text matching the match_num'th capturing
324 	 * parentheses. 0 is the full text of the match, 1 is the first paren
325 	 * set, 2 the second, and so on.
326 	 * If match_num is a valid sub pattern but it didn't match anything
327 	 * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
328 	 * string is returned.
329 	 * If the match was obtained using the DFA algorithm, that is using
330 	 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
331 	 * string is not that of a set of parentheses but that of a matched
332 	 * substring. Substrings are matched in reverse order of length, so
333 	 * 0 is the longest match.
334 	 * The string is fetched from the string passed to the match function,
335 	 * so you cannot call this function after freeing the string.
336 	 * Since 2.14
337 	 * Params:
338 	 * matchNum = number of the sub expression
339 	 * Returns: The matched substring, or NULL if an error occurred. You have to free the string yourself. [allow-none]
340 	 */
341 	public string fetch(int matchNum)
342 	{
343 		// gchar * g_match_info_fetch (const GMatchInfo *match_info,  gint match_num);
344 		return Str.toString(g_match_info_fetch(gMatchInfo, matchNum));
345 	}
346 	
347 	/**
348 	 * Retrieves the position in bytes of the match_num'th capturing
349 	 * parentheses. 0 is the full text of the match, 1 is the first
350 	 * paren set, 2 the second, and so on.
351 	 * If match_num is a valid sub pattern but it didn't match anything
352 	 * (e.g. sub pattern 1, matching "b" against "(a)?b") then start_pos
353 	 * and end_pos are set to -1 and TRUE is returned.
354 	 * If the match was obtained using the DFA algorithm, that is using
355 	 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
356 	 * position is not that of a set of parentheses but that of a matched
357 	 * substring. Substrings are matched in reverse order of length, so
358 	 * 0 is the longest match.
359 	 * Since 2.14
360 	 * Params:
361 	 * matchNum = number of the sub expression
362 	 * startPos = pointer to location where to store
363 	 * the start position, or NULL. [out][allow-none]
364 	 * endPos = pointer to location where to store
365 	 * the end position, or NULL. [out][allow-none]
366 	 * Returns: TRUE if the position was fetched, FALSE otherwise. If the position cannot be fetched, start_pos and end_pos are left unchanged
367 	 */
368 	public int fetchPos(int matchNum, out int startPos, out int endPos)
369 	{
370 		// gboolean g_match_info_fetch_pos (const GMatchInfo *match_info,  gint match_num,  gint *start_pos,  gint *end_pos);
371 		return g_match_info_fetch_pos(gMatchInfo, matchNum, &startPos, &endPos);
372 	}
373 	
374 	/**
375 	 * Retrieves the text matching the capturing parentheses named name.
376 	 * If name is a valid sub pattern name but it didn't match anything
377 	 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
378 	 * then an empty string is returned.
379 	 * The string is fetched from the string passed to the match function,
380 	 * so you cannot call this function after freeing the string.
381 	 * Since 2.14
382 	 * Params:
383 	 * name = name of the subexpression
384 	 * Returns: The matched substring, or NULL if an error occurred. You have to free the string yourself. [allow-none]
385 	 */
386 	public string fetchNamed(string name)
387 	{
388 		// gchar * g_match_info_fetch_named (const GMatchInfo *match_info,  const gchar *name);
389 		return Str.toString(g_match_info_fetch_named(gMatchInfo, Str.toStringz(name)));
390 	}
391 	
392 	/**
393 	 * Retrieves the position in bytes of the capturing parentheses named name.
394 	 * If name is a valid sub pattern name but it didn't match anything
395 	 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
396 	 * then start_pos and end_pos are set to -1 and TRUE is returned.
397 	 * Since 2.14
398 	 * Params:
399 	 * name = name of the subexpression
400 	 * startPos = pointer to location where to store
401 	 * the start position, or NULL. [out][allow-none]
402 	 * endPos = pointer to location where to store
403 	 * the end position, or NULL. [out][allow-none]
404 	 * Returns: TRUE if the position was fetched, FALSE otherwise. If the position cannot be fetched, start_pos and end_pos are left unchanged.
405 	 */
406 	public int fetchNamedPos(string name, out int startPos, out int endPos)
407 	{
408 		// gboolean g_match_info_fetch_named_pos (const GMatchInfo *match_info,  const gchar *name,  gint *start_pos,  gint *end_pos);
409 		return g_match_info_fetch_named_pos(gMatchInfo, Str.toStringz(name), &startPos, &endPos);
410 	}
411 	
412 	/**
413 	 * Bundles up pointers to each of the matching substrings from a match
414 	 * and stores them in an array of gchar pointers. The first element in
415 	 * the returned array is the match number 0, i.e. the entire matched
416 	 * text.
417 	 * If a sub pattern didn't match anything (e.g. sub pattern 1, matching
418 	 * "b" against "(a)?b") then an empty string is inserted.
419 	 * If the last match was obtained using the DFA algorithm, that is using
420 	 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
421 	 * strings are not that matched by sets of parentheses but that of the
422 	 * matched substring. Substrings are matched in reverse order of length,
423 	 * so the first one is the longest match.
424 	 * The strings are fetched from the string passed to the match function,
425 	 * so you cannot call this function after freeing the string.
426 	 * Since 2.14
427 	 * Returns: a NULL-terminated array of gchar * pointers. It must be freed using g_strfreev(). If the previous match failed NULL is returned. [allow-none]
428 	 */
429 	public string[] fetchAll()
430 	{
431 		// gchar ** g_match_info_fetch_all (const GMatchInfo *match_info);
432 		return Str.toStringArray(g_match_info_fetch_all(gMatchInfo));
433 	}
434 }