BOOTSTRAP (kutils) functions
LIBRARY ROUTINE
kparse_string_search_delimit - break up a line data into an array of strings based on some set of delimiters
LIBRARY CALL
char **kparse_string_search_delimit(
char *data,
char *key,
int mode,
char *delimiters,
char *cont,
char **key_format,
ssize_t *num,
int *status)
INPUT
- data - input string to search and delimit.
- key - regular expression key to search for.
- mode - tells the parser which mode to work in:
KIGNORE_CASE Ignore case on a-z and A-Z
KLITERAL Use case information on
a-z and A-Z
- delimiters - a string containing the delimiter characters.
- cont - a string containing the continuation characters.
OUTPUT
- key_format - the address of a pointer to hold the returned
key that was matched. Sufficient space for
the returned string will be allocated if you
pass in a valid pointer. Note that if this
parameter is passed in as NULL, this routine
will ignore it, and the string that key matched
will not be returned.
- num - returns the number of items in the array, -1
on error
- status - error status of the search. It can be
one of the following:
KPARSE_OK (parse ok, return data
valid)
KPARSE_NOKEY (couldn't find key)
KPARSE_PARTKEY (data ends on a partial
match)
KPARSE_NULLKEY (key was NULL)
KPARSE_SYNTAXKEY (key had an illegal syntax)
RETURN VALUE
This routine returns a pointer to an array of items we just
broke apart from the input data string. NULL is returned
when the kparse_string_search() or kparse_string_delimit()
fails.
DESCRIPTION
This routine looks for a user specified key with a
call to kparse_string_search(); then, it
parses the rest of the line, up to a '\\n', according to the
user's list of delimiters by calling kparse_string_delimit().
The user can specify a set of continuation characters.
Continuation characters must appear as the last character
of the line. Line continuation can be chained together
at the end of each consecutive line you want this routine
to parse as a single line.
ADDITIONAL INFORMATION
The regular expression syntax supported by the parser
is: '.', '*', '[..]', '[^..]', '$', '^', and '\\'. The explainations
for each syntax is explained below.
.
Match any single character except newline
*
Match the preceding character or ranger of characters 0 or more times. This
matching includes items specified within a [...] construct.
[...] or [^...]
Matches any one character contained within the brackets. If the first
character after the is a ']', then it is included as a character to match.
If the first character after the '[' is a '^', then it will match all characters
NOT included within the []. Finally, the '-' will indicate a range of
characters. For example, [a-z] specifies all characters between and
including the ascii values 'a' and 'z'. If the '-' follows the '[', or is
right before the ']', then it is interpreted literally.
^
If it is the first character of the regular expression, it matches the
beginning of the line.
$
If it is the last character of the regular expression, it matches the end of
line. However, it does NOT put the \\n in your key when the matched key is
returned.
\e
This escapes the meaning of a special character.
EXAMPLES
none
SIDE EFFECTS
This routine mallocs data and sets the value of key_format
parameter. Thus, the user should pass in an address of
an unused character pointer. The calling routine is
responsible for freeing the space malloc'ed for
the key_format parameter.
This routine creates a new array of strings, and the
calling routine is responsible for freeing the space
allocated while creating the array via a call to
karray_free().
RESTRICTIONS
It does not support the following regular expression
constructs: or'ing '|', grouping of regular expressions '()',
match one or more times '+', or match n to m times '\\{n,m\\}'.
Finally, the '\\number' and '\\(\\)' constructs have no meaning
for these routines, so they are not supported either.
Search keys and data strings should not contain the
values '\\001', '\\002', '\\003', or '\\004',
because these values are used as special search parameters
by the parser.
MODIFICATION
none
FILES
$BOOTSTRAP/objects/library/kutils/src/parse.c
SEE ALSO
kparse_string_search(kutils), kparse_string_delimit(kutils), karray_add(kutils),
karray_free(kutils)
COPYRIGHT
Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.