4.8.1Regexp Syntax🔗 i

The following syntax specifications describe the content of a string that represents a regular expression. The syntax of the corresponding string may involve extra escape characters. For example, the regular expression (.*)1円 can be represented with the string "(.*)\1円" or the regexp constant #rx"(.*)\1円"; the \ in the regular expression must be escaped to include it in a string or regexp constant.

The regexp and pregexp syntaxes share a common core:

The following completes the grammar for regexp , which treats { and } as literals, \ as a literal within ranges, and \ as a literal producer outside of ranges.

The following completes the grammar for pregexp , which uses { and } bounded repetition and uses \ for meta-characters both inside and outside of ranges.

In case-insensitive mode, a backreference of the form \‹n› matches case-insensitively only with respect to ASCII characters.

The Unicode categories follow.

When a character regexp with . is used with a byte string or input port, the . matches only a valid UTF-8 encoding in the input. A . in a byte regexp matches any byte (except a newline in multi mode). A property specified with \P or \p matches only a valid UTF-8 encoding, whether it is written in a character regexp or byte regexp. Similarly, \X matches only valid UTF-8 encoding sequences, and it will not match a prefix of a sequence (even if matching only a prefix would allow the rest of the pattern to match remaining input), but a grapheme-cluster sequence can be terminated by an invalid UTF-8 encoding.

Changed in version 8.15.0.8 of package base: Added \X grapheme cluster pattern.

4.8.2Additional Syntactic Constraints🔗 i

In addition to matching a grammar, regular expressions must meet two syntactic restrictions:

• In a ‹repeat› other than ‹atom›?, the ‹atom› must not match an empty sequence.

• In a (?<=‹regexp›) or (?<!‹regexp›), the ‹regexp› must match a bounded sequence only.

These constraints are checked syntactically by the following type system. A type [n, m] corresponds to an expression that matches between n and m characters. In the rule for (‹regexp›), ‹n› means the number such that the opening parenthesis is the ‹n›th opening parenthesis for collecting match reports. Non-emptiness is inferred for a backreference pattern, \‹n›, so that a backreference can be used for repetition patterns; in the case of mutual dependencies among backreferences, the inference chooses the fixpoint that maximizes non-emptiness. Finiteness is not inferred for backreferences (i.e., a backreference is assumed to match an arbitrarily large sequence). No syntactic constraint prohibits a backreference within the group that it references, although such self references might create a pattern with no possible matches (as in the case of (.1円), although (^.|1円){2} matches an input that starts with the same two characters).

4.8.3Regexp Constructors🔗 i

If handler is provided and not #f, it is called and its result is returned when str is not a valid representation of a regular expression; the argument to handler is a string that describes the problem with str. If handler is #f or not provided, then exn:fail:contract exception is raised.

The object-name procedure returns the source string for a regexp value.

Changed in version 6.5.0.1 of package base: Added the handler argument.

Changed in version 6.5.0.1 of package base: Added the handler argument.

If handler is provided, it is called and its result is returned if bstr is not a valid representation of a regular expression.

The object-name procedure returns the source byte string for a regexp value.

Changed in version 6.5.0.1 of package base: Added the handler argument.

Changed in version 6.5.0.1 of package base: Added the handler argument.

Added in version 8.11.1.9 of package base.

Added in version 8.15.0.8 of package base.

4.8.4Regexp Matching🔗 i

If input is a path, it is converted to a byte string with path->bytes if pattern is a byte string or a byte-based regexp. Otherwise, input is converted to a string with path->string .

The optional start-pos and end-pos arguments select a portion of input for matching; the default is the entire string or the stream up to an end-of-file. When input is a string, start-pos is a character position; when input is a byte string, then start-pos is a byte position; and when input is an input port, start-pos is the number of bytes to skip before starting to match. The end-pos argument can be #f, which corresponds to the end of the string or an end-of-file in the stream; otherwise, it is a character or byte position, like start-pos. If input is an input port, and if an end-of-file is reached before start-pos bytes are skipped, then the match fails.

In pattern, a start-of-string ^ refers to the first position of input after start-pos, assuming that input-prefix is #"". The end-of-input $ refers to the end-posth position or (in the case of an input port) an end-of-file, whichever comes first.

The input-prefix specifies bytes that effectively precede input for the purposes of ^ and other look-behind matching. For example, a #"" prefix means that ^ matches at the beginning of the stream, while a #"\n" input-prefix means that a start-of-line ^ can match the beginning of the input, while a start-of-file ^ cannot.

If the match fails, #f is returned. If the match succeeds, a list containing strings or byte string, and possibly #f, is returned. The list contains strings only if input is a string and pattern is not a byte regexp. Otherwise, the list contains byte strings (substrings of the UTF-8 encoding of input, if input is a string).

The first (byte) string in a result list is the portion of input that matched pattern. If two portions of input can match pattern, then the match that starts earliest is found.

Additional (byte) strings are returned in the list if pattern contains parenthesized sub-expressions (but not when the opening parenthesis is followed by ?). Matches for the sub-expressions are provided in the order of the opening parentheses in pattern. When sub-expressions occur in branches of an | “or” pattern, in a * “zero or more” pattern, or other places where the overall pattern can succeed without a match for the sub-expression, then a #f is returned for the sub-expression if it did not contribute to the final match. When a single sub-expression occurs within a * “zero or more” pattern or other multiple-match positions, then the rightmost match associated with the sub-expression is returned in the list.

If the optional output-port is provided as an output port, the part of input from its beginning (not start-pos) that precedes the match is written to the port. All of input up to end-pos is written to the port if no match is found. This functionality is most useful when input is an input port.

