Next: , Previous: str_tokbqenize_free, Up: Strings


4.13 str_tokbq

split a quoted string at specified delimiters

Synopsis

     #include <suplib/str.h>
     
     
     
char *str_tokbq( char *string, const char *delim, const char *open_quote, const char *close_quote, char escape_char, int actions, struct str_tokbqdata *tbqd, int *error );

Parameters

char *string
the string to parse
const char *delim
the set of characters that delimit tokens
const char *open_quote
the set of characters that delimit opening quotes. e.g., ‘"'{[
const char *close_quote
the set of matching characters that delimit closing quotes. These must be in the same order as the opening characters in open_quote, e.g., ‘"'}]
char escape_char
the escape character
int actions
skip, restore, and escape modes
struct str_tokbqdata *tbqd
state information
int *error
returned error code

Description

This routine works like strtok, except that it understands escaped characters and quoted strings. It handles balanced quote characters (i.e. ‘[’ and ‘]’). It does not handle nested quotes.

It can collapse consecutive delimiter characters, or generate empty tokens. For example, if the delimiter is ‘,’, parsing of the string ",,a" would return three tokens, the first two empty strings. Additionally str_tokbq can be instructed to restore the parsed string to its initial state (normally it sticks ‘\0’ where the delimiter characters are).

str_tokbq is invoked multiple times, once per token. Unlike str_tok, str_tokbq stores all of its state information externally, in a caller provided structure. This must be initialized with str_tokbq_init before the first call to str_tokbq. The contents are unique to each parsed string.

Delimiters, quote characters, and the escape character may be changed between calls.

Each invocation of str_tokbq returns a pointer to the next token. If no more tokens are available, it returns NULL. If skip mode is on an empty string is considered to have no tokens. If skip mode is off, an empty string is considered to have a single token.

The actions flag is used to specify how to handle consecutive delimiters, string restoration, and whether to recognize escape sequence. The following flags (which may be combined with | are available:

STRTOK_ESCAPE
Recognize escape character sequences before quotes and delimiters. They are ignored elsewhere. The escape character is given by the escape_char parameter.
STRTOK_RESTORE str_tokbq replaces delimiter characters
in the passed string with ‘\0’ as it parses it. This flag directs str_tokbq to restore the character from the previous call. To fully restore the string to its original state, the caller must either repeatedly invoke str_tokbq until it returns a NULL or invoke the str_tokbq_restore function.
STRTOK_SKIP
If set, this indicates that consecutive delimiters are collapsed ("skipped").

Quotes need not be the first character in a token (e.g., ‘foo" "bar’) will be treated as one token, and can be either single (both forward and backwards) or double. To embed quotes in like-quoted strings, escape them (e.g., ‘foo"\""bar’).

Errors

On error, str_tokbq returns NULL and stores an error code in *error. The following errors are recognized:

EINVAL
There were unbalanced quotes.