Clarify 'regexp-opt' match ordering

Clarify 'regexp-opt' match ordering

[Mattias Engdegård]

[-- Attachment #1: Type: text/plain, Size: 430 bytes --]

As mentioned elsewhere, 'regexp-opt' normally returns a regexp that always matches the longest string in the given list if more than one could match. This is not documented, but it seems very likely that callers often rely on this behaviour even if they don't actually give it much thought.

In other words: it's a behaviour that is useful and cannot be changed, so it should be documented properly. Proposed patch attached.


[-- Attachment #2: 0001-More-precise-regexp-opt-documentation.patch --]
[-- Type: application/octet-stream, Size: 2728 bytes --]

From 3732c59a7bce236afe088c49139c2f9b71689894 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Sun, 15 Dec 2019 22:17:11 +0100
Subject: [PATCH] More precise 'regexp-opt' documentation

* lisp/emacs-lisp/regexp-opt.el (regexp-opt):
* doc/lispref/searching.texi (Regexp Functions):
Be more specific about how the KEEP-ORDER argument actually works.
If nil, the regexp guarantees a longest match; this is the behaviour
that many callers implicitly rely on.
---
 doc/lispref/searching.texi    | 10 +++++-----
 lisp/emacs-lisp/regexp-opt.el | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 700880c228..c8d263d972 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1780,11 +1780,11 @@ Regexp Functions
 it will apply to the whole expression.
 @end table
 
-The optional argument @var{keep-order}, if @code{nil} or omitted,
-allows the returned regexp to match the strings in any order.  If
-non-@code{nil}, the match is guaranteed to be performed in the order
-given, as if the strings were made into a regexp by joining them with
-the @samp{\|} operator.
+The optional argument @var{keep-order}, if non-@code{nil}, forces the
+match to be performed in the order given, as if the strings were made
+into a regexp by joining them with the @samp{\|} operator.  If nil or
+omitted, the returned regexp will always match the longest string
+possible.
 
 Up to reordering, the resulting regexp of @code{regexp-opt} is
 equivalent to but usually more efficient than that of a simplified
diff --git a/lisp/emacs-lisp/regexp-opt.el b/lisp/emacs-lisp/regexp-opt.el
index ab52003cdf..c0921646d6 100644
--- a/lisp/emacs-lisp/regexp-opt.el
+++ b/lisp/emacs-lisp/regexp-opt.el
@@ -114,11 +114,11 @@ regexp-opt
     necessary to ensure that a postfix operator appended to it will
     apply to the whole expression.
 
-The optional argument KEEP-ORDER, if nil or omitted, allows the
-returned regexp to match the strings in any order.  If non-nil,
-the match is guaranteed to be performed in the order given, as if
-the strings were made into a regexp by joining them with the
-`\\|' operator.
+The optional argument KEEP-ORDER, if non-nil, forces the match to
+be performed in the order given, as if the strings were made into
+a regexp by joining them with the `\\|' operator.  If nil or
+omitted, the returned regexp is will always match the longest
+string possible.
 
 Up to reordering, the resulting regexp is equivalent to but
 usually more efficient than that of a simplified version:
-- 
2.21.0 (Apple Git-122.2)

Re: Clarify 'regexp-opt' match ordering

[Mattias Engdegård]

16 dec. 2019 kl. 11.54 skrev Mattias Engdegård <mattiase@acm.org>:

> In other words: it's a behaviour that is useful and cannot be changed, so it should be documented properly. Proposed patch attached.

Pushed; there isn't much more to say about it.