From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stephen Berman Newsgroups: gmane.emacs.bugs Subject: bug#23937: 25.0.95; Search functions doc fixes/improvements Date: Sun, 10 Jul 2016 20:21:34 +0200 Message-ID: <87d1ml8ic1.fsf@gmx.net> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1468174950 27567 80.91.229.3 (10 Jul 2016 18:22:30 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 10 Jul 2016 18:22:30 +0000 (UTC) To: 23937@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Jul 10 20:22:18 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bMJMv-0007Cv-GB for geb-bug-gnu-emacs@m.gmane.org; Sun, 10 Jul 2016 20:22:17 +0200 Original-Received: from localhost ([::1]:56419 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMu-0007fi-NG for geb-bug-gnu-emacs@m.gmane.org; Sun, 10 Jul 2016 14:22:16 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59122) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMm-0007dE-AX for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:22:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMJMg-0005XW-97 for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:22:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:33271) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMg-0005XS-4G for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:22:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bMJMg-0002Ix-1E for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:22:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stephen Berman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 10 Jul 2016 18:22:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 23937 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.14681749178847 (code B ref -1); Sun, 10 Jul 2016 18:22:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 10 Jul 2016 18:21:57 +0000 Original-Received: from localhost ([127.0.0.1]:45608 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMJMb-0002Ic-2z for submit@debbugs.gnu.org; Sun, 10 Jul 2016 14:21:57 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:39723) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMJMZ-0002IP-2H for submit@debbugs.gnu.org; Sun, 10 Jul 2016 14:21:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMJMR-0005Tf-Lb for submit@debbugs.gnu.org; Sun, 10 Jul 2016 14:21:49 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:58330) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMR-0005TN-Hq for submit@debbugs.gnu.org; Sun, 10 Jul 2016 14:21:47 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58882) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMN-0007Re-OI for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:21:46 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMJMI-0005Qu-Kb for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:21:43 -0400 Original-Received: from mout.gmx.net ([212.227.17.20]:54599) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMI-0005QD-B7 for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:21:38 -0400 Original-Received: from rosalinde ([89.245.92.4]) by mail.gmx.com (mrgmx102) with ESMTPSA (Nemesis) id 0MNO33-1bTB7G3Tyr-006tFi for ; Sun, 10 Jul 2016 20:21:36 +0200 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.95 (gnu/linux) X-Provags-ID: V03:K0:RNklWZGZq4I3Dox7oRVrY7TJN/7mEzIQhAq+jALtpnzIfa8C9H9 oEqyHVhE5vwjyhr3EFnHl0diwubQ1SCjX9X75wzFZnzs0vdMY13Lqz+wWQ2pk+bPpWDl0kb BOvMqnkuO8ETBNT/SSXnrc9/wh+3w13zqdYlpfIfjSs7gUJFMOW3DPHwzD2bYSVApdQUtlR GMynxCV8GeMsReoBDLhRQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:mFWYKeVCAnw=:hTLoQ6x1+a1Ozjur8FbIgL 67EZVB1UFpKm7Y8DbRHfIwCZ7mrVmNanLs7UvETIObeDbFF/B7wURU8dL9uy3I823DwW55VuK 8JVuNRU9QR2PdPJ1h6avVvEBZ7ZLO6HFHwIhsNA2iIZCgnb+58LxfYkZ5h3f69uXMteyJVSPk 9MxRj98NGYYZOeEY/l3pAinIeEPxPlyFIGIbBnqQ0Rniz3ax0QkWBqneEwXeQ4P5PnQDxfUBQ yaD2omOlrpKkh23ks2cDa0OXHwBTgLzWH29OhCqeiH/SLp5ePKgcc73MdgifeKEkQEqU9axRP H5l0ebjKF6TIHkRmKHDkZebRMI37CjYh9GBvb6OpbSlptXVL/WZUiM6SUAquxSj+pTxGnLfGO XG9UJxK7v1hRtiB9x4eK+Kim1PcA1YqXzYSXh0BTYdQ2YvDlNrIgZXFpSLFr78az0rwFwfLvg cTVyQetFtzxU/bdFjpqZz6P3j1unF2xkI/6hbwhWsiL4Ee9rR6C2uQGIZLV0L8M+Rx7mg0PyG k+Ol4BnBFU8+up5hZk8wX21CRvnwhYdS83XuWrhUgZX1tzwkDgq+l2+hajDCmAyPOvkioH7Pz hwNGn9a89L8s2yDT7dGxJKNyA9LX3+moxcDlsNiPxc8V1C24D/vVvrx79HXiTetiv5o712GnM FKpRhN7MUgg2ehfvCejUumZSYJlovbBcpyOn2Q7LT21am5cu22HJL+14w4l2XzRvQtNGRtoZx PYOpvDNO5qApsD1jxiCCnE305IWD1P7gA4r7/KZFPHOonIu3QYqhZcMBCSUooopGjvFISbFW X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:120808 Archived-At: In GNU Emacs 25.0.95.9 (x86_64-suse-linux-gnu, GTK+ Version 3.14.15) of 2016-07-10 built on rosalinde Repository revision: 4069b716ad3422f2d7f595699220c39297427387 Bug#10507 was about missing documentation for the fact that the fourth argument of search-{for,back}ward can be a negative number, reversing the search direction. This lack was fixed in commit acc28cb, but that commit didn't correspondingly augment the doc of the other search functions (word-search-*, re-search-*, posix-search-*), which have the same behavior. The patch below does this. In addition, the documentation in the Lisp reference uses the word "repeat" instead of "count" for that argument, and says the search is repeated N times, where N is the argument's value; but strictly speaking, it's repeated N-1 times. It may be clear what's intended, but there's no need for the manual to differ from (and be strictly less accurate than) the doc strings on this point, so the patch changes the manual accordingly. Finally, the patch also adds the information about the nil value of the bound/limit argument to those doc strings/manual entries where it's missing. In short the patch makes the doc of all these functions more uniform. diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 1243d72..8d0e4ca 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -44,7 +44,7 @@ String Search buffer is multibyte; they convert the search string to unibyte if the buffer is unibyte. @xref{Text Representations}. -@deffn Command search-forward string &optional limit noerror repeat +@deffn Command search-forward string &optional limit noerror count This function searches forward from point for an exact match for @var{string}. If successful, it sets point to the end of the occurrence found, and returns the new value of point. If no match is found, the @@ -95,24 +95,24 @@ String Search find a match. Invalid arguments cause errors regardless of @var{noerror}. -If @var{repeat} is a positive number @var{n}, it serves as a repeat -count: the search is repeated @var{n} times, each time starting at the -end of the previous time's match. If these successive searches -succeed, the function succeeds, moving point and returning its new -value. Otherwise the search fails, with results depending on the -value of @var{noerror}, as described above. If @var{repeat} is a -negative number -@var{n}, it serves as a repeat count of @var{n} for a -search in the opposite (backward) direction. +If @var{count} is a positive number @var{n}, the search is done +@var{n} times; each repetition starts at the end of the previous +match. If all these successive searches succeed, the function call +succeeds, moving point and returning its new value. Otherwise the +function call fails, with results depending on the value of +@var{noerror}, as described above. If @var{count} is a negative +number -@var{n}, the search is done @var{n} times in the opposite +(backward) direction. @end deffn -@deffn Command search-backward string &optional limit noerror repeat +@deffn Command search-backward string &optional limit noerror count This function searches backward from point for @var{string}. It is like @code{search-forward}, except that it searches backwards rather than forwards. Backward searches leave point at the beginning of the match. @end deffn -@deffn Command word-search-forward string &optional limit noerror repeat +@deffn Command word-search-forward string &optional limit noerror count This function searches forward from point for a word match for @var{string}. If it finds a match, it sets point to the end of the match found, and returns the new value of point. @@ -156,8 +156,10 @@ String Search neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the end of the accessible portion of the buffer) and returns @code{nil}. -If @var{repeat} is non-@code{nil}, then the search is repeated that many -times. Point is positioned at the end of the last match. +If @var{count} is a positive number, it specifies how many successive +occurrences to search for. Point is positioned at the end of the last +match. If @var{count} is a negative number, the search is backward +and point is positioned at the beginning of the last match. @findex word-search-regexp Internally, @code{word-search-forward} and related functions use the @@ -165,7 +167,7 @@ String Search regular expression that ignores punctuation. @end deffn -@deffn Command word-search-forward-lax string &optional limit noerror repeat +@deffn Command word-search-forward-lax string &optional limit noerror count This command is identical to @code{word-search-forward}, except that the beginning or the end of @var{string} need not match a word boundary, unless @var{string} begins or ends in whitespace. @@ -173,14 +175,14 @@ String Search but does not match @samp{balls boy}. @end deffn -@deffn Command word-search-backward string &optional limit noerror repeat +@deffn Command word-search-backward string &optional limit noerror count This function searches backward from point for a word match to @var{string}. This function is just like @code{word-search-forward} except that it searches backward and normally leaves point at the beginning of the match. @end deffn -@deffn Command word-search-backward-lax string &optional limit noerror repeat +@deffn Command word-search-backward-lax string &optional limit noerror count This command is identical to @code{word-search-backward}, except that the beginning or the end of @var{string} need not match a word boundary, unless @var{string} begins or ends in whitespace. @@ -1005,7 +1007,7 @@ Regexp Search the buffer is multibyte; they convert the regular expression to unibyte if the buffer is unibyte. @xref{Text Representations}. -@deffn Command re-search-forward regexp &optional limit noerror repeat +@deffn Command re-search-forward regexp &optional limit noerror count This function searches forward in the current buffer for a string of text that is matched by the regular expression @var{regexp}. The function skips over any amount of text that is not matched by @@ -1014,14 +1016,12 @@ Regexp Search If @var{limit} is non-@code{nil}, it must be a position in the current buffer. It specifies the upper bound to the search. No match -extending after that position is accepted. +extending after that position is accepted. If @var{limit} is omitted +or @code{nil}, it defaults to the end of the accessible portion of the +buffer. -If @var{repeat} is supplied, it must be a positive number; the search -is repeated that many times; each repetition starts at the end of the -previous match. If all these successive searches succeed, the search -succeeds, moving point and returning its new value. Otherwise the -search fails. What @code{re-search-forward} does when the search -fails depends on the value of @var{noerror}: +What @code{re-search-forward} does when the search fails depends on +the value of @var{noerror}: @table @asis @item @code{nil} @@ -1033,6 +1033,19 @@ Regexp Search buffer) and return @code{nil}. @end table +The argument @var{noerror} only affects valid searches which fail to +find a match. Invalid arguments cause errors regardless of +@var{noerror}. + +If @var{count} is a positive number @var{n}, the search is done +@var{n} times; each repetition starts at the end of the previous +match. If all these successive searches succeed, the function call +succeeds, moving point and returning its new value. Otherwise the +function call fails, with results depending on the value of +@var{noerror}, as described above. If @var{count} is a negative +number -@var{n}, the search is done @var{n} times in the opposite +(backward) direction. + In the following example, point is initially before the @samp{T}. Evaluating the search call moves point to the end of that line (between the @samp{t} of @samp{hat} and the newline). @@ -1057,7 +1070,7 @@ Regexp Search @end example @end deffn -@deffn Command re-search-backward regexp &optional limit noerror repeat +@deffn Command re-search-backward regexp &optional limit noerror count This function searches backward in the current buffer for a string of text that is matched by the regular expression @var{regexp}, leaving point at the beginning of the first text found. @@ -1228,13 +1241,13 @@ POSIX Regexps This is because POSIX backtracking conflicts with the semantics of non-greedy repetition. -@deffn Command posix-search-forward regexp &optional limit noerror repeat +@deffn Command posix-search-forward regexp &optional limit noerror count This is like @code{re-search-forward} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. @end deffn -@deffn Command posix-search-backward regexp &optional limit noerror repeat +@deffn Command posix-search-backward regexp &optional limit noerror count This is like @code{re-search-backward} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. diff --git a/lisp/isearch.el b/lisp/isearch.el index 7360a0b..322f2aa 100644 --- a/lisp/isearch.el +++ b/lisp/isearch.el @@ -1627,7 +1627,8 @@ word-search-backward The match found must not extend before that position. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument specifies how many successive occurrences to + search for. Relies on the function `word-search-regexp' to convert a sequence of words in STRING to a regexp used to search words without regard @@ -1644,7 +1645,8 @@ word-search-forward The match found must not extend after that position. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument specifies how many successive occurrences to + search for. Relies on the function `word-search-regexp' to convert a sequence of words in STRING to a regexp used to search words without regard @@ -1665,7 +1667,8 @@ word-search-backward-lax The match found must not extend before that position. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument specifies how many successive occurrences to + search for. Relies on the function `word-search-regexp' to convert a sequence of words in STRING to a regexp used to search words without regard @@ -1686,7 +1689,8 @@ word-search-forward-lax The match found must not extend after that position. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument specifies how many successive occurrences to + search for. Relies on the function `word-search-regexp' to convert a sequence of words in STRING to a regexp used to search words without regard diff --git a/src/search.c b/src/search.c index bcdd8f1..6614781 100644 --- a/src/search.c +++ b/src/search.c @@ -2164,7 +2164,8 @@ DEFUN ("search-backward", Fsearch_backward, Ssearch_backward, 1, 4, doc: /* Search backward from point for STRING. Set point to the beginning of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. -The match found must not extend before that position. +The match found must not extend before that position. A value of nil is + equivalent to (point-min). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, position at limit of search and return nil. Optional fourth argument COUNT, if non-nil, means to search for COUNT @@ -2204,14 +2205,15 @@ See also the functions `match-beginning', `match-end' and `replace-match'. */) DEFUN ("re-search-backward", Fre_search_backward, Sre_search_backward, 1, 4, "sRE search backward: ", doc: /* Search backward from point for match for regular expression REGEXP. -Set point to the beginning of the match, and return point. -The match found is the one starting last in the buffer -and yet ending before the origin of the search. +Set point to the beginning of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. -The match found must start at or after that position. +The match found must not extend before that position. A value of nil is + equivalent to (point-min). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument COUNT, if non-nil, means to search for COUNT + successive occurrences. If COUNT is negative, search forward, + instead of backward, for -COUNT occurrences. Search case-sensitivity is determined by the value of the variable `case-fold-search', which see. @@ -2228,10 +2230,13 @@ DEFUN ("re-search-forward", Fre_search_forward, Sre_search_forward, 1, 4, doc: /* Search forward from point for regular expression REGEXP. Set point to the end of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. -The match found must not extend after that position. +The match found must not extend after that position. A value of nil is + equivalent to (point-max). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument COUNT, if non-nil, means to search for COUNT + successive occurrences. If COUNT is negative, search backward, + instead of forward, for -COUNT occurrences. Search case-sensitivity is determined by the value of the variable `case-fold-search', which see. @@ -2247,14 +2252,15 @@ DEFUN ("posix-search-backward", Fposix_search_backward, Sposix_search_backward, "sPosix search backward: ", doc: /* Search backward from point for match for regular expression REGEXP. Find the longest match in accord with Posix regular expression rules. -Set point to the beginning of the match, and return point. -The match found is the one starting last in the buffer -and yet ending before the origin of the search. +Set point to the beginning of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. -The match found must start at or after that position. +The match found must start at or after that position. A value of nil is + equivalent to (point-min). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument COUNT, if non-nil, means to search for COUNT + successive occurrences. If COUNT is negative, search forward, + instead of backward, for -COUNT occurrences. Search case-sensitivity is determined by the value of the variable `case-fold-search', which see. @@ -2272,10 +2278,13 @@ DEFUN ("posix-search-forward", Fposix_search_forward, Sposix_search_forward, 1, Find the longest match in accord with Posix regular expression rules. Set point to the end of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. -The match found must not extend after that position. +The match found must not extend after that position. A value of nil is + equivalent to (point-max). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument COUNT, if non-nil, means to search for COUNT + successive occurrences. If COUNT is negative, search backward, + instead of forward, for -COUNT occurrences. Search case-sensitivity is determined by the value of the variable `case-fold-search', which see.