+/****d* silcutil/SilcBufferFormatAPI/SilcBufferRegexFlags
+ *
+ * NAME
+ *
+ * typedef enum { ... } SilcBufferRegexFlags;
+ *
+ * DESCRIPTION
+ *
+ * Regular expression flags for SILC_STR_REGEX macro. The flags can be
+ * used to manipulate the behavior of the SILC_STR_REGEX. All flags
+ * may be combined unless otherwise stated.
+ *
+ * SOURCE
+ */
+typedef enum {
+ SILC_STR_REGEX_NONE = 0x00000000,
+
+ /* By default mismatch will be skipped. Set this flag if mismatch should
+ cause error and stopping of the formatting/unformatting. */
+ SILC_STR_REGEX_MISMATCH = 0x00000001,
+
+ /* By default only the first match is found. Set this flag to find
+ all matches. */
+ SILC_STR_REGEX_ALL = 0x00000002,
+
+ /* By default the buffer position is advanced to the position of the
+ first match. Set this flag if the buffer should not be advanced to
+ the match. */
+ SILC_STR_REGEX_NO_ADVANCE = 0x00000004,
+
+ /* By default SILC_STR_REGEX performs the match on the whole buffer. Set
+ this flag to make it behave like sed and match line by line. Each line
+ must end with '\n'. If buffer doesn't have '\n' it is considered to be
+ one line. Note that, any formatting done immediately after SILC_STR_REGEX
+ block with this flag will be formatted to the end of the buffer (after
+ last line). Use SILC_STR_OFFSET* macros to change the position if
+ needed. Also note that, any encoding macro inside the SILC_STR_REGEX
+ block will see only the matched line (including '\n'), instead of whole
+ buffer after the match. */
+ SILC_STR_REGEX_NL = 0x00000008,
+
+ /* Set this flag to not match the regular expression, but to match everything
+ else. When combined with SILC_STR_REGEX_NL this flag matches all other
+ lines except the ones with matching regular expression. */
+ SILC_STR_REGEX_NOT = 0x00000010,
+
+ /* By default the buffer is advanced to the first match and the rest of the
+ buffer remains as is. Set this flag to pass the exact match to the
+ SILC_STR_* macros in the SILC_STR_REGEX block; macros see the start of
+ the match and the end of the match, but not rest of the buffer (ie. with
+ match 'foo' the size of the buffer is 3 bytes). */
+ SILC_STR_REGEX_INCLUSIVE = 0x00000020,
+} SilcBufferRegexFlags;
+/***/
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_REGEX
+ *
+ * NAME
+ *
+ * #define SILC_STR_REGEX() ...
+ *
+ * DESCRIPTION
+ *
+ * Regular expression matching within the buffer.
+ *
+ * Formatting: SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
+ * Unformatting: SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
+ *
+ * SILC_STR_REGEX can be used to do regular expression matching within
+ * the SilcBuffer. When the string in the buffer matches the regular
+ * expression the position of the buffer is advanced to the position of
+ * the first match (rest of the buffer remains intact). If the regular
+ * expression does not match it is skipped, unless the flags specify
+ * otherwise. If flags are not needed they can be set to 0.
+ *
+ * In addition of matching regular expressions it can be used in a
+ * Stream Editor (sed) and Awk like fashion. The regular expression can be
+ * matched and then edited by any of the SILC_STR_* macros. The flags
+ * can be used to perform complex operations on the data. Some sed
+ * features that cannot be directly done with the flags can be done with
+ * SILC_STR_FUNC and other macros (the SILC_STR_FUNC could do anything
+ * after the match).
+ *
+ * The SILC_STR_REGEX itself is used as an opening of a block of encoding
+ * macros and must be closed with SILC_STR_END. This means that for
+ * each SILC_STR_REGEX there must be one SILC_STR_END. See examples for
+ * more information.
+ *
+ * The SILC_STR_REGEX can be used in buffer unformatting also to do
+ * string matching and parsing, but not editing, except with SILC_STR_FUNC
+ * macro, which can do anything caller wants.
+ *
+ * EXAMPLE
+ *
+ * // sed 's/foo/bar/', replace first foo with bar
+ * silc_buffer_format(buffer,
+ * SILC_STR_REGEX("foo", 0),
+ * SILC_STR_STRING("bar"),
+ * SILC_STR_END, SILC_STR_END);
+ *
+ * // sed 's/foo/bar/g', replace all foo's with bar
+ * silc_buffer_format(buffer,
+ * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
+ * SILC_STR_STRING("bar"),
+ * SILC_STR_END, SILC_STR_END);
+ *
+ * // sed '/baz/s/foo/bar/g, replace all foo's with bar on lines with baz
+ * silc_buffer_format(buffer,
+ * SILC_STR_REGEX("baz", SILC_STR_REGEX_NL),
+ * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
+ * SILC_STR_STRING("bar"),
+ * SILC_STR_END,
+ * SILC_STR_END, SILC_STR_END);
+ *
+ * // Print all lines that start with 'R'
+ * int print(SilcStack stack, SilcBuffer buf, void *value, void *context)
+ * {
+ * return fwrite(silc_buffer_data(buf), 1, silc_buffer_len(buf), stdout);
+ * }
+ *
+ * silc_buffer_unformat(buffer,
+ * SILC_STR_REGEX("^R", SILC_STR_REGEX_NL),
+ * SILC_STR_FUNC(print, NULL, NULL),
+ * SILC_STR_END, SILC_STR_END);
+ *
+ ***/
+#define SILC_STR_REGEX(regex, flags) SILC_PARAM_REGEX, (regex), (flags)