When matching an input port, a match failure reads up to end-pos bytes (or end-of-file), even if pattern begins with a start-of-string ^; see also regexp-try-match . On success, all bytes up to and including the match are eventually read from the port, but matching proceeds by first peeking bytes from the port (using peek-bytes-avail! ), and then (re‑)reading matching bytes to discard them after the match result is determined. Non-matching bytes may be read and discarded before the match is determined. The matcher peeks in blocking mode only as far as necessary to determine a match, but it may peek extra bytes to fill an internal buffer if immediately available (i.e., without blocking). Greedy repeat operators in pattern, such as * or +, tend to force reading the entire content of the port (up to end-pos) to determine a match.

If the input port is read simultaneously by another thread, or if the port is a custom port with inconsistent reading and peeking procedures (see Custom Ports), then the bytes that are peeked and used for matching may be different than the bytes read and discarded after the match completes; the matcher inspects only the peeked bytes. To avoid such interleaving, use regexp-match-peek (with a progress argument) followed by port-commit-peeked .

The pattern is used in order to find matches, where each match attempt starts at the end of the last match, and ^ is allowed to match the beginning of the input (if input-prefix is #"") only for the first match. Empty matches are handled like other matches, returning a zero-length string or byte sequence (they are more useful in making this a complement of regexp-split ), but pattern is restricted from matching an empty sequence immediately after an empty match.

If input contains no matches (in the range start-pos to end-pos), null is returned. Otherwise, each item in the resulting list is a distinct substring or byte sequence from input that matches pattern. The end-pos argument can be #f to match to the end of input (which corresponds to an end-of-file if input is an input port).

The match-select function specifies the collected results. The default of car means that the result is the list of matches without returning parenthesized sub-patterns. It can be given as a “selector” function which chooses an item from a list, or it can choose a list of items. For example, you can use cdr to get a list of lists of parenthesized sub-patterns matches, or values (as an identity function) to get the full matches as well. (Note that the selector must choose an element of its input list or a list of elements, but it must not inspect its input as they can be either a list of strings or a list of position pairs. Furthermore, the selector must be consistent in its choice(s).)

In addition, specifying gap-select as a non-#f value will make the result an interleaved list of the matches as well as the separators between them matches, starting and ending with a separator. In this case, match-select can be given as #f to return only the separators, making such uses equivalent to regexp-split .

This procedure is especially useful with a pattern that begins with a start-of-string ^ or with a non-#f end-pos, since each limits the amount of peeking into the port. Otherwise, beware that a large portion of the stream may be peeked (and therefore pulled into memory) before the match succeeds or fails.

Range results are returned in a substring - and subbytes -compatible manner, independent of start-pos. In the case of an input port, the returned positions indicate the number of bytes that were read, including start-pos, before the first matching byte.

Range results after the first one can include negative numbers if input-prefix is non-empty and if pattern includes a lookbehind pattern. Such ranges start in the input-prefix instead of input. More generally, when start-pos is positive, then range results that are less than start-pos start in input-prefix.

Although input-prefix is always a byte string, when the returned positions are string indices and they refer to a portion of input-prefix, then they correspond to a UTF-8 decoding of a tail of input-prefix.

Note that unlike regexp-match* , there is no #:gap-select? input keyword, as this information can be easily inferred from the resulting matches.

Beware that regexp-match-exact? can return #f if pattern generates a partial match for input first, even if pattern could also generate a complete match. To check if there is any match of pattern that covers all of input, use regexp-match? with ^(?:pattern)$ instead.

The (?:) grouping is necessary because concatenation has lower precedence than alternation; the regular expression without it, ^a|ab$, matches any input that either starts with a or ends with ab.

The second result can be useful as an input-prefix for attempting a second match on input starting from the end of the first match. In that case, use regexp-max-lookbehind to determine an appropriate value for count.

4.8.5Regexp Splitting🔗 i

If input contains no matches (in the range start-pos to end-pos), the result is a list containing input’s content (from start-pos to end-pos) as a single element. If a match occurs at the beginning of input (at start-pos), the resulting list will start with an empty string or byte string, and if a match occurs at the end (at end-pos), the list will end with an empty string or byte string. The end-pos argument can be #f, in which case splitting goes to the end of input (which corresponds to an end-of-file if input is an input port).

4.8.6Regexp Substitution🔗 i

The insert argument can be either a (byte) string, or a function that returns a (byte) string. In the latter case, the function is applied on the list of values that regexp-match would return (i.e., the first argument is the complete match, and then one argument for each parenthesized sub-expression) to obtain a replacement (byte) string.

If pattern is a string or character regexp and input is a string, then insert must be a string or a procedure that accept strings, and the result is a string. If pattern is a byte string or byte regexp, or if input is a byte string, then insert as a string is converted to a byte string, insert as a procedure is called with a byte string, and the result is a byte string.

If insert contains &, then & is replaced with the matching portion of input before it is substituted into the match’s place. If insert contains \‹n› for some integer ‹n›, then it is replaced with the ‹n›th matching sub-expression from input. A & and 0円 are aliases. If the ‹n›th sub-expression was not used in the match, or if ‹n› is greater than the number of sub-expressions in pattern, then \‹n› is replaced with the empty string.

To substitute a literal & or \, use \& and \\, respectively, in insert. A \$ in insert is equivalent to an empty sequence; this can be used to terminate a number ‹n› following \. If a \ in insert is followed by anything other than a digit, &, \, or $, then the \ by itself is treated as 0円.

Note that the \ described in the previous paragraphs is a character or byte of insert. To write such an insert as a Racket string literal, an escaping \ is needed before the \. For example, the Racket constant "\1円" is 1円.