| Allegro CL version 8.2 Significant update since 8.2 release. 8.1 version |
Arguments: regexp input &key return case-fold single-line multiple-lines ignore-whitespace start end back-end start-unbounded end-unbounded
A patch issued in July, 2013 changed match-re by adding new keyword arguments start-unbounded and end-unbounded, which will find matches when BOS or EOS markers are used only if the match is at the actual start (end) of the string, not where the substring specified by start-unbounded starts or end-unbounded ends. See the examples below. Note the behavior of match-re when the new arguments are not used is unchanged.
Thus this patch corrects the results of replace-re in relevant cases but does not change the results of match-re, but match-re does now have additional capability.
regexp must be a string specifying a regular
expression, or a compiled regular expression (an object returned by
compile-re). This function
tries to match the string input with the
regexp. If they do not match, nil
is returned as the single returned value. If they
match, t
is returned as a first value, and
the match result of the whole, submatch 1, submatch 2, ... are
returned as the other values.
The way of returning match result can be specified by the
return keyword argument. If it is
:string
(the default), substrings of
input are returned. If it is
:index
, a cons of start and end index within
input is returned for each match.
The keyword arguments start and
end limit the region of
input, as do start-unbounded
and end-unbounded. The arguments (only one of
start and start-unbounded
and of end and end-unbounded
should be specified in a call) differ in the handling of BOS
(Beginning of String) and EOS markers. (match-re "^abc" " abc
def" :start 1)
returns true since :start
1
means treat the string as starting at position 1 and so
the BOS condition is satisfied, when (match-re "^abc" " abc
def" :start-unbounded 1)
returns nil since even though
comparisons are only done in the substring, the true start of the
string is remembered and 'abc', though at the beginning of the
substring is not at the true beginning of the string. See the
additional examples below.
The keyword arguments case-fold and
back-end are passed to the compile-re function,
when a string is given as the value of regexp.
They are ignored when regexp is a compiled
regular expression. The default value of back-end
is regexp:vm
.
When applicable, :case-fold nil
means
case-sensitive, :case-fold t
means case-insensitive
(see examples below).
A compiler-macro is defined for this function. If regexp is a literal string, compile-re is called at compilation time, so you do not need to pay the cost of regexp compilation at run-time.
cl-user(4): (match-re "^[A-E]" "Boo") t "B" cl-user(5): (match-re "i.*s" "mississippi") t "ississ" ; the greedy version cl-user(6): (match-re "i.*?s" "mississippi") t "is" ; the non-greedy version cl-user(7): ;; The :CASE-FOLD argument (default is NIL so case-sensitive): cl-user(57): (match-re "Foo" "FOO") nil cl-user(58): (match-re "Foo" "FOO" :case-fold nil) nil cl-user(59): (match-re "Foo" "FOO" :case-fold t) t "FOO" ;; Here we use the new START-UNBOUNDED argument. With START, ;; a regexp with a BOS marker finds a match if the text is at the ;; beginning of the specified substring. With START-UNBOUNDED, ;; it does not find a match: cl-user(152): (match-re "^abc" "abc def") t "abc" cl-user(153): (match-re "^abc" " abc def") nil cl-user(154): (match-re "^abc" " abc def" :start 1) t "abc" cl-user(155): (match-re "^abc" " abc def" :start-unbounded 1) nil ;; Similarly with END-UNBOUNDED: cl-user(157): (match-re "def$" "abc def ") nil cl-user(158): (match-re "def$" "abc def " :end 7) t "def" cl-user(159): (match-re "def$" "abc def " :end-unbounded 7) nil
See The new regexp2 module in regexp.htm for further information on this function and the regexp2 module.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.
| Allegro CL version 8.2 Significant update since 8.2 release. 8.1 version |