Regexp Functions
----------------
By default, Guile supports POSIX extended regular expressions. That
means that the characters `(', `)', `+' and `?' are special, and must
be escaped if you wish to match the literal characters.
This regular expression interface was modeled after that implemented by
SCSH, the Scheme Shell. It is intended to be upwardly compatible with
SCSH regular expressions.
- procedure: string-match pattern str [start]
Compile the string PATTERN into a regular expression and compare
it with STR. The optional numeric argument START specifies the
position of STR at which to begin matching.
`string-match' returns a "match structure" which describes what,
if anything, was matched by the regular expression. Note:Match
Structures. If STR does not match PATTERN at all,
`string-match' returns `#f'.
Each time `string-match' is called, it must compile its PATTERN
argument into a regular expression structure. This operation is
expensive, which makes `string-match' inefficient if the same regular
expression is used several times (for example, in a loop). For better
performance, you can compile a regular expression in advance and then
match strings against the compiled regexp.
- primitive: make-regexp pat . flags
Compile the regular expression described by STR, and return the
compiled regexp structure. If STR does not describe a legal
regular expression, `make-regexp' throws a
`regular-expression-syntax' error.
The FLAG arguments change the behavior of the compiled regexp.
The following flags may be supplied:
`regexp/icase'
Consider uppercase and lowercase letters to be the same when
matching.
`regexp/newline'
If a newline appears in the target string, then permit the
`^' and `$' operators to match immediately after or
immediately before the newline, respectively. Also, the `.'
and `[^...]' operators will never match a newline character.
The intent of this flag is to treat the target string as a
buffer containing many lines of text, and the regular
expression as a pattern that may match a single one of those
lines.
`regexp/basic'
Compile a basic ("obsolete") regexp instead of the extended
("modern") regexps that are the default. Basic regexps do not
consider `|', `+' or `?' to be special characters, and
require the `{...}' and `(...)' metacharacters to be
backslash-escaped (Note:Backslash Escapes). There are
several other differences between basic and extended regular
expressions, but these are the most significant.
`regexp/extended'
Compile an extended regular expression rather than a basic
regexp. This is the default behavior; this flag will not
usually be needed. If a call to `make-regexp' includes both
`regexp/basic' and `regexp/extended' flags, the one which
comes last will override the earlier one.
- primitive: regexp-exec rx str [start [flags]]
Match the compiled regular expression REGEXP against `str'. If
the optional integer START argument is provided, begin matching
from that position in the string. Return a match structure
describing the results of the match, or `#f' if no match could be
found.
- primitive: regexp? x
Return `#t' if OBJ is a compiled regular expression, or `#f'
otherwise.
Regular expressions are commonly used to find patterns in one string and
replace them with the contents of another string.
- procedure: regexp-substitute port match [item...]
Write to the output port PORT selected contents of the match
structure MATCH. Each ITEM specifies what should be written, and
may be one of the following arguments:
* A string. String arguments are written out verbatim.
* An integer. The submatch with that number is written.
* The symbol `pre'. The portion of the matched string preceding
the regexp match is written.
* The symbol `post'. The portion of the matched string
following the regexp match is written.
PORT may be `#f', in which case nothing is written; instead,
`regexp-substitute' constructs a string from the specified ITEMs
and returns that.
- procedure: regexp-substitute/global port regexp target [item...]
Similar to `regexp-substitute', but can be used to perform global
substitutions on STR. Instead of taking a match structure as an
argument, `regexp-substitute/global' takes two string arguments: a
REGEXP string describing a regular expression, and a TARGET string
which should be matched against this regular expression.
Each ITEM behaves as in REGEXP-SUBSTITUTE, with the following
exceptions:
* A function may be supplied. When this function is called, it
will be passed one argument: a match structure for a given
regular expression match. It should return a string to be
written out to PORT.
* The `post' symbol causes `regexp-substitute/global' to recurse
on the unmatched portion of STR. This _must_ be supplied in
order to perform global search-and-replace on STR; if it is
not present among the ITEMs, then `regexp-substitute/global'
will return after processing a single match.