Debian Codegraph @

Utilities/KWSys/RegularExpression.hxx.in

raw
1 /* Distributed under the OSI-approved BSD 3-Clause License. See accompanying
2 file Copyright.txt or https://cmake.org/licensing#kwsys for details. */
3 // Original Copyright notice:
4 // Copyright (C) 1991 Texas Instruments Incorporated.
5 //
6 // Permission is granted to any individual or institution to use, copy, modify,
7 // and distribute this software, provided that this complete copyright and
8 // permission notice is maintained, intact, in all copies and supporting
9 // documentation.
10 //
11 // Texas Instruments Incorporated provides this software "as is" without
12 // express or implied warranty.
13 //
14 // Created: MNF 06/13/89 Initial Design and Implementation
15 // Updated: LGO 08/09/89 Inherit from Generic
16 // Updated: MBN 09/07/89 Added conditional exception handling
17 // Updated: MBN 12/15/89 Sprinkled "const" qualifiers all over the place!
18 // Updated: DLS 03/22/91 New lite version
19 //
20
21 #ifndef @KWSYS_NAMESPACE@_RegularExpression_hxx
22 #define @KWSYS_NAMESPACE@_RegularExpression_hxx
23
24 #include <@KWSYS_NAMESPACE@/Configure.h>
25 #include <@KWSYS_NAMESPACE@/Configure.hxx>
26
27 #include <string>
28
29 namespace @KWSYS_NAMESPACE@ {
30
31 // Forward declaration
32 class RegularExpression;
33
34 /** \class RegularExpressionMatch
35 * \brief Stores the pattern matches of a RegularExpression
36 */
37 class @KWSYS_NAMESPACE@_EXPORT RegularExpressionMatch
38 {
39 public:
40 RegularExpressionMatch();
41
42 bool isValid() const;
43 void clear();
44
45 std::string::size_type start() const;
46 std::string::size_type end() const;
47 std::string::size_type start(int n) const;
48 std::string::size_type end(int n) const;
49 std::string match(int n) const;
50
51 enum
52 {
53 NSUBEXP = 32
54 };
55
56 private:
57 friend class RegularExpression;
58 const char* startp[NSUBEXP];
59 const char* endp[NSUBEXP];
60 const char* searchstring;
61 };
62
63 #ifdef _MSC_VER
64 # pragma warning(push)
65 # if _MSC_VER < 1900
66 # pragma warning(disable : 4351) /* new behavior */
67 # endif
68 #endif
69
70 /**
71 * \brief Creates an invalid match object
72 */
73 inline RegularExpressionMatch::RegularExpressionMatch()
74 : startp{}
75 , endp{}
76 , searchstring{}
77 {
78 }
79
80 #ifdef _MSC_VER
81 # pragma warning(pop)
82 #endif
83
84 /**
85 * \brief Returns true if the match pointers are valid
86 */
87 inline bool RegularExpressionMatch::isValid() const
88 {
89 return (this->startp[0] != nullptr);
90 }
91
92 /**
93 * \brief Resets to the (invalid) construction state.
94 */
95 inline void RegularExpressionMatch::clear()
96 {
97 startp[0] = nullptr;
98 endp[0] = nullptr;
99 searchstring = nullptr;
100 }
101
102 /**
103 * \brief Returns the start index of the full match.
104 */
105 inline std::string::size_type RegularExpressionMatch::start() const
106 {
107 return static_cast<std::string::size_type>(this->startp[0] - searchstring);
108 }
109
110 /**
111 * \brief Returns the end index of the full match.
112 */
113 inline std::string::size_type RegularExpressionMatch::end() const
114 {
115 return static_cast<std::string::size_type>(this->endp[0] - searchstring);
116 }
117
118 /**
119 * \brief Returns the start index of nth submatch.
120 * start(0) is the start of the full match.
121 */
122 inline std::string::size_type RegularExpressionMatch::start(int n) const
123 {
124 return static_cast<std::string::size_type>(this->startp[n] -
125 this->searchstring);
126 }
127
128 /**
129 * \brief Returns the end index of nth submatch.
130 * end(0) is the end of the full match.
131 */
132 inline std::string::size_type RegularExpressionMatch::end(int n) const
133 {
134 return static_cast<std::string::size_type>(this->endp[n] -
135 this->searchstring);
136 }
137
138 /**
139 * \brief Returns the nth submatch as a string.
140 */
141 inline std::string RegularExpressionMatch::match(int n) const
142 {
143 if (this->startp[n] == nullptr) {
144 return std::string();
145 } else {
146 return std::string(
147 this->startp[n],
148 static_cast<std::string::size_type>(this->endp[n] - this->startp[n]));
149 }
150 }
151
152 /** \class RegularExpression
153 * \brief Implements pattern matching with regular expressions.
154 *
155 * This is the header file for the regular expression class. An object of
156 * this class contains a regular expression, in a special "compiled" format.
157 * This compiled format consists of several slots all kept as the objects
158 * private data. The RegularExpression class provides a convenient way to
159 * represent regular expressions. It makes it easy to search for the same
160 * regular expression in many different strings without having to compile a
161 * string to regular expression format more than necessary.
162 *
163 * This class implements pattern matching via regular expressions.
164 * A regular expression allows a programmer to specify complex
165 * patterns that can be searched for and matched against the
166 * character string of a string object. In its simplest form, a
167 * regular expression is a sequence of characters used to
168 * search for exact character matches. However, many times the
169 * exact sequence to be found is not known, or only a match at
170 * the beginning or end of a string is desired. The RegularExpression regu-
171 * lar expression class implements regular expression pattern
172 * matching as is found and implemented in many UNIX commands
173 * and utilities.
174 *
175 * Example: The perl code
176 *
177 * $filename =~ m"([a-z]+)\.cc";
178 * print $1;
179 *
180 * Is written as follows in C++
181 *
182 * RegularExpression re("([a-z]+)\\.cc");
183 * re.find(filename);
184 * cerr << re.match(1);
185 *
186 *
187 * The regular expression class provides a convenient mechanism
188 * for specifying and manipulating regular expressions. The
189 * regular expression object allows specification of such pat-
190 * terns by using the following regular expression metacharac-
191 * ters:
192 *
193 * ^ Matches at beginning of a line
194 *
195 * $ Matches at end of a line
196 *
197 * . Matches any single character
198 *
199 * [ ] Matches any character(s) inside the brackets
200 *
201 * [^ ] Matches any character(s) not inside the brackets
202 *
203 * - Matches any character in range on either side of a dash
204 *
205 * * Matches preceding pattern zero or more times
206 *
207 * + Matches preceding pattern one or more times
208 *
209 * ? Matches preceding pattern zero or once only
210 *
211 * () Saves a matched expression and uses it in a later match
212 *
213 * Note that more than one of these metacharacters can be used
214 * in a single regular expression in order to create complex
215 * search patterns. For example, the pattern [^ab1-9] says to
216 * match any character sequence that does not begin with the
217 * characters "ab" followed by numbers in the series one
218 * through nine.
219 *
220 * There are three constructors for RegularExpression. One just creates an
221 * empty RegularExpression object. Another creates a RegularExpression
222 * object and initializes it with a regular expression that is given in the
223 * form of a char*. The third takes a reference to a RegularExpression
224 * object as an argument and creates an object initialized with the
225 * information from the given RegularExpression object.
226 *
227 * The find member function finds the first occurrence of the regular
228 * expression of that object in the string given to find as an argument. Find
229 * returns a boolean, and if true, mutates the private data appropriately.
230 * Find sets pointers to the beginning and end of the thing last found, they
231 * are pointers into the actual string that was searched. The start and end
232 * member functions return indices into the searched string that correspond
233 * to the beginning and end pointers respectively. The compile member
234 * function takes a char* and puts the compiled version of the char* argument
235 * into the object's private data fields. The == and != operators only check
236 * the to see if the compiled regular expression is the same, and the
237 * deep_equal functions also checks to see if the start and end pointers are
238 * the same. The is_valid function returns false if program is set to
239 * nullptr, (i.e. there is no valid compiled expression). The set_invalid
240 * function sets the program to nullptr (Warning: this deletes the compiled
241 * expression). The following examples may help clarify regular expression
242 * usage:
243 *
244 * * The regular expression "^hello" matches a "hello" only at the
245 * beginning of a line. It would match "hello there" but not "hi,
246 * hello there".
247 *
248 * * The regular expression "long$" matches a "long" only at the end
249 * of a line. It would match "so long\0", but not "long ago".
250 *
251 * * The regular expression "t..t..g" will match anything that has a
252 * "t" then any two characters, another "t", any two characters and
253 * then a "g". It will match "testing", or "test again" but would
254 * not match "toasting"
255 *
256 * * The regular expression "[1-9ab]" matches any number one through
257 * nine, and the characters "a" and "b". It would match "hello 1"
258 * or "begin", but would not match "no-match".
259 *
260 * * The regular expression "[^1-9ab]" matches any character that is
261 * not a number one through nine, or an "a" or "b". It would NOT
262 * match "hello 1" or "begin", but would match "no-match".
263 *
264 * * The regular expression "br* " matches something that begins with
265 * a "b", is followed by zero or more "r"s, and ends in a space. It
266 * would match "brrrrr ", and "b ", but would not match "brrh ".
267 *
268 * * The regular expression "br+ " matches something that begins with
269 * a "b", is followed by one or more "r"s, and ends in a space. It
270 * would match "brrrrr ", and "br ", but would not match "b " or
271 * "brrh ".
272 *
273 * * The regular expression "br? " matches something that begins with
274 * a "b", is followed by zero or one "r"s, and ends in a space. It
275 * would match "br ", and "b ", but would not match "brrrr " or
276 * "brrh ".
277 *
278 * * The regular expression "(..p)b" matches something ending with pb
279 * and beginning with whatever the two characters before the first p
280 * encountered in the line were. It would find "repb" in "rep drepa
281 * qrepb". The regular expression "(..p)a" would find "repa qrepb"
282 * in "rep drepa qrepb"
283 *
284 * * The regular expression "d(..p)" matches something ending with p,
285 * beginning with d, and having two characters in between that are
286 * the same as the two characters before the first p encountered in
287 * the line. It would match "drepa qrepb" in "rep drepa qrepb".
288 *
289 * All methods of RegularExpression can be called simultaneously from
290 * different threads but only if each invocation uses an own instance of
291 * RegularExpression.
292 */
293 class @KWSYS_NAMESPACE@_EXPORT RegularExpression
294 {
295 public:
296 /**
297 * Instantiate RegularExpression with program=nullptr.
298 */
299 inline RegularExpression();
300
301 /**
302 * Instantiate RegularExpression with compiled char*.
303 */
304 inline RegularExpression(char const*);
305
306 /**
307 * Instantiate RegularExpression as a copy of another regular expression.
308 */
309 RegularExpression(RegularExpression const&);
310
311 /**
312 * Instantiate RegularExpression with compiled string.
313 */
314 inline RegularExpression(std::string const&);
315
316 /**
317 * Destructor.
318 */
319 inline ~RegularExpression();
320
321 /**
322 * Compile a regular expression into internal code
323 * for later pattern matching.
324 */
325 bool compile(char const*);
326
327 /**
328 * Compile a regular expression into internal code
329 * for later pattern matching.
330 */
331 inline bool compile(std::string const&);
332
333 /**
334 * Matches the regular expression to the given string.
335 * Returns true if found, and sets start and end indexes
336 * in the RegularExpressionMatch instance accordingly.
337 *
338 * This method is thread safe when called with different
339 * RegularExpressionMatch instances.
340 */
341 bool find(char const*, RegularExpressionMatch&) const;
342
343 /**
344 * Matches the regular expression to the given string.
345 * Returns true if found, and sets start and end indexes accordingly.
346 */
347 inline bool find(char const*);
348
349 /**
350 * Matches the regular expression to the given std string.
351 * Returns true if found, and sets start and end indexes accordingly.
352 */
353 inline bool find(std::string const&);
354
355 /**
356 * Match indices
357 */
358 inline RegularExpressionMatch const& regMatch() const;
359 inline std::string::size_type start() const;
360 inline std::string::size_type end() const;
361 inline std::string::size_type start(int n) const;
362 inline std::string::size_type end(int n) const;
363
364 /**
365 * Match strings
366 */
367 inline std::string match(int n) const;
368
369 /**
370 * Copy the given regular expression.
371 */
372 RegularExpression& operator=(const RegularExpression& rxp);
373
374 /**
375 * Returns true if two regular expressions have the same
376 * compiled program for pattern matching.
377 */
378 bool operator==(RegularExpression const&) const;
379
380 /**
381 * Returns true if two regular expressions have different
382 * compiled program for pattern matching.
383 */
384 inline bool operator!=(RegularExpression const&) const;
385
386 /**
387 * Returns true if have the same compiled regular expressions
388 * and the same start and end pointers.
389 */
390 bool deep_equal(RegularExpression const&) const;
391
392 /**
393 * True if the compiled regexp is valid.
394 */
395 inline bool is_valid() const;
396
397 /**
398 * Marks the regular expression as invalid.
399 */
400 inline void set_invalid();
401
402 private:
403 RegularExpressionMatch regmatch;
404 char regstart; // Internal use only
405 char reganch; // Internal use only
406 const char* regmust; // Internal use only
407 std::string::size_type regmlen; // Internal use only
408 char* program;
409 int progsize;
410 };
411
412 /**
413 * Create an empty regular expression.
414 */
415 inline RegularExpression::RegularExpression()
416 : regstart{}
417 , reganch{}
418 , regmust{}
419 , program{ nullptr }
420 , progsize{}
421 {
422 }
423
424 /**
425 * Creates a regular expression from string s, and
426 * compiles s.
427 */
428 inline RegularExpression::RegularExpression(const char* s)
429 : regstart{}
430 , reganch{}
431 , regmust{}
432 , program{ nullptr }
433 , progsize{}
434 {
435 if (s) {
436 this->compile(s);
437 }
438 }
439
440 /**
441 * Creates a regular expression from string s, and
442 * compiles s.
443 */
444 inline RegularExpression::RegularExpression(const std::string& s)
445 : regstart{}
446 , reganch{}
447 , regmust{}
448 , program{ nullptr }
449 , progsize{}
450 {
451 this->compile(s);
452 }
453
454 /**
455 * Destroys and frees space allocated for the regular expression.
456 */
457 inline RegularExpression::~RegularExpression()
458 {
459 // #ifndef _WIN32
460 delete[] this->program;
461 // #endif
462 }
463
464 /**
465 * Compile a regular expression into internal code
466 * for later pattern matching.
467 */
468 inline bool RegularExpression::compile(std::string const& s)
469 {
470 return this->compile(s.c_str());
471 }
472
473 /**
474 * Matches the regular expression to the given std string.
475 * Returns true if found, and sets start and end indexes accordingly.
476 */
477 inline bool RegularExpression::find(const char* s)
478 {
479 return this->find(s, this->regmatch);
480 }
481
482 /**
483 * Matches the regular expression to the given std string.
484 * Returns true if found, and sets start and end indexes accordingly.
485 */
486 inline bool RegularExpression::find(std::string const& s)
487 {
488 return this->find(s.c_str());
489 }
490
491 /**
492 * Returns the internal match object
493 */
494 inline RegularExpressionMatch const& RegularExpression::regMatch() const
495 {
496 return this->regmatch;
497 }
498
499 /**
500 * Returns the start index of the full match.
501 */
502 inline std::string::size_type RegularExpression::start() const
503 {
504 return regmatch.start();
505 }
506
507 /**
508 * Returns the end index of the full match.
509 */
510 inline std::string::size_type RegularExpression::end() const
511 {
512 return regmatch.end();
513 }
514
515 /**
516 * Return start index of nth submatch. start(0) is the start of the full match.
517 */
518 inline std::string::size_type RegularExpression::start(int n) const
519 {
520 return regmatch.start(n);
521 }
522
523 /**
524 * Return end index of nth submatch. end(0) is the end of the full match.
525 */
526 inline std::string::size_type RegularExpression::end(int n) const
527 {
528 return regmatch.end(n);
529 }
530
531 /**
532 * Return nth submatch as a string.
533 */
534 inline std::string RegularExpression::match(int n) const
535 {
536 return regmatch.match(n);
537 }
538
539 /**
540 * Returns true if two regular expressions have different
541 * compiled program for pattern matching.
542 */
543 inline bool RegularExpression::operator!=(const RegularExpression& r) const
544 {
545 return (!(*this == r));
546 }
547
548 /**
549 * Returns true if a valid regular expression is compiled
550 * and ready for pattern matching.
551 */
552 inline bool RegularExpression::is_valid() const
553 {
554 return (this->program != nullptr);
555 }
556
557 inline void RegularExpression::set_invalid()
558 {
559 // #ifndef _WIN32
560 delete[] this->program;
561 // #endif
562 this->program = nullptr;
563 }
564
565 } // namespace @KWSYS_NAMESPACE@
566
567 #endif