match-re

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.

Example

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.