interface/regex.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        regex.h
   3 // Purpose:     interface of wxRegEx
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @anchor wxRE_FLAGS
  11
  12     Flags for regex compilation to be used with wxRegEx::Compile().
  13 */
  14 enum
  15 {
  16     /** Use extended regex syntax. */
  17     wxRE_EXTENDED = 0,
  18
  19     /** Use advanced RE syntax (built-in regex only). */
  20     wxRE_ADVANCED = 1,
  21
  22     /** Use basic RE syntax. */
  23     wxRE_BASIC    = 2,
  24
  25     /** Ignore case in match. */
  26     wxRE_ICASE    = 4,
  27
  28     /** Only check match, don't set back references. */
  29     wxRE_NOSUB    = 8,
  30
  31     /**
  32         If not set, treat '\n' as an ordinary character, otherwise it is
  33         special: it is not matched by '.' and '^' and '$' always match
  34         after/before it regardless of the setting of wxRE_NOT[BE]OL.
  35     */
  36     wxRE_NEWLINE  = 16,
  37
  38     /** Default flags.*/
  39     wxRE_DEFAULT  = wxRE_EXTENDED
  40 };
  41
  42 /**
  43     @anchor wxRE_NOT_FLAGS
  44
  45     Flags for regex matching to be used with wxRegEx::Matches().
  46     These flags are mainly useful when doing several matches in a long string
  47     to prevent erroneous matches for '^' and '$':
  48 */
  49 enum
  50 {
  51     /** '^' doesn't match at the start of line. */
  52     wxRE_NOTBOL = 32,
  53
  54     /** '$' doesn't match at the end of line. */
  55     wxRE_NOTEOL = 64
  56 };
  57
  58 /**
  59     @class wxRegEx
  60     @wxheader{regex.h}
  61
  62     wxRegEx represents a regular expression.  This class provides support
  63     for regular expressions matching and also replacement.
  64
  65     It is built on top of either the system library (if it has support
  66     for POSIX regular expressions - which is the case of the most modern
  67     Unices) or uses the built in Henry Spencer's library.  Henry Spencer
  68     would appreciate being given credit in the documentation of software
  69     which uses his library, but that is not a requirement.
  70
  71     Regular expressions, as defined by POSIX, come in two flavours: @e extended
  72     and @e basic.  The builtin library also adds a third flavour
  73     of expression @ref overview_resyntax "advanced", which is not available
  74     when using the system library.
  75
  76     Unicode is fully supported only when using the builtin library.
  77     When using the system library in Unicode mode, the expressions and data
  78     are translated to the default 8-bit encoding before being passed to
  79     the library.
  80
  81     On platforms where a system library is available, the default is to use
  82     the builtin library for Unicode builds, and the system library otherwise.
  83     It is possible to use the other if preferred by selecting it when building
  84     the wxWidgets.
  85
  86     @library{wxbase}
  87     @category{data}
  88
  89     Examples:
  90
  91     A bad example of processing some text containing email addresses (the example
  92     is bad because the real email addresses can have more complicated form than
  93     @c user@host.net):
  94
  95     @code
  96     wxString text;
  97     ...
  98     wxRegEx reEmail = wxT("([^@]+)@([[:alnum:].-_].)+([[:alnum:]]+)");
  99     if ( reEmail.Matches(text) )
 100     {
 101         wxString text = reEmail.GetMatch(email);
 102         wxString username = reEmail.GetMatch(email, 1);
 103         if ( reEmail.GetMatch(email, 3) == wxT("com") ) // .com TLD?
 104         {
 105             ...
 106         }
 107     }
 108
 109     // or we could do this to hide the email address
 110     size_t count = reEmail.ReplaceAll(text, wxT("HIDDEN@\\2\\3"));
 111     printf("text now contains %u hidden addresses", count);
 112     @endcode
 113 */
 114 class wxRegEx
 115 {
 116 public:
 117
 118     /**
 119         Default constructor: use Compile() later.
 120     */
 121     wxRegEx();
 122
 123     /**
 124         Create and compile the regular expression, use
 125         IsValid() to test for compilation errors.
 126
 127         As for the flags, please see @ref wxRE_FLAGS.
 128     */
 129     wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT);
 130
 131
 132     /**
 133         Destructor. It's not virtual, don't derive from this class.
 134     */
 135     ~wxRegEx();
 136
 137     /**
 138         Compile the string into regular expression, return @true if ok or @false
 139         if string has a syntax error.
 140
 141         As for the flags, please see @ref wxRE_FLAGS.
 142     */
 143     bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT);
 144
 145     /**
 146         Get the start index and the length of the match of the expression
 147         (if @a index is 0) or a bracketed subexpression (@a index different from 0).
 148
 149         May only be called after successful call to Matches() and only if @c wxRE_NOSUB
 150         was @b not used in Compile().
 151
 152         Returns @false if no match or if an error occurred.
 153
 154     */
 155     bool GetMatch(size_t* start, size_t* len, size_t index = 0) const;
 156
 157     /**
 158         Returns the part of string corresponding to the match where index is interpreted
 159         as above. Empty string is returned if match failed.
 160
 161         May only be called after successful call to Matches() and only if @c wxRE_NOSUB
 162         was @b not used in Compile().
 163     */
 164     wxString  GetMatch(const wxString& text, size_t index = 0) const;
 165
 166     /**
 167         Returns the size of the array of matches, i.e. the number of bracketed
 168         subexpressions plus one for the expression itself, or 0 on error.
 169
 170         May only be called after successful call to Compile().
 171         and only if @c wxRE_NOSUB was @b not used.
 172     */
 173     size_t GetMatchCount() const;
 174
 175     /**
 176         Return @true if this is a valid compiled regular expression, @false
 177         otherwise.
 178     */
 179     bool IsValid() const;
 180
 181     //@{
 182     /**
 183         Matches the precompiled regular expression against the string @a text,
 184         returns @true if matches and @false otherwise.
 185
 186         @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL, see
 187         @ref wxRE_NOT_FLAGS.
 188
 189         Some regex libraries assume that the text given is null terminated, while
 190         others require the length be given as a separate parameter. Therefore for
 191         maximum portability assume that @a text cannot contain embedded nulls.
 192
 193         When the <b>Matches(const wxChar *text, int flags = 0)</b> form is used,
 194         a wxStrlen() will be done internally if the regex library requires the
 195         length. When using Matches() in a loop the <b>Matches(text, flags, len)</b>
 196         form can be used instead, making it possible to avoid a wxStrlen() inside
 197         the loop.
 198
 199         May only be called after successful call to Compile().
 200     */
 201     bool Matches(const wxChar* text, int flags = 0) const;
 202     const bool Matches(const wxChar* text, int flags, size_t len) const;
 203     //@}
 204
 205     /**
 206         Matches the precompiled regular expression against the string @a text,
 207         returns @true if matches and @false otherwise.
 208
 209         @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL, see
 210         @ref wxRE_NOT_FLAGS.
 211
 212         May only be called after successful call to Compile().
 213     */
 214     const bool Matches(const wxString& text, int flags = 0) const;
 215
 216     /**
 217         Replaces the current regular expression in the string pointed to by
 218         @a text, with the text in @a replacement and return number of matches
 219         replaced (maybe 0 if none found) or -1 on error.
 220
 221         The replacement text may contain back references @c \\number which will be
 222         replaced with the value of the corresponding subexpression in the
 223         pattern match. @c \\0 corresponds to the entire match and @c \& is a
 224         synonym for it. Backslash may be used to quote itself or @c \& character.
 225
 226         @a maxMatches may be used to limit the number of replacements made, setting
 227         it to 1, for example, will only replace first occurrence (if any) of the
 228         pattern in the text while default value of 0 means replace all.
 229     */
 230     int Replace(wxString* text, const wxString& replacement,
 231                 size_t maxMatches = 0) const;
 232
 233     /**
 234         Replace all occurrences: this is actually a synonym for
 235         Replace().
 236
 237         @see ReplaceFirst()
 238     */
 239     int ReplaceAll(wxString* text, const wxString& replacement) const;
 240
 241     /**
 242         Replace the first occurrence.
 243     */
 244     int ReplaceFirst(wxString* text, const wxString& replacement) const;
 245 };
 246