BOOTSTRAP (kutils) functions


LIBRARY ROUTINE

kparse_file_scan - scan a Khoros Data Transport Stream for a specific section of data

LIBRARY CALL

char *kparse_file_scan(
   kfile *file,
   char  *key1,
   char  *key2,
   int   mode,
   char  **key1_format,
   char  **key2_format,
   int   *status)

INPUT

OUTPUT

RETURN VALUE

This routine returns a pointer to a malloc'ed string containing the text between the two matched keys. If an error occured during the search, it will return NULL, and the error status is set appropriately. This current file position is set to the

DESCRIPTION

This routine finds a section of data, marked by begin and end keys, out of a Khoros Data Transport Stream that was opened for input. When the begin and end keys are matched, this routine allocates a string big enough to hold the data between the keys, and then copies the data into that space. A pointer to this string is then returned. This routine makes calls to kparse_file_search() which handles the regular expression parsing for the begin and end match keys. On a successful search, the current position in the Khoros Data Transport Stream will be set to the character directly following the last character matched by the end key.

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. .ds bs "\\\\"

\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.

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.

MODIFICATION

none

FILES

$BOOTSTRAP/objects/library/kutils/src/parse.c

SEE ALSO

kparse_file_search(kutils), kparse_string_search(kutils)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.