BOOTSTRAP (kutils) functions
LIBRARY ROUTINE
kparse_string_scan_delimit - Break a string into an array of strings
LIBRARY CALL
char **kparse_string_scan_delimit(
char *data,
char *key1,
char *key2,
int mode,
char *delimiters,
char **key1_format,
char **key2_format,
ssize_t *num,
int *status)
INPUT
- data - the data string to search through
- key1 - the regular expression begin key to search for
- key2 - the regular expression end key to search for
- mode - tells the parser which mode to work in:
KIGNORE_CASE (match reguardless of case),
KLITERAL (match with case).
- delimiters - a string containing the delimiter characters.
OUTPUT
- key1_format - the address of a pointer to hold the returned
begin key that was matched. If key1 was
KPARSE_BOF, this address will set to NULL.
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 key1 matched will not be
returned.
- key2_format - the address of a pointer to hold the returned
end key that was matched. If key2 was
KPARSE_EOF, this address will be set to NULL.
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 key2 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 begin key)
KPARSE_NOEND (couldn't find end key)
KPARSE_DATAERR (data string was invalid)
KPARSE_PARTKEY (data ended with partial
match)
KPARSE_PARTEND (same as above, but on
end key)
KPARSE_NULLKEY (key was NULL)
KPARSE_NULLEND (end key was NULL)
KPARSE_SYNTAXKEY (key had an illegal
syntax)
KPARSE_SYNTAXEND (end key had an illegal
syntax)
RETURN VALUE
This routine returns a pointer to an array of items that were
just broke apart from the input data string. NULL is returned
when the kparse_string_scan() or kparse_string_delimit()
fails.
DESCRIPTION
This routine looks in a data string for an area of text
between two user specified match keys, then it delimits
the section of text in to an array of smaller strings
based on a set of character delimiters. Delimiters
can be escaped by a '\\' if they need to appear in the
text section. This routine is a combination of the
calls kparse_string_scan() and kparse_string_delimit().
This routine cleans up the entries in the array via
a kstring_cleanup() call.
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 the key1_format
and key2_format parameters. Thus, the user should pass in
addresses of an unused character pointers for them. The
calling routine is responsible for freeing the space
malloc'ed for the key1_format and key2_format parameters.
This routine mallocs the space for the return string;
and hence, is responsible for freeing the that space
via kfree_and_NULL() when they are done with it.
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 the data file 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_scan(kutils), kparse_string_delimit(kutils), karray_add(kutils),
karray_free(kutils)
COPYRIGHT
Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.