284 lines
17 KiB
Plaintext
284 lines
17 KiB
Plaintext
[/
|
|
Copyright 2006-2007 John Maddock.
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt).
|
|
]
|
|
|
|
|
|
[section:old_regex High Level Class RegEx (Deprecated)]
|
|
|
|
The high level wrapper class RegEx is now deprecated and does not form
|
|
part of the regular expression standardization proposal. This type still
|
|
exists, and existing code will continue to compile, however the following
|
|
documentation is unlikely to be further updated.
|
|
|
|
#include <boost/cregex.hpp>
|
|
|
|
The class RegEx provides a high level simplified interface to the regular
|
|
expression library, this class only handles narrow character strings, and
|
|
regular expressions always follow the "normal" syntax - that is the
|
|
same as the perl / ECMAScript syntax.
|
|
|
|
typedef bool (*GrepCallback)(const RegEx& expression);
|
|
typedef bool (*GrepFileCallback)(const char* file, const RegEx& expression);
|
|
typedef bool (*FindFilesCallback)(const char* file);
|
|
|
|
class RegEx
|
|
{
|
|
public:
|
|
RegEx();
|
|
RegEx(const RegEx& o);
|
|
~RegEx();
|
|
RegEx(const char* c, bool icase = false);
|
|
explicit RegEx(const std::string& s, bool icase = false);
|
|
RegEx& operator=(const RegEx& o);
|
|
RegEx& operator=(const char* p);
|
|
RegEx& operator=(const std::string& s);
|
|
unsigned int SetExpression(const char* p, bool icase = false);
|
|
unsigned int SetExpression(const std::string& s, bool icase = false);
|
|
std::string Expression()const;
|
|
//
|
|
// now matching operators:
|
|
//
|
|
bool Match(const char* p, boost::match_flag_type flags = match_default);
|
|
bool Match(const std::string& s, boost::match_flag_type flags = match_default);
|
|
bool Search(const char* p, boost::match_flag_type flags = match_default);
|
|
bool Search(const std::string& s, boost::match_flag_type flags = match_default);
|
|
unsigned int Grep(GrepCallback cb, const char* p,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int Grep(GrepCallback cb, const std::string& s,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int Grep(std::vector<std::string>& v, const char* p,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int Grep(std::vector<std::string>& v, const std::string& s,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int Grep(std::vector<unsigned int>& v, const char* p,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int Grep(std::vector<unsigned int>& v, const std::string& s,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int GrepFiles(GrepFileCallback cb, const std::string& files,
|
|
bool recurse = false,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int FindFiles(FindFilesCallback cb, const char* files,
|
|
bool recurse = false,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned int FindFiles(FindFilesCallback cb, const std::string& files,
|
|
bool recurse = false,
|
|
boost::match_flag_type flags = match_default);
|
|
std::string Merge(const std::string& in, const std::string& fmt,
|
|
bool copy = true, boost::match_flag_type flags = match_default);
|
|
std::string Merge(const char* in, const char* fmt, bool copy = true,
|
|
boost::match_flag_type flags = match_default);
|
|
unsigned Split(std::vector<std::string>& v, std::string& s,
|
|
boost::match_flag_type flags = match_default,
|
|
unsigned max_count = ~0);
|
|
//
|
|
// now operators for returning what matched in more detail:
|
|
//
|
|
unsigned int Position(int i = 0)const;
|
|
unsigned int Length(int i = 0)const;
|
|
bool Matched(int i = 0)const;
|
|
unsigned int Line()const;
|
|
unsigned int Marks() const;
|
|
std::string What(int i)const;
|
|
std::string operator[](int i)const ;
|
|
|
|
static const unsigned int npos;
|
|
};
|
|
|
|
Member functions for class RegEx are defined as follows:
|
|
|
|
[table
|
|
[[Member][Description]]
|
|
[[`RegEx();`][Default constructor, constructs an instance of RegEx without any valid expression. ]]
|
|
[[`RegEx(const RegEx& o);`][Copy constructor, all the properties of parameter /o/
|
|
are copied. ]]
|
|
[[`RegEx(const char* c, bool icase = false);`][Constructs an instance of RegEx,
|
|
setting the expression to /c/, if /icase/ is true then matching is
|
|
insensitive to case, otherwise it is sensitive to case. Throws
|
|
[bad_expression] on failure. ]]
|
|
[[`RegEx(const std::string& s, bool icase = false);`][Constructs an instance of
|
|
RegEx, setting the expression to /s/, if /icase/ is true then matching
|
|
is insensitive to case, otherwise it is sensitive to case. Throws
|
|
[bad_expression] on failure. ]]
|
|
[[`RegEx& operator=(const RegEx& o);`][Default assignment operator. ]]
|
|
[[`RegEx& operator=(const char* p);`][Assignment operator, equivalent to calling
|
|
`SetExpression(p, false)`. Throws [bad_expression] on failure. ]]
|
|
[[`RegEx& operator=(const std::string& s);`][Assignment operator, equivalent to
|
|
calling `SetExpression(s, false)`. Throws [bad_expression] on failure. ]]
|
|
[[`unsigned int SetExpression(const char* p, bool icase = false);`][Sets the
|
|
current expression to /p/, if /icase/ is true then matching is
|
|
insensitive to case, otherwise it is sensitive to case.
|
|
Throws [bad_expression] on failure. ]]
|
|
[[`unsigned int SetExpression(const std::string& s, bool icase = false);`]
|
|
[Sets the current expression to /s/, if /icase/ is true then matching is
|
|
insensitive to case, otherwise it is sensitive to case. Throws
|
|
[bad_expression] on failure. ]]
|
|
[[`std::string Expression()const;`][Returns a copy of the current regular expression. ]]
|
|
[[`bool Match(const char* p, boost::match_flag_type flags = match_default);`]
|
|
[Attempts to match the current expression against the text /p/ using
|
|
the match flags /flags/ - see [match_flag_type]. Returns /true/ if the
|
|
expression matches the whole of the input string. ]]
|
|
[[`bool Match(const std::string& s, boost::match_flag_type flags = match_default);`]
|
|
[Attempts to match the current expression against the text /s/ using
|
|
the [match_flag_type] /flags/. Returns /true/ if the expression matches
|
|
the whole of the input string. ]]
|
|
[[`bool Search(const char* p, boost::match_flag_type flags = match_default);`]
|
|
[Attempts to find a match for the current expression somewhere in
|
|
the text /p/ using the [match_flag_type] /flags/. Returns /true/
|
|
if the match succeeds. ]]
|
|
[[`bool Search(const std::string& s, boost::match_flag_type flags = match_default);`]
|
|
[Attempts to find a match for the current expression somewhere in the
|
|
text /s/ using the [match_flag_type] flags. Returns /true/ if the
|
|
match succeeds. ]]
|
|
[[`unsigned int Grep(GrepCallback cb, const char* p, boost::match_flag_type flags = match_default);`]
|
|
[Finds all matches of the current expression in the text /p/ using the
|
|
[match_flag_type] /flags/. For each match found calls the call-back
|
|
function cb as: `cb(*this);`
|
|
If at any stage the call-back function returns /false/ then the grep
|
|
operation terminates, otherwise continues until no further matches
|
|
are found. Returns the number of matches found.]]
|
|
[[`unsigned int Grep(GrepCallback cb, const std::string& s, boost::match_flag_type flags = match_default);`]
|
|
[Finds all matches of the current expression in the text /s/ using the
|
|
[match_flag_type] flags. For each match found calls the call-back
|
|
function cb as: `cb(*this);`
|
|
If at any stage the call-back function returns false then the grep operation
|
|
terminates, otherwise continues until no further matches are found.
|
|
Returns the number of matches found.]]
|
|
[[`unsigned int Grep(std::vector<std::string>& v, const char* p, boost::match_flag_type flags = match_default);`]
|
|
[Finds all matches of the current expression in the text /p/ using the
|
|
[match_flag_type] flags. For each match pushes a copy of what matched
|
|
onto /v/. Returns the number of matches found. ]]
|
|
[[`unsigned int Grep(std::vector<std::string>& v, const std::string& s, boost::match_flag_type flags = match_default);`]
|
|
[Finds all matches of the current expression in the text /s/ using the
|
|
[match_flag_type] /flags/. For each match pushes a copy of what
|
|
matched onto /v/. Returns the number of matches found. ]]
|
|
[[`unsigned int Grep(std::vector<unsigned int>& v, const char* p, boost::match_flag_type flags = match_default);`]
|
|
[Finds all matches of the current expression in the text /p/ using the
|
|
[match_flag_type] /flags/. For each match pushes the starting index of
|
|
what matched onto /v/. Returns the number of matches found. ]]
|
|
[[`unsigned int Grep(std::vector<unsigned int>& v, const std::string& s, boost::match_flag_type flags = match_default);`]
|
|
[Finds all matches of the current expression in the text /s/ using the
|
|
[match_flag_type] /flags/. For each match pushes the starting index of what
|
|
matched onto /v/. Returns the number of matches found. ]]
|
|
[[`unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`]
|
|
[Finds all matches of the current expression in the files /files/ using
|
|
the [match_flag_type] /flags/. For each match calls the call-back function cb.
|
|
If the call-back returns false then the algorithm returns without
|
|
considering further matches in the current file, or any further files.
|
|
|
|
The parameter /files/ can include wild card characters '\*' and '\?', if
|
|
the parameter recurse is true then searches sub-directories for matching
|
|
file names.
|
|
|
|
Returns the total number of matches found.
|
|
|
|
May throw an exception derived from `std::runtime_error` if file io fails.]]
|
|
[[`unsigned int GrepFiles(GrepFileCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`]
|
|
[Finds all matches of the current expression in the files /files/ using the
|
|
[match_flag_type] /flags/. For each match calls the call-back function cb.
|
|
|
|
If the call-back returns false then the algorithm returns without
|
|
considering further matches in the current file, or any further files.
|
|
|
|
The parameter /files/ can include wild card characters '\*' and '\?', if
|
|
the parameter recurse is true then searches sub-directories for
|
|
matching file names.
|
|
|
|
Returns the total number of matches found.
|
|
|
|
May throw an exception derived from `std::runtime_error` if file io fails.]]
|
|
|
|
[[`unsigned int FindFiles(FindFilesCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`]
|
|
[Searches files to find all those which contain at least one match of
|
|
the current expression using the [match_flag_type] /flags/. For each
|
|
matching file calls the call-back function cb.
|
|
If the call-back returns false then the algorithm returns without
|
|
considering any further files.
|
|
|
|
The parameter /files/ can include wild card characters '\*' and '\?', if
|
|
the parameter /recurse/ is true then searches sub-directories for
|
|
matching file names.
|
|
|
|
Returns the total number of files found.
|
|
|
|
May throw an exception derived from `std::runtime_error` if file io fails.]]
|
|
[[`unsigned int FindFiles(FindFilesCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`]
|
|
[Searches files to find all those which contain at least one
|
|
match of the current expression using the [match_flag_type] /flags/.
|
|
For each matching file calls the call-back function cb.
|
|
|
|
If the call-back returns false then the algorithm returns without
|
|
considering any further files.
|
|
|
|
The parameter /files/ can include wild card characters '\*' and '\?', if
|
|
the parameter /recurse/ is true then searches sub-directories for
|
|
matching file names.
|
|
|
|
Returns the total number of files found.
|
|
|
|
May throw an exception derived from `std::runtime_error` if file io fails.]]
|
|
|
|
[[`std::string Merge(const std::string& in, const std::string& fmt, bool copy = true, boost::match_flag_type flags = match_default);`]
|
|
[Performs a search and replace operation: searches through the
|
|
string /in/ for all occurrences of the current expression, for each
|
|
occurrence replaces the match with the format string /fmt/. Uses /flags/
|
|
to determine what gets matched, and how the format string should be
|
|
treated. If /copy/ is true then all unmatched sections of input are
|
|
copied unchanged to output, if the flag /format_first_only/ is set then
|
|
only the first occurrence of the pattern found is replaced.
|
|
Returns the new string. See also
|
|
[link boost_regex.format format string syntax], and [match_flag_type].]]
|
|
[[`std::string Merge(const char* in, const char* fmt, bool copy = true, boost::match_flag_type flags = match_default);`]
|
|
[Performs a search and replace operation: searches through the string /in/
|
|
for all occurrences of the current expression, for each occurrence
|
|
replaces the match with the format string /fmt/. Uses /flags/ to determine
|
|
what gets matched, and how the format string should be treated.
|
|
If /copy/ is true then all unmatched sections of input are copied
|
|
unchanged to output, if the flag /format_first_only/ is set then only
|
|
the first occurrence of the pattern found is replaced. Returns
|
|
the new string. See also [link boost_regex.format format string syntax], and [match_flag_type].]]
|
|
[[`unsigned Split(std::vector<std::string>& v, std::string& s, boost::match_flag_type flags = match_default, unsigned max_count = ~0);`]
|
|
[Splits the input string and pushes each one onto the vector.
|
|
If the expression contains no marked sub-expressions, then one
|
|
string is outputted for each section of the input that does not
|
|
match the expression. If the expression does contain marked
|
|
sub-expressions, then outputs one string for each marked
|
|
sub-expression each time a match occurs. Outputs no more than
|
|
/max_count/ strings. Before returning, deletes from the input string
|
|
/s/ all of the input that has been processed (all of the string if
|
|
/max_count/ was not reached). Returns the number of strings pushed
|
|
onto the vector. ]]
|
|
[[`unsigned int Position(int i = 0)const;`]
|
|
[Returns the position of what matched sub-expression /i/. If `i = 0`
|
|
then returns the position of the whole match. Returns `RegEx::npos` if
|
|
the supplied index is invalid, or if the specified sub-expression
|
|
did not participate in the match. ]]
|
|
[[`unsigned int Length(int i = 0)const;`]
|
|
[Returns the length of what matched sub-expression i. If `i = 0` then
|
|
returns the length of the whole match. Returns `RegEx::npos` if the
|
|
supplied index is invalid, or if the specified sub-expression did not
|
|
participate in the match. ]]
|
|
[[`bool Matched(int i = 0)const;`]
|
|
[Returns true if sub-expression /i/ was matched, false otherwise. ]]
|
|
[[`unsigned int Line()const;`][Returns the line on which the match occurred,
|
|
indexes start from 1 not zero, if no match occurred then returns `RegEx::npos`. ]]
|
|
[[`unsigned int Marks() const;`][Returns the number of marked sub-expressions
|
|
contained in the expression. Note that this includes the whole
|
|
match (sub-expression zero), so the value returned is always >= 1. ]]
|
|
[[`std::string What(int i)const;`]
|
|
[Returns a copy of what matched sub-expression /i/. If `i = 0` then
|
|
returns a copy of the whole match. Returns a null string if the
|
|
index is invalid or if the specified sub-expression did not
|
|
participate in a match. ]]
|
|
[[`std::string operator[](int i)const ;`][Returns `what(i);`
|
|
Can be used to simplify access to sub-expression matches, and make
|
|
usage more perl-like.]]
|
|
]
|
|
|
|
[endsect]
|
|
|