[Chicken-hackers] pcre documentation

[Tony Sidaway]

Trying to document the new pcre functions.  Here's my first attempt.

string-search
 (string-search regexp str [start [end]]) ; find a match to a regular
expression anywhere within a string
 regexp: regular expression (compiled or string)
 str: string to be searched
 start: index of str at which to start (default 0)
 end: index of str at which to end (default end of str)
 Returns: #f if no match is found.  Otherwise a list containing the
full match and any submatches.

regexp-escape
 (regexp-escape str); escape all regular expression sequences in a string
 str: string containing regular expression sequences
 Returns: the escape string

regexp
 (regexp rx [caseless [extended [utf8]]])
 rx: string containing a perl-style regular expression
 caseless extended utf8: boolean option flags which default to #f
 Returns: compiled regular expression

string-match
 (string-match regexp str [start]) ; match a whole string to a
regular expression
 regexp: regular expression (compiled or string)
 str: string to match
 start: index of str at which to start (default 0)
 Returns: #f if it doesn't match.  Otherwise a list containing the
full match and any submatches.

regexp?
 (regexp? obj) ; regular expression identity predicate

string-search-positions
 (string-search-positions regexp str [start [end]]) ; string-search
but return indexes
 Returns: #f if it fails, else a list of (start end) lists of match
and submatches

string-match-positions
 (string-match-positions regexp str [start]) ; string-match but return indexes
 regexp: regular expression (compiled or string)
 str: string to match
 start: start index, defaults to 0
 end: end index, defaults to end of str
 Returns: #f if it fails, else a llist of (start end) lists of match
and submatches

string-substitute
 (string-substitute regexp subst str [occ]) ; substitute matching string
 regexp: regular expression (compiled or string)
 str: string to be searched
 occ: occurrence to substitute (default 1 for first occurrence)
 Returns: string with substitution performed

glob->regexp
 (glob->regexp g) ; convert syntax from glob to regular expression
 g: string containing a unix-style glob expression
 Returns: string containing the regular expression

string-split-fields
 (string-split-fields regexp str [mode [start]]) ; split fields of string
 regexp: regular expression to be used for split
 str: string to be split
 mode: #:infix, regexp is field separator, #:suffix, regexp is field
       terminator, otherwise regexp spans the fields.
 start: index of str at which fields start
 Returns: list of strings containing fields of str

string-substitute*
 (string-substitute* str smap [occ]) ; substitute matching strings
 str: string to be searched
 smap: list of pairs containing (regexp . subst)
 occ: occurrence to substitute (default 1 for first occurrence)
 Returns: string with all substitutions performed

grep
 (grep rx lst) ; filter list with a regular expression
 rx: regular expression
 lst: list of strings
 Returns: list of all members of lst that match rx