— Scheme 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. See Match Structures. If str does not match pattern at all, string-match returns #f.

     (string-match "[0-9][0-9][0-9][0-9]" "blah2002")
     => #("blah2002" (4 . 8))
     
     (string-match "[A-Za-z]" "123456")
     => #f

— Scheme Procedure: make-regexp pat flag...
— C Function: scm_make_regexp (pat, flaglst)

Compile the regular expression described by pat, and return the compiled regexp structure. If pat does not describe a legal regular expression, make-regexp throws a regular-expression-syntax error.

The flag arguments change the behavior of the compiled regular expression. The following values may be supplied:

— Variable: regexp/icase

Consider uppercase and lowercase letters to be the same when matching.

— Variable: 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.

— Variable: 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 (see Backslash Escapes). There are several other differences between basic and extended regular expressions, but these are the most significant.

— Variable: 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.

— Scheme Procedure: regexp-exec rx str [start [flags]]
— C Function: scm_regexp_exec (rx, str, start, flags)

Match the compiled regular expression rx 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.

The flags argument changes the matching behavior. The following flag values may be supplied, use logior (see Bitwise Operations) to combine them,

— Variable: regexp/notbol

Consider that the start offset into str is not the beginning of a line and should not match operator `^'.

If rx was created with the regexp/newline option above, `^' will still match after a newline in str.

— Variable: regexp/noteol

Consider that the end of str is not the end of a line and should not match operator `$'.

If rx was created with the regexp/newline option above, `$' will still match before a newline in str.

     ;; Regexp to match uppercase letters
     (define r (make-regexp "[A-Z]*"))
     
     ;; Regexp to match letters, ignoring case
     (define ri (make-regexp "[A-Z]*" regexp/icase))
     
     ;; Search for bob using regexp r
     (match:substring (regexp-exec r "bob"))
     => ""                  ; no match
     
     ;; Search for bob using regexp ri
     (match:substring (regexp-exec ri "Bob"))
     => "Bob"               ; matched case insensitive

— Scheme Procedure: regexp? obj
— C Function: scm_regexp_p (obj)

Return #t if obj is a compiled regular expression, or #f otherwise.

— Scheme Procedure: list-matches regexp str [flags]

Return a list of match structures which are the non-overlapping matches of regexp in str. regexp can be either a pattern string or a compiled regexp. The flags argument is as per regexp-exec above.

          (map match:substring (list-matches "[a-z]+" "abc 42 def 78"))
          => ("abc" "def")
     

— Scheme Procedure: fold-matches regexp str init proc [flags]

Apply proc to the non-overlapping matches of regexp in str, to build a result. regexp can be either a pattern string or a compiled regexp. The flags argument is as per regexp-exec above.

proc is called as (proc match prev) where match is a match structure and prev is the previous return from proc. For the first call prev is the given init parameter. fold-matches returns the final value from proc.

For example to count matches,

          (fold-matches "[a-z][0-9]" "abc x1 def y2" 0
                        (lambda (match count)
                          (1+ count)))
          => 2
     

— Scheme Procedure: regexp-substitute port match [item...]

Write to port selected parts of the match structure match. Or if port is #f then form a string from those parts and return that.

Each item specifies a part to be written, and may be one of the following,

• A string. String arguments are written out verbatim.
• An integer. The submatch with that number is written (match:substring). Zero is the entire match.
• The symbol `pre'. The portion of the matched string preceding the regexp match is written (match:prefix).
• The symbol `post'. The portion of the matched string following the regexp match is written (match:suffix).

For example, changing a match and retaining the text before and after,

          (regexp-substitute #f (string-match "[0-9]+" "number 25 is good")
                             'pre "37" 'post)
          => "number 37 is good"
     

Or matching a yyyymmdd format date such as `20020828' and re-ordering and hyphenating the fields.

          (define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
          (define s "Date 20020429 12am.")
          (regexp-substitute #f (string-match date-regex s)
                             'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
          => "Date 04-29-2002 12am. (20020429)"
     

— Scheme Procedure: regexp-substitute/global port regexp target [item...]

Write to port selected parts of matches of regexp in target. If port is #f then form a string from those parts and return that. regexp can be a string or a compiled regex.

This is similar to regexp-substitute, but allows global substitutions on target. Each item behaves as per regexp-substitute, with the following differences,

• A function. Called as (item match) with the match structure for the regexp match, it should return a string to be written to port.
• The symbol `post'. This doesn't output anything, but instead causes regexp-substitute/global to recurse on the unmatched portion of target.

  This must be supplied to perform a global search and replace on target; without it regexp-substitute/global returns after a single match and output.

For example, to collapse runs of tabs and spaces to a single hyphen each,

          (regexp-substitute/global #f "[ \t]+"  "this   is   the text"
                                    'pre "-" 'post)
          => "this-is-the-text"
     

Or using a function to reverse the letters in each word,

          (regexp-substitute/global #f "[a-z]+"  "to do and not-do"
            'pre (lambda (m) (string-reverse (match:substring m))) 'post)
          => "ot od dna ton-od"
     

Without the post symbol, just one regexp match is made. For example the following is the date example from regexp-substitute above, without the need for the separate string-match call.

          (define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
          (define s "Date 20020429 12am.")
          (regexp-substitute/global #f date-regex s
                                    'pre 2 "-" 3 "-" 1 'post " (" 0 ")")
          
          => "Date 04-29-2002 12am. (20020429)"