libs/glibmm2/glib/src/regex.hg

   1 /* Copyright (C) 2007 The glibmm Development Team
   2  *
   3  * This library is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU Library General Public
   5  * License as published by the Free Software Foundation; either
   6  * version 2 of the License, or (at your option) any later version.
   7  *
   8  * This library is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Library General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Library General Public
  14  * License along with this library; if not, write to the Free
  15  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16  */
  17
  18 _DEFS(glibmm,glib)
  19
  20 #include <glibmm/refptr.h>
  21 #include <glibmm/ustring.h>
  22 #include <glibmm/error.h>
  23 #include <glibmm/arrayhandle.h>
  24 #include <glib/gregex.h>
  25
  26 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  27 typedef struct _GRegex GRegex;
  28 #endif
  29
  30 namespace Glib
  31 {
  32
  33 _WRAP_ENUM(RegexCompileFlags, GRegexCompileFlags, NO_GTYPE)
  34 _WRAP_ENUM(RegexMatchFlags, GRegexMatchFlags, NO_GTYPE)
  35
  36 /** Exception class for Regex
  37  */
  38 _WRAP_GERROR(RegexError, GRegexError, G_REGEX_ERROR, NO_GTYPE)
  39
  40
  41 /** Perl-compatible regular expressions - matches strings against regular expressions.
  42  *
  43  * The Glib::Regex functions implement regular expression pattern matching using
  44  * syntax and semantics similar to Perl regular expression.
  45  *
  46  * Some functions accept a start_position argument, setting it differs from just
  47  * passing over a shortened string and setting REGEX_MATCH_NOTBOL in the case
  48  * of a pattern that begins with any kind of lookbehind assertion. For example,
  49  * consider the pattern "\Biss\B" which finds occurrences of "iss" in the middle
  50  * of words. ("\B" matches only if the current position in the subject is not a
  51  * word boundary.) When applied to the string "Mississipi" from the fourth byte,
  52  * namely "issipi", it does not match, because "\B" is always false at the
  53  * start of the subject, which is deemed to be a word boundary. However, if
  54  * the entire string is passed , but with start_position set to 4, it finds the
  55  * second occurrence of "iss" because it is able to look behind the starting point
  56  * to discover that it is preceded by a letter.
  57  *
  58  * Note that, unless you set the REGEX_RAW flag, all the strings passed to these
  59  * functions must be encoded in UTF-8. The lengths and the positions inside the
  60  *  strings are in bytes and not in characters, so, for instance,
  61  * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a single
  62  * character. If you set REGEX_RAW the strings can be non-valid UTF-8 strings
  63  * and a byte is treated as a character, so "\xc3\xa0" is two bytes and
  64  * two characters long.
  65  *
  66  * When matching a pattern, "\n" matches only against a "\n" character in the
  67  * string, and "\r" matches only a "\r" character. To match any newline sequence
  68  * use "\R". This particular group matches either the two-character sequence
  69  * CR + LF ("\r\n"), or one of the single characters LF (linefeed, U+000A, "\n"),
  70  *  VT (vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"), CR (carriage
  71  * return, U+000D, "\r"), NEL (next line, U+0085), LS (line separator, U+2028),
  72  * or PS (paragraph separator, U+2029).
  73  *
  74  * The behaviour of the dot, circumflex, and dollar metacharacters are affected
  75  * by newline characters, the default is to recognize any newline character (the
  76  * same characters recognized by "\R"). This can be changed with REGEX_NEWLINE_CR,
  77  * REGEX_NEWLINE_LF and REGEX_NEWLINE_CRLF compile options, and with
  78  * REGEX_MATCH_NEWLINE_ANY, REGEX_MATCH_NEWLINE_CR, REGEX_MATCH_NEWLINE_LF
  79  * and REGEX_MATCH_NEWLINE_CRLF match options. These settings are also
  80  * relevant when compiling a pattern if REGEX_EXTENDED is set, and an unescaped
  81  * "#" outside a character class is encountered. This indicates a comment that
  82  * lasts until after the next newline.
  83  *
  84  * Creating and manipulating the same Glib::Regex class from different threads is
  85  * not a problem as Glib::Regex does not modify its internal state between creation and
  86  * destruction, on the other hand Glib::MatchInfo is not threadsafe.
  87  *
  88  * The regular expressions low level functionalities are obtained through the
  89  * excellent PCRE library written by Philip Hazel.
  90  *
  91  * @newin2p14
  92  */
  93 class Regex
  94 {
  95   _CLASS_OPAQUE_REFCOUNTED(Regex, GRegex, NONE, g_regex_ref, g_regex_unref)
  96   _IGNORE(g_regex_ref, g_regex_unref)
  97 public:
  98
  99 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 100   static Glib::RefPtr<Glib::Regex> create(const Glib::ustring& pattern, RegexCompileFlags compile_options = static_cast<RegexCompileFlags>(0), RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0));
 101 #else
 102   static Glib::RefPtr<Glib::Regex> create(const Glib::ustring& pattern, RegexCompileFlags compile_options = static_cast<RegexCompileFlags>(0), RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0), std::auto_ptr<Glib::Error>& error);
 103 #endif /* !GLIBMM_EXCEPTIONS_ENABLED */
 104
 105   _WRAP_METHOD(Glib::ustring get_pattern() const, g_regex_get_pattern)
 106   _WRAP_METHOD(int get_max_backref() const, g_regex_get_max_backref)
 107   _WRAP_METHOD(int get_capture_count() const, g_regex_get_capture_count)
 108   _WRAP_METHOD(int get_string_number(const Glib::ustring& name) const, g_regex_get_string_number)
 109
 110   static Glib::ustring escape_string(const Glib::ustring& string);
 111
 112   _WRAP_METHOD(static bool match_simple(const Glib::ustring& pattern, const Glib::ustring& string, RegexCompileFlags compile_options = static_cast<RegexCompileFlags>(0), RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0)), g_regex_match_simple)
 113
 114   //TODO: _WRAP_METHOD(bool match(const Glib::ustring& string, RegexMatchFlags match_options = (RegexMatchFlags)0, GMatchInfo **match_info = 0), g_regex_match)
 115   bool match(const Glib::ustring& string, RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0));
 116
 117   //TODO: Wrap GMatchInfo as an iterator:
 118   //_WRAP_METHOD(bool match_full(const gchar* string, gssize string_len, int start_position, RegexMatchFlags match_options = (RegexMatchFlags)0, GMatchInfo** match_info = 0), g_regex_match_full, errthrow)
 119
 120 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 121   bool match(const Glib::ustring& string, int start_position, RegexMatchFlags match_options);
 122 #else
 123   bool match(const Glib::ustring& string, int start_position, RegexMatchFlags match_options, std::auto_ptr<Glib::Error>& error);
 124 #endif /* !GLIBMM_EXCEPTIONS_ENABLED */
 125
 126 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 127   bool match(const Glib::ustring& string, gssize string_len, int start_position, RegexMatchFlags match_options);
 128 #else
 129   bool match(const Glib::ustring& string, gssize string_len, int start_position, RegexMatchFlags match_options, std::auto_ptr<Glib::Error>& error);
 130 #endif /* !GLIBMM_EXCEPTIONS_ENABLED */
 131
 132   //TODO: _WRAP_METHOD(bool match_all(const Glib::ustring& string, RegexMatchFlags match_options = (RegexMatchFlags)0, GMatchInfo ** match_info = 0), g_regex_match_all)
 133   bool match_all(const Glib::ustring& string, RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0));
 134
 135   //TODO: _WRAP_METHOD(bool match_all_full(const gchar* string, gssize string_len, int start_position, RegexMatchFlags match_options = (RegexMatchFlags)0, GMatchInfo** match_info = 0), g_regex_match_all_full, errthrow)
 136
 137 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 138   bool match_all(const Glib::ustring& string, int start_position, RegexMatchFlags match_options);
 139 #else
 140   bool match_all(const Glib::ustring& string, int start_position, RegexMatchFlags match_options, std::auto_ptr<Glib::Error>& error);
 141 #endif /* !GLIBMM_EXCEPTIONS_ENABLED */
 142
 143 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 144   bool match_all(const Glib::ustring& string, gssize string_len, int start_position, RegexMatchFlags match_options);
 145 #else
 146   bool match_all(const Glib::ustring& string, gssize string_len, int start_position, RegexMatchFlags match_options, std::auto_ptr<Glib::Error>& error);
 147 #endif /* !GLIBMM_EXCEPTIONS_ENABLED */
 148
 149 #m4 _CONVERSION(`gchar**',`Glib::StringArrayHandle',`Glib::StringArrayHandle($3, Glib::OWNERSHIP_DEEP)')
 150
 151   _WRAP_METHOD(static Glib::StringArrayHandle split_simple(const Glib::ustring& pattern, const Glib::ustring& string, RegexCompileFlags compile_options = static_cast<RegexCompileFlags>(0), RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0)), g_regex_split_simple)
 152   _WRAP_METHOD(Glib::StringArrayHandle split(const Glib::ustring& string, RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0)), g_regex_split)
 153
 154   _WRAP_METHOD(Glib::StringArrayHandle split(const gchar* string, gssize string_len, int start_position, RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0), int max_tokens = 0) const, g_regex_split_full, errthrow)
 155
 156 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 157   Glib::StringArrayHandle split(const Glib::ustring& string, int start_position, RegexMatchFlags match_options, int max_tokens) const;
 158 #else
 159   Glib::StringArrayHandle split(const Glib::ustring& string, int start_position, RegexMatchFlags match_options, int max_tokens, std::auto_ptr<Glib::Error>& error) const;
 160 #endif /* !GLIBMM_EXCEPTIONS_ENABLED */
 161
 162   _WRAP_METHOD(Glib::ustring replace(const gchar* string, gssize string_len, int start_position, const Glib::ustring& replacement, RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0)), g_regex_replace, errthrow)
 163 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 164   Glib::ustring replace(const Glib::ustring& string, int start_position, const Glib::ustring& replacement, RegexMatchFlags match_options);
 165 #else
 166   Glib::ustring replace(const Glib::ustring& string, int start_position, const Glib::ustring& replacement, RegexMatchFlags match_options, std::auto_ptr<Glib::Error>& error);
 167 #endif /* !GLIBMM_EXCEPTIONS_ENABLED */
 168
 169   _WRAP_METHOD(Glib::ustring replace_literal(const gchar *string, gssize string_len, int start_position, const Glib::ustring& replacement, RegexMatchFlags match_options = static_cast<RegexMatchFlags>(0)), g_regex_replace_literal, errthrow)
 170 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 171   Glib::ustring replace_literal(const Glib::ustring& string, int start_position, const Glib::ustring& replacement, RegexMatchFlags match_options);
 172 #else
 173   Glib::ustring replace_literal(const Glib::ustring& string, int start_position, const Glib::ustring& replacement, RegexMatchFlags match_options, std::auto_ptr<Glib::Error>& error);
 174 #endif /* !GLIBMM_EXCEPTIONS_ENABLED */
 175
 176   _WRAP_METHOD(Glib::ustring replace_eval(const Glib::ustring& string, gssize string_len, int start_position, RegexMatchFlags match_options, GRegexEvalCallback eval,  gpointer user_data), g_regex_replace_eval, errthrow)
 177   _WRAP_METHOD(static bool check_replacement(const Glib::ustring& replacement, gboolean* has_references), g_regex_check_replacement, errthrow)
 178
 179 /* Match info */
 180 /*
 181 GRegex           *g_match_info_get_regex        (const GMatchInfo    *match_info);
 182 const gchar      *g_match_info_get_string       (const GMatchInfo    *match_info);
 183
 184 void              g_match_info_free             (GMatchInfo          *match_info);
 185   _WRAP_METHOD(bool g_match_info_next           (GMatchInfo          *match_info,
 186                                                  GError             **error);
 187   _WRAP_METHOD(bool g_match_info_matches                (const GMatchInfo    *match_info);
 188   _WRAP_METHOD(int g_match_info_get_match_count (const GMatchInfo    *match_info);
 189   _WRAP_METHOD(bool g_match_info_is_partial_match       (const GMatchInfo    *match_info);
 190 Glib::ustring g_match_info_expand_references(const GMatchInfo    *match_info,
 191                                                  Glib::ustring& string_to_expand,
 192                                                  GError             **error);
 193 Glib::ustring g_match_info_fetch                (const GMatchInfo    *match_info,
 194                                                  int match_num);
 195   _WRAP_METHOD(bool g_match_info_fetch_pos      (const GMatchInfo    *match_info,
 196                                                  int match_num,
 197                                                  int                 *start_pos,
 198                                                  int                 *end_pos);
 199 Glib::ustring g_match_info_fetch_named  (const GMatchInfo    *match_info,
 200                                                  Glib::ustring& name);
 201   _WRAP_METHOD(bool g_match_info_fetch_named_pos        (const GMatchInfo    *match_info,
 202                                                  Glib::ustring& name,
 203                                                  int                 *start_pos,
 204                                                  int                 *end_pos);
 205 gchar           **g_match_info_fetch_all        (const GMatchInfo    *match_info);
 206 */
 207 };
 208
 209 } // namespace Glib