Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2007 Pekka Riikonen
+ Copyright (C) 1997 - 2008 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
*/
-/****h* silcutil/SILC Buffer Format Interface
+/****h* silcutil/Buffer Format Interface
*
* DESCRIPTION
*
* into specified data types. It is especially useful to encode packets,
* protocol payloads and such.
*
- * As the SilcBuffer API is not thread-safe these routines may not be used
+ * It also provides many advanced features like calling user specified
+ * encoder and decoder functions that are free to do anything to the buffer.
+ * The API also provides powerful regular expression matching capabilities
+ * within the buffer, enabling caller to not only match regular expressions
+ * but to make the API behave like Stream Editor (Sed) and Awk. The buffer
+ * can be matched against regular expression and then edited. Caller can
+ * do anything they want to the buffer after a match. The SILC_STR_REGEX
+ * macro provides many different flags that can change the behavior of the
+ * matching, with capabilities to also mimic Sed behavior.
+ *
+ * As the SilcBuffer context is not thread-safe these routines may not be used
* in multithreaded environment with a same SilcBuffer context without
* concurrency control.
*
*
* SilcBufferStruct buffer;
*
+ * // Encode buffer
* memset(&buffer, 0, sizeof(buffer));
* ret = silc_buffer_format(&buffer,
* SILC_STR_UINT32(intval),
* if (ret < 0)
* error;
*
+ * // 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);
+ *
***/
#ifndef SILCBUFFMT_H
#define SILCBUFFMT_H
-/****f* silcutil/SilcBufferFormatAPI/SilcBufferFormatFunc
+/****f* silcutil/SilcBufferFormatFunc
*
* SYNOPSIS
*
typedef int (*SilcBufferFormatFunc)(SilcStack stack, SilcBuffer buffer,
void *value, void *context);
-/****f* silcutil/SilcBufferFormatAPI/SilcBufferUnformatFunc
+/****f* silcutil/SilcBufferUnformatFunc
*
* SYNOPSIS
*
/* Prototypes */
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
+/****f* silcutil/silc_buffer_format
*
* SYNOPSIS
*
* Formats a buffer from a variable argument list. Returns -1 if the
* system is out of memory and the length of the formatted buffer otherwise.
* The buffer is enlarged automatically during formatting, if it doesn't
- * already have enough space.
+ * already have enough space. Sets silc_errno in case of error.
*
* EXAMPLE
*
* silc_buffer_purge(&buffer);
*
* // Dynamically allocated zero size buffer
- * SilcBuffer buf;
+ * SilcBuffer buf;
* buf = silc_buffer_alloc(0);
* ret = silc_buffer_format(buf,
* SILC_STR_UINT32(intval),
***/
int silc_buffer_format(SilcBuffer dst, ...);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat
+/****f* silcutil/silc_buffer_sformat
*
* SYNOPSIS
*
*
* Same as silc_buffer_format but uses `stack' to allocate the memory.
* if `stack' is NULL reverts back to silc_buffer_format call. Returns
- * -1 if system is out of memory.
+ * -1 if system is out of memory. Sets silc_errno in case of error.
*
* Note that this call consumes the `stack'. The caller should push the
* stack before calling the function and pop it later.
***/
int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
+/****f* silcutil/silc_buffer_format_vp
*
* SYNOPSIS
*
***/
int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat_vp
+/****f* silcutil/silc_buffer_sformat_vp
*
* SYNOPSIS
*
*
* Same as silc_buffer_format_vp but uses `stack' to allocate the memory.
* if `stack' is NULL reverts back to silc_buffer_format_vp call. Returns
- * -1 if system is out of memory.
+ * -1 if system is out of memory. Sets silc_errno in case of error.
*
* Note that this call consumes the `stack'. The caller should push the
* stack before calling the function and pop it later.
***/
int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list ap);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
+/****f* silcutil/silc_buffer_unformat
*
* SYNOPSIS
*
* DESCRIPTION
*
* Unformats a buffer from a variable argument list. Returns -1 on error
- * and the length of the unformatted buffer otherwise.
+ * and the length of the unformatted buffer otherwise. Sets silc_errno
+ * in case of error.
*
* EXAMPLE
*
***/
int silc_buffer_unformat(SilcBuffer src, ...);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat
+/****f* silcutil/silc_buffer_sunformat
*
* SYNOPSIS
*
***/
int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp
+/****f* silcutil/silc_buffer_unformat_vp
*
* SYNOPSIS
*
***/
int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat_vp
+/****f* silcutil/silc_buffer_sunformat_vp
*
* SYNOPSIS
*
***/
int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_strformat
+/****f* silcutil/silc_buffer_strformat
*
* SYNOPSIS
*
* be end with SILC_STRFMT_END argument. This allows that a string in
* the list can be NULL, in which case it is skipped. This automatically
* allocates the space for the buffer data but `dst' must be already
- * allocated by the caller. Returns -1 if system is out of memory.
+ * allocated by the caller. Returns -1 if system is out of memory and
+ * sets silc_errno.
*
* EXAMPLE
*
***/
int silc_buffer_strformat(SilcBuffer dst, ...);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sstrformat
+/****f* silcutil/silc_buffer_sstrformat
*
* SYNOPSIS
*
* allocates the space for the buffer data but `dst' must be already
* allocated by the caller. This function is equivalent to
* silc_buffer_strformat but allocates memory from `stack'. Returns -1
- * if system is out of memory.
+ * if system is out of memory and sets silc_errno.
*
* Note that this call consumes the `stack'. The caller should push the
* stack before calling the function and pop it later.
***/
int silc_buffer_sstrformat(SilcStack stack, SilcBuffer dst, ...);
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT8
+/****d* silcutil/SILC_STR_SINT8
*
* NAME
*
*
* One 8-bit signed integer.
*
- * Formatting: SILC_STR_SINT8(SilcInt8)
- * Unformatting: SILC_STR_SINT8(SilcInt8 *)
+ * Formatting: SILC_STR_SINT8(SilcInt8)
+ * Unformatting: SILC_STR_SINT8(SilcInt8 *)
*
***/
#define SILC_STR_SINT8(x) SILC_PARAM_SINT8, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT8
+/****d* silcutil/SILC_STR_UINT8
*
* NAME
*
*
* One 8-bit unsigned integer.
*
- * Formatting: SILC_STR_UINT8(SilcUInt8)
- * Unformatting: SILC_STR_UINT8(SilcUInt8 *)
+ * Formatting: SILC_STR_UINT8(SilcUInt8)
+ * Unformatting: SILC_STR_UINT8(SilcUInt8 *)
*
***/
#define SILC_STR_UINT8(x) SILC_PARAM_UINT8, (x)
#define SILC_STR_SI_CHAR(x) SILC_PARAM_SINT8, (x)
#define SILC_STR_UI_CHAR(x) SILC_PARAM_UINT8, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT16
+/****d* silcutil/SILC_STR_SINT16
*
* NAME
*
*
* SilcInt16.
*
- * Formatting: SILC_STR_SINT16(SilcInt16)
- * Unformatting: SILC_STR_SINT16(SilcInt16 *)
+ * Formatting: SILC_STR_SINT16(SilcInt16)
+ * Unformatting: SILC_STR_SINT16(SilcInt16 *)
*
***/
#define SILC_STR_SINT16(x) SILC_PARAM_SINT16, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT16
+/****d* silcutil/SILC_STR_UINT16
*
* NAME
*
*
* SilcUInt16.
*
- * Formatting: SILC_STR_UINT16(SilcUInt16)
- * Unformatting: SILC_STR_UINT16(SilcUInt16 *)
+ * Formatting: SILC_STR_UINT16(SilcUInt16)
+ * Unformatting: SILC_STR_UINT16(SilcUInt16 *)
*
***/
#define SILC_STR_UINT16(x) SILC_PARAM_UINT16, (x)
#define SILC_STR_SI_SHORT(x) SILC_PARAM_SINT16, (x)
#define SILC_STR_UI_SHORT(x) SILC_PARAM_UINT16, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT32
+/****d* silcutil/SILC_STR_SINT32
*
* NAME
*
*
* SilcInt32.
*
- * Formatting: SILC_STR_SINT32(SilcInt32)
- * Unformatting: SILC_STR_SINT32(SilcInt32 *)
+ * Formatting: SILC_STR_SINT32(SilcInt32)
+ * Unformatting: SILC_STR_SINT32(SilcInt32 *)
*
***/
#define SILC_STR_SINT32(x) SILC_PARAM_SINT32, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT32
+/****d* silcutil/SILC_STR_UINT32
*
* NAME
*
*
* SilcUInt32.
*
- * Formatting: SILC_STR_UINT32(SilcUInt32)
- * Unformatting: SILC_STR_UINT32(SilcUInt32 *)
+ * Formatting: SILC_STR_UINT32(SilcUInt32)
+ * Unformatting: SILC_STR_UINT32(SilcUInt32 *)
*
***/
#define SILC_STR_UINT32(x) SILC_PARAM_UINT32, (x)
#define SILC_STR_SI_INT(x) SILC_PARAM_SINT32, (x)
#define SILC_STR_UI_INT(x) SILC_PARAM_UINT32, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT64
+/****d* silcutil/SILC_STR_SINT64
*
* NAME
*
*
* SilcInt64.
*
- * Formatting: SILC_STR_SINT64(SilcInt64)
- * Unformatting: SILC_STR_SINT64(SilcInt64 *)
+ * Formatting: SILC_STR_SINT64(SilcInt64)
+ * Unformatting: SILC_STR_SINT64(SilcInt64 *)
*
***/
#define SILC_STR_SI_INT64(x) SILC_PARAM_SINT64, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT64
+/****d* silcutil/SILC_STR_UINT64
*
* NAME
*
*
* SilcUInt64.
*
- * Formatting: SILC_STR_UINT64(SilcUInt64)
- * Unformatting: SILC_STR_UINT64(SilcUInt64 *)
+ * Formatting: SILC_STR_UINT64(SilcUInt64)
+ * Unformatting: SILC_STR_UINT64(SilcUInt64 *)
*
***/
#define SILC_STR_UI_INT64(x) SILC_PARAM_UINT64, (x)
#define SILC_STR_SI_INT64(x) SILC_PARAM_SINT64, (x)
#define SILC_STR_UI_INT64(x) SILC_PARAM_UINT64, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_STRING
+/****d* silcutil/SILC_STR_STRING
+ *
+ * NAME
+ *
+ * #define SILC_STR_STRING() ...
+ *
+ * DESCRIPTION
+ *
+ * Encode NULL terminated string. Use this only for formatting.
+ *
+ * Formatting: SILC_STR_STRING(char *)
+ *
+ * For unformatting use one of the SILC_STR_*_STRING macros, which
+ * automatically gets the length of the string from the buffer. Note
+ * SILC_STR_STRING does not save the length of the string into the buffer.
+ * The caller must do that in order for the unformatting macros to work.
+ *
+ * EXAMPLE
+ *
+ * Formatting: ..., SILC_STR_UINT32(strlen(string)),
+ * SILC_STR_STRING(string), ...
+ * Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
+ *
+ ***/
+#define SILC_STR_STRING(x) SILC_PARAM_UI8_STRING, (x)
+
+/****d* silcutil/SILC_STR_*_STRING
*
* NAME
*
* NULL terminated because strlen() will be used to get the length of
* the string.
*
- * Formatting: SILC_STR_UI32_STRING(unsigned char *)
- * Unformatting: SILC_STR_UI32_STRING(unsigned char **)
+ * Formatting: SILC_STR_UI32_STRING(unsigned char *)
+ * Unformatting: SILC_STR_UI32_STRING(unsigned char **)
*
* Unformatting procedure will check for length of the string from the
* buffer before trying to get the string out. Thus, one *must* format the
- * length as UI_INT or UI_SHORT into the buffer *before* formatting the
- * actual string to the buffer, and, in unformatting one must ignore the
+ * length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
+ * the actual string to the buffer, and, in unformatting one ignores the
* length of the string because unformatting procedure will take it
* automatically.
*
- * Example:
+ * EXAMPLE
*
- * Formatting: ..., SILC_STR_UI_INT(strlen(string)),
+ * Formatting: ..., SILC_STR_UINT32(strlen(string)),
* SILC_STR_UI32_STRING(string), ...
* Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
*
* I.e., you can ignore the formatted length field in unformatting.
*
* UI8, UI16 and UI32 means that the length is considered to be
- * either char (8 bits), short (16 bits) or int (32 bits) in
- * unformatting.
+ * either UINT8, UINT16 or UINT32 in unformatting.
*
* _ALLOC routines automatically allocates memory for the variable sent
* as argument in unformatting.
#define SILC_STR_UI32_STRING(x) SILC_PARAM_UI32_STRING, (x)
#define SILC_STR_UI32_STRING_ALLOC(x) SILC_PARAM_UI32_STRING | SILC_PARAM_ALLOC, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_NSTRING
+/****d* silcutil/SILC_STR_*_NSTRING
*
* NAME
*
*
* Unsigned string. Second argument is the length of the string.
*
- * Formatting: SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
- * Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
+ * Formatting: SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
+ * Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
*
* Unformatting procedure will check for length of the string from the
* buffer before trying to get the string out. Thus, one *must* format the
- * length as UI_INT or UI_SHORT into the buffer *before* formatting the
- * actual string to the buffer, and, in unformatting one must ignore the
+ * length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
+ * the actual string to the buffer, and, in unformatting one ignores the
* length of the string because unformatting procedure will take it
* automatically.
*
- * Example:
+ * EXAMPLE
*
- * Formatting: ..., SILC_STR_UI_INT(strlen(string)),
+ * Formatting: ..., SILC_STR_UINT32(strlen(string)),
* SILC_STR_UI32_NSTRING(string, strlen(string)), ...
* Unformatting: ..., SILC_STR_UI32_NSTRING(&string, &len), ...
*
* argument (&len in above example).
*
* UI8, UI16 and UI32 means that the length is considered to be
- * either char (8 bits), short (16 bits) or int (32 bits) in
- * unformatting.
+ * either UINT8, UINT16 or UINT32 in unformatting.
*
* _ALLOC routines automatically allocates memory for the variable sent
* as argument in unformatting.
#define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
SILC_PARAM_UI32_NSTRING | SILC_PARAM_ALLOC, (x), (l)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_DATA
+/****d* silcutil/SILC_STR_DATA
*
* NAME
*
*
* Binary data formatting. Second argument is the length of the data.
*
- * Formatting: SILC_STR_DATA(unsigned char *, SilcUInt32)
- * Unformatting: SILC_STR_DATA(unsigned char **, SilcUInt32)
+ * Formatting: SILC_STR_DATA(unsigned char *, SilcUInt32)
+ * Unformatting: SILC_STR_DATA(unsigned char **, SilcUInt32)
*
* This type can be used to take arbitrary size data block from the buffer
* by sending the requested amount of bytes as argument.
#define SILC_STR_UI_XNSTRING(x, l) SILC_PARAM_UICHAR, (x), (l)
#define SILC_STR_UI_XNSTRING_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_BUFFER
+/****d* silcutil/SILC_STR_BUFFER
*
* NAME
*
*
* SilcBuffer formatting.
*
- * Formatting: SILC_STR_BUFFER(SilcBuffer)
- * Unformatting: SILC_STR_BUFFER(SilcBuffer)
+ * Formatting: SILC_STR_BUFFER(SilcBuffer)
+ * Unformatting: SILC_STR_BUFFER(SilcBuffer)
*
* This type can be used to format and unformat SilcBuffer. Note that, the
* length of the buffer will be automatically encoded into the buffer as
#define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
#define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER | SILC_PARAM_ALLOC, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_FUNC
+/****d* silcutil/SILC_STR_REPLACE
+ *
+ * NAME
+ *
+ * #define SILC_STR_REPLACE(unsigned char *data, SilcUInt32 len) ...
+ *
+ * DESCRIPTION
+ *
+ * Encode the `data' of length of `len' bytes into the buffer, replacing
+ * existing data.
+ *
+ * If the length of the current data area is equal to `len' the data area
+ * is replaced with `data'.
+ *
+ * If `len' is longer than the data area, it will be enlarged to fit the
+ * `data'. If there is data in the tail area, it will not be replaced,
+ * but the buffer is enlarged and the old tail area will be copied to the
+ * new tail area, thus preserving any data in the buffer (the data is
+ * in effect appended to the current data area).
+ *
+ * If `len' is shorter than than the data area, only the bytes in `data'
+ * are replaced, and rest are deleted from the data area. The buffer size
+ * is also reduced but no other data is lost in the process.
+ *
+ * If `len' is 0 but `data' is non-NULL, this will delete all bytes from
+ * the current data area. If `data' is NULL this macro has no effect to
+ * the buffer.
+ *
+ * Use this only for formatting.
+ *
+ * Formatting: SILC_STR_REPLACE(unsigned char *, SilcUInt32)
+ *
+ * EXAMPLE
+ *
+ * Before replacing
+ * -------------------------
+ * | head | 12345 | 67890 |
+ * -------------------------
+ *
+ * After replacing with 12345XXX (appends)
+ * ----------------------------
+ * | head | 12345XXX | 67890 |
+ * ----------------------------
+ *
+ * After replacing with YYY (deletes)
+ * -----------------------
+ * | head | YYY | 67890 |
+ * -----------------------
+ *
+ ***/
+#define SILC_STR_REPLACE(x, l) SILC_PARAM_UICHAR | SILC_PARAM_REPLACE, (x), (l)
+
+/****d* silcutil/SILC_STR_FUNC
*
* NAME
*
*
* DESCRIPTION
*
- * SilcBuffer formatting.
+ * Formatting and unformatting of arbitrary data.
*
- * Formatting: SILC_STR_FUNC(function, void *value, void *context)
- * Unformatting: SILC_STR_FUNC(function, void **value, void *context)
+ * Formatting: SILC_STR_FUNC(function, void *value, void *context)
+ * Unformatting: SILC_STR_FUNC(function, void **value, void *context)
*
* This type can be used to call the `function' of the type
* SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
#define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
func, (val), (context)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
+/****d* silcutil/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. Skipping means that none of the
+ operations inside the SILC_STR_REGEX are executed. 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/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.
+ *
+ * Typically the following encoding macros are used with SILC_STR_REGEX:
+ * SILC_STR_REPLACE, SILC_STR_STRING and SILC_STR_FUNC. If you use
+ * SILC_STR_REPLACE always set SILC_STR_REGEX_INCLUSIVE.
+ *
+ * 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/barbar/g', replace all foo's with barbar, without
+ * // overwriting any data in the buffer, but appending it. The match
+ * // must be inclusive to make appending work.
+ * silc_buffer_format(buffer,
+ * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL |
+ * SILC_STR_REGEX_INCLUSIVE),
+ * SILC_STR_REPLACE("barbar", 5),
+ * SILC_STR_END, SILC_STR_END);
+ *
+ * // sed 's/foo/B/', replace foo with B, deleting rest of the match from
+ * // the buffer. The match must be inclusive to make deleting work.
+ * silc_buffer_format(buffer,
+ * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL |
+ * SILC_STR_REGEX_INCLUSIVE),
+ * SILC_STR_REPLACE("B", 1),
+ * 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)
+
+/****d* silcutil/SILC_STR_DELETE
+ *
+ * NAME
+ *
+ * #define SILC_STR_DELETE(n) ...
+ *
+ * DESCRIPTION
+ *
+ * Deletes bytes from the buffer by moving data in order to delete it.
+ * The size of the buffer is also reduced, but no data is lost in the
+ * process.
+ *
+ * The `n' specifies the number of bytes to delete from the current
+ * data area. If `n' is -1 this deletes all bytes from the data area.
+ * This effectively moves the data from the tail area into the current
+ * data area. The length of the data area after this is 0.
+ *
+ * Use this only for formatting.
+ *
+ * Formatting: SILC_STR_DELETE(int bytes)
+ *
+ ***/
+#define SILC_STR_DELETE(x) SILC_PARAM_DELETE, (x)
+
+/****d* silcutil/SILC_STR_OFFSET
*
* NAME
*
* or backwards (negative offset). It can be used to for example skip
* some types during unformatting.
*
- * Example:
+ * EXAMPLE
*
* ..., SILC_STR_OFFSET(5), ...
* ..., SILC_STR_OFFSET(-3), ...
***/
#define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_ADVANCE
+/****d* silcutil/SILC_STR_OFFSET_START
+ *
+ * NAME
+ *
+ * #define SILC_STR_OFFSET_START ...
+ *
+ * DESCRIPTION
+ *
+ * Moves the buffer position to the start of the data area.
+ *
+ * EXAMPLE
+ *
+ * ..., SILC_STR_OFFSET_START, ...
+ *
+ ***/
+#define SILC_STR_OFFSET_START SILC_PARAM_OFFSET_START
+
+/****d* silcutil/SILC_STR_OFFSET_END
+ *
+ * NAME
+ *
+ * #define SILC_STR_OFFSET_END ...
+ *
+ * DESCRIPTION
+ *
+ * Moves the buffer position to the end of the data area.
+ *
+ * EXAMPLE
+ *
+ * ..., SILC_STR_OFFSET_END, ...
+ *
+ ***/
+#define SILC_STR_OFFSET_END SILC_PARAM_OFFSET_END
+
+/****d* silcutil/SILC_STR_ADVANCE
*
* NAME
*
***/
#define SILC_STR_ADVANCE SILC_PARAM_ADVANCE
-/****d* silcutil/SilcBufferFormatAPI/SILC_STR_END
+/****d* silcutil/SILC_STR_END
*
* NAME
*
***/
#define SILC_STR_END SILC_PARAM_END
-/****d* silcutil/SilcBufferFormatAPI/SILC_STRFMT_END
+/****d* silcutil/SILC_STRFMT_END
*
* NAME
*