]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | Copyright 2006-2007 John Maddock. | |
3 | Distributed under the Boost Software License, Version 1.0. | |
4 | (See accompanying file LICENSE_1_0.txt or copy at | |
5 | http://www.boost.org/LICENSE_1_0.txt). | |
6 | ] | |
7 | ||
8 | ||
9 | [section:old_regex High Level Class RegEx (Deprecated)] | |
10 | ||
11 | The high level wrapper class RegEx is now deprecated and does not form | |
12 | part of the regular expression standardization proposal. This type still | |
13 | exists, and existing code will continue to compile, however the following | |
14 | documentation is unlikely to be further updated. | |
15 | ||
16 | #include <boost/cregex.hpp> | |
17 | ||
18 | The class RegEx provides a high level simplified interface to the regular | |
19 | expression library, this class only handles narrow character strings, and | |
20 | regular expressions always follow the "normal" syntax - that is the | |
21 | same as the perl / ECMAScript syntax. | |
22 | ||
23 | typedef bool (*GrepCallback)(const RegEx& expression); | |
24 | typedef bool (*GrepFileCallback)(const char* file, const RegEx& expression); | |
25 | typedef bool (*FindFilesCallback)(const char* file); | |
26 | ||
27 | class RegEx | |
28 | { | |
29 | public: | |
30 | RegEx(); | |
31 | RegEx(const RegEx& o); | |
32 | ~RegEx(); | |
33 | RegEx(const char* c, bool icase = false); | |
34 | explicit RegEx(const std::string& s, bool icase = false); | |
35 | RegEx& operator=(const RegEx& o); | |
36 | RegEx& operator=(const char* p); | |
37 | RegEx& operator=(const std::string& s); | |
38 | unsigned int SetExpression(const char* p, bool icase = false); | |
39 | unsigned int SetExpression(const std::string& s, bool icase = false); | |
40 | std::string Expression()const; | |
41 | // | |
42 | // now matching operators: | |
43 | // | |
44 | bool Match(const char* p, boost::match_flag_type flags = match_default); | |
45 | bool Match(const std::string& s, boost::match_flag_type flags = match_default); | |
46 | bool Search(const char* p, boost::match_flag_type flags = match_default); | |
47 | bool Search(const std::string& s, boost::match_flag_type flags = match_default); | |
48 | unsigned int Grep(GrepCallback cb, const char* p, | |
49 | boost::match_flag_type flags = match_default); | |
50 | unsigned int Grep(GrepCallback cb, const std::string& s, | |
51 | boost::match_flag_type flags = match_default); | |
52 | unsigned int Grep(std::vector<std::string>& v, const char* p, | |
53 | boost::match_flag_type flags = match_default); | |
54 | unsigned int Grep(std::vector<std::string>& v, const std::string& s, | |
55 | boost::match_flag_type flags = match_default); | |
56 | unsigned int Grep(std::vector<unsigned int>& v, const char* p, | |
57 | boost::match_flag_type flags = match_default); | |
58 | unsigned int Grep(std::vector<unsigned int>& v, const std::string& s, | |
59 | boost::match_flag_type flags = match_default); | |
60 | unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false, | |
61 | boost::match_flag_type flags = match_default); | |
62 | unsigned int GrepFiles(GrepFileCallback cb, const std::string& files, | |
63 | bool recurse = false, | |
64 | boost::match_flag_type flags = match_default); | |
65 | unsigned int FindFiles(FindFilesCallback cb, const char* files, | |
66 | bool recurse = false, | |
67 | boost::match_flag_type flags = match_default); | |
68 | unsigned int FindFiles(FindFilesCallback cb, const std::string& files, | |
69 | bool recurse = false, | |
70 | boost::match_flag_type flags = match_default); | |
71 | std::string Merge(const std::string& in, const std::string& fmt, | |
72 | bool copy = true, boost::match_flag_type flags = match_default); | |
73 | std::string Merge(const char* in, const char* fmt, bool copy = true, | |
74 | boost::match_flag_type flags = match_default); | |
75 | unsigned Split(std::vector<std::string>& v, std::string& s, | |
76 | boost::match_flag_type flags = match_default, | |
77 | unsigned max_count = ~0); | |
78 | // | |
79 | // now operators for returning what matched in more detail: | |
80 | // | |
81 | unsigned int Position(int i = 0)const; | |
82 | unsigned int Length(int i = 0)const; | |
83 | bool Matched(int i = 0)const; | |
84 | unsigned int Line()const; | |
85 | unsigned int Marks() const; | |
86 | std::string What(int i)const; | |
87 | std::string operator[](int i)const ; | |
88 | ||
89 | static const unsigned int npos; | |
90 | }; | |
91 | ||
92 | Member functions for class RegEx are defined as follows: | |
93 | ||
94 | [table | |
95 | [[Member][Description]] | |
96 | [[`RegEx();`][Default constructor, constructs an instance of RegEx without any valid expression. ]] | |
97 | [[`RegEx(const RegEx& o);`][Copy constructor, all the properties of parameter /o/ | |
98 | are copied. ]] | |
99 | [[`RegEx(const char* c, bool icase = false);`][Constructs an instance of RegEx, | |
100 | setting the expression to /c/, if /icase/ is true then matching is | |
101 | insensitive to case, otherwise it is sensitive to case. Throws | |
102 | [bad_expression] on failure. ]] | |
103 | [[`RegEx(const std::string& s, bool icase = false);`][Constructs an instance of | |
104 | RegEx, setting the expression to /s/, if /icase/ is true then matching | |
105 | is insensitive to case, otherwise it is sensitive to case. Throws | |
106 | [bad_expression] on failure. ]] | |
107 | [[`RegEx& operator=(const RegEx& o);`][Default assignment operator. ]] | |
108 | [[`RegEx& operator=(const char* p);`][Assignment operator, equivalent to calling | |
109 | `SetExpression(p, false)`. Throws [bad_expression] on failure. ]] | |
110 | [[`RegEx& operator=(const std::string& s);`][Assignment operator, equivalent to | |
111 | calling `SetExpression(s, false)`. Throws [bad_expression] on failure. ]] | |
112 | [[`unsigned int SetExpression(const char* p, bool icase = false);`][Sets the | |
113 | current expression to /p/, if /icase/ is true then matching is | |
114 | insensitive to case, otherwise it is sensitive to case. | |
115 | Throws [bad_expression] on failure. ]] | |
116 | [[`unsigned int SetExpression(const std::string& s, bool icase = false);`] | |
117 | [Sets the current expression to /s/, if /icase/ is true then matching is | |
118 | insensitive to case, otherwise it is sensitive to case. Throws | |
119 | [bad_expression] on failure. ]] | |
120 | [[`std::string Expression()const;`][Returns a copy of the current regular expression. ]] | |
121 | [[`bool Match(const char* p, boost::match_flag_type flags = match_default);`] | |
122 | [Attempts to match the current expression against the text /p/ using | |
123 | the match flags /flags/ - see [match_flag_type]. Returns /true/ if the | |
124 | expression matches the whole of the input string. ]] | |
125 | [[`bool Match(const std::string& s, boost::match_flag_type flags = match_default);`] | |
126 | [Attempts to match the current expression against the text /s/ using | |
127 | the [match_flag_type] /flags/. Returns /true/ if the expression matches | |
128 | the whole of the input string. ]] | |
129 | [[`bool Search(const char* p, boost::match_flag_type flags = match_default);`] | |
130 | [Attempts to find a match for the current expression somewhere in | |
131 | the text /p/ using the [match_flag_type] /flags/. Returns /true/ | |
132 | if the match succeeds. ]] | |
133 | [[`bool Search(const std::string& s, boost::match_flag_type flags = match_default);`] | |
134 | [Attempts to find a match for the current expression somewhere in the | |
135 | text /s/ using the [match_flag_type] flags. Returns /true/ if the | |
136 | match succeeds. ]] | |
137 | [[`unsigned int Grep(GrepCallback cb, const char* p, boost::match_flag_type flags = match_default);`] | |
138 | [Finds all matches of the current expression in the text /p/ using the | |
139 | [match_flag_type] /flags/. For each match found calls the call-back | |
140 | function cb as: `cb(*this);` | |
141 | If at any stage the call-back function returns /false/ then the grep | |
142 | operation terminates, otherwise continues until no further matches | |
143 | are found. Returns the number of matches found.]] | |
144 | [[`unsigned int Grep(GrepCallback cb, const std::string& s, boost::match_flag_type flags = match_default);`] | |
145 | [Finds all matches of the current expression in the text /s/ using the | |
146 | [match_flag_type] flags. For each match found calls the call-back | |
147 | function cb as: `cb(*this);` | |
148 | If at any stage the call-back function returns false then the grep operation | |
149 | terminates, otherwise continues until no further matches are found. | |
150 | Returns the number of matches found.]] | |
151 | [[`unsigned int Grep(std::vector<std::string>& v, const char* p, boost::match_flag_type flags = match_default);`] | |
152 | [Finds all matches of the current expression in the text /p/ using the | |
153 | [match_flag_type] flags. For each match pushes a copy of what matched | |
154 | onto /v/. Returns the number of matches found. ]] | |
155 | [[`unsigned int Grep(std::vector<std::string>& v, const std::string& s, boost::match_flag_type flags = match_default);`] | |
156 | [Finds all matches of the current expression in the text /s/ using the | |
157 | [match_flag_type] /flags/. For each match pushes a copy of what | |
158 | matched onto /v/. Returns the number of matches found. ]] | |
159 | [[`unsigned int Grep(std::vector<unsigned int>& v, const char* p, boost::match_flag_type flags = match_default);`] | |
160 | [Finds all matches of the current expression in the text /p/ using the | |
161 | [match_flag_type] /flags/. For each match pushes the starting index of | |
162 | what matched onto /v/. Returns the number of matches found. ]] | |
163 | [[`unsigned int Grep(std::vector<unsigned int>& v, const std::string& s, boost::match_flag_type flags = match_default);`] | |
164 | [Finds all matches of the current expression in the text /s/ using the | |
165 | [match_flag_type] /flags/. For each match pushes the starting index of what | |
166 | matched onto /v/. Returns the number of matches found. ]] | |
167 | [[`unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`] | |
168 | [Finds all matches of the current expression in the files /files/ using | |
169 | the [match_flag_type] /flags/. For each match calls the call-back function cb. | |
170 | If the call-back returns false then the algorithm returns without | |
171 | considering further matches in the current file, or any further files. | |
172 | ||
173 | The parameter /files/ can include wild card characters '\*' and '\?', if | |
174 | the parameter recurse is true then searches sub-directories for matching | |
175 | file names. | |
176 | ||
177 | Returns the total number of matches found. | |
178 | ||
179 | May throw an exception derived from `std::runtime_error` if file io fails.]] | |
180 | [[`unsigned int GrepFiles(GrepFileCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`] | |
181 | [Finds all matches of the current expression in the files /files/ using the | |
182 | [match_flag_type] /flags/. For each match calls the call-back function cb. | |
183 | ||
184 | If the call-back returns false then the algorithm returns without | |
185 | considering further matches in the current file, or any further files. | |
186 | ||
187 | The parameter /files/ can include wild card characters '\*' and '\?', if | |
188 | the parameter recurse is true then searches sub-directories for | |
189 | matching file names. | |
190 | ||
191 | Returns the total number of matches found. | |
192 | ||
193 | May throw an exception derived from `std::runtime_error` if file io fails.]] | |
194 | ||
195 | [[`unsigned int FindFiles(FindFilesCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`] | |
196 | [Searches files to find all those which contain at least one match of | |
197 | the current expression using the [match_flag_type] /flags/. For each | |
198 | matching file calls the call-back function cb. | |
199 | If the call-back returns false then the algorithm returns without | |
200 | considering any further files. | |
201 | ||
202 | The parameter /files/ can include wild card characters '\*' and '\?', if | |
203 | the parameter /recurse/ is true then searches sub-directories for | |
204 | matching file names. | |
205 | ||
206 | Returns the total number of files found. | |
207 | ||
208 | May throw an exception derived from `std::runtime_error` if file io fails.]] | |
209 | [[`unsigned int FindFiles(FindFilesCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`] | |
210 | [Searches files to find all those which contain at least one | |
211 | match of the current expression using the [match_flag_type] /flags/. | |
212 | For each matching file calls the call-back function cb. | |
213 | ||
214 | If the call-back returns false then the algorithm returns without | |
215 | considering any further files. | |
216 | ||
217 | The parameter /files/ can include wild card characters '\*' and '\?', if | |
218 | the parameter /recurse/ is true then searches sub-directories for | |
219 | matching file names. | |
220 | ||
221 | Returns the total number of files found. | |
222 | ||
223 | May throw an exception derived from `std::runtime_error` if file io fails.]] | |
224 | ||
225 | [[`std::string Merge(const std::string& in, const std::string& fmt, bool copy = true, boost::match_flag_type flags = match_default);`] | |
226 | [Performs a search and replace operation: searches through the | |
227 | string /in/ for all occurrences of the current expression, for each | |
228 | occurrence replaces the match with the format string /fmt/. Uses /flags/ | |
229 | to determine what gets matched, and how the format string should be | |
230 | treated. If /copy/ is true then all unmatched sections of input are | |
231 | copied unchanged to output, if the flag /format_first_only/ is set then | |
232 | only the first occurrence of the pattern found is replaced. | |
233 | Returns the new string. See also | |
234 | [link boost_regex.format format string syntax], and [match_flag_type].]] | |
235 | [[`std::string Merge(const char* in, const char* fmt, bool copy = true, boost::match_flag_type flags = match_default);`] | |
236 | [Performs a search and replace operation: searches through the string /in/ | |
237 | for all occurrences of the current expression, for each occurrence | |
238 | replaces the match with the format string /fmt/. Uses /flags/ to determine | |
239 | what gets matched, and how the format string should be treated. | |
240 | If /copy/ is true then all unmatched sections of input are copied | |
241 | unchanged to output, if the flag /format_first_only/ is set then only | |
242 | the first occurrence of the pattern found is replaced. Returns | |
243 | the new string. See also [link boost_regex.format format string syntax], and [match_flag_type].]] | |
244 | [[`unsigned Split(std::vector<std::string>& v, std::string& s, boost::match_flag_type flags = match_default, unsigned max_count = ~0);`] | |
245 | [Splits the input string and pushes each one onto the vector. | |
246 | If the expression contains no marked sub-expressions, then one | |
247 | string is outputted for each section of the input that does not | |
248 | match the expression. If the expression does contain marked | |
249 | sub-expressions, then outputs one string for each marked | |
250 | sub-expression each time a match occurs. Outputs no more than | |
251 | /max_count/ strings. Before returning, deletes from the input string | |
252 | /s/ all of the input that has been processed (all of the string if | |
253 | /max_count/ was not reached). Returns the number of strings pushed | |
254 | onto the vector. ]] | |
255 | [[`unsigned int Position(int i = 0)const;`] | |
256 | [Returns the position of what matched sub-expression /i/. If `i = 0` | |
257 | then returns the position of the whole match. Returns `RegEx::npos` if | |
258 | the supplied index is invalid, or if the specified sub-expression | |
259 | did not participate in the match. ]] | |
260 | [[`unsigned int Length(int i = 0)const;`] | |
261 | [Returns the length of what matched sub-expression i. If `i = 0` then | |
262 | returns the length of the whole match. Returns `RegEx::npos` if the | |
263 | supplied index is invalid, or if the specified sub-expression did not | |
264 | participate in the match. ]] | |
265 | [[`bool Matched(int i = 0)const;`] | |
266 | [Returns true if sub-expression /i/ was matched, false otherwise. ]] | |
267 | [[`unsigned int Line()const;`][Returns the line on which the match occurred, | |
268 | indexes start from 1 not zero, if no match occurred then returns `RegEx::npos`. ]] | |
269 | [[`unsigned int Marks() const;`][Returns the number of marked sub-expressions | |
270 | contained in the expression. Note that this includes the whole | |
271 | match (sub-expression zero), so the value returned is always >= 1. ]] | |
272 | [[`std::string What(int i)const;`] | |
273 | [Returns a copy of what matched sub-expression /i/. If `i = 0` then | |
274 | returns a copy of the whole match. Returns a null string if the | |
275 | index is invalid or if the specified sub-expression did not | |
276 | participate in a match. ]] | |
277 | [[`std::string operator[](int i)const ;`][Returns `what(i);` | |
278 | Can be used to simplify access to sub-expression matches, and make | |
279 | usage more perl-like.]] | |
280 | ] | |
281 | ||
282 | [endsect] | |
283 |