From 3d572ae0d507bba07f3cfc5ae2d2c7dd4937472c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 13 Feb 2023 20:11:28 +0200 Subject: [PATCH] Rename with/without-narrowing to with/without-restriction * doc/lispref/commands.texi: * doc/lispref/display.texi: * doc/lispref/positions.texi: * etc/NEWS: * lisp/subr.el: * src/buffer.c: * src/editfns.c: * src/keyboard.c: * src/xdisp.c: * test/src/buffer-tests.el: Rename with-narrowing and without-narrowing to with-restriction and without-restriction. Likewise with internal--with-narrowing and internal--without-narrowing. All callers and documentation changed. --- doc/lispref/commands.texi | 2 +- doc/lispref/display.texi | 2 +- doc/lispref/positions.texi | 24 ++++++++++++------------ etc/NEWS | 4 ++-- lisp/subr.el | 24 ++++++++++++------------ src/buffer.c | 4 ++-- src/editfns.c | 18 +++++++++--------- src/keyboard.c | 4 ++-- src/xdisp.c | 2 +- test/src/buffer-tests.el | 32 ++++++++++++++++---------------- 10 files changed, 58 insertions(+), 58 deletions(-) diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 9723c279a45..6fd9377e1de 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -100,7 +100,7 @@ emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard command does. Note that, when the buffer text includes very long lines, these two -hooks are called as if they were in a @code{with-narrowing} form +hooks are called as if they were in a @code{with-restriction} form (@pxref{Narrowing}), with a @code{long-line-optimizations-in-command-hooks} label and with the buffer narrowed to a portion around point. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index f0ca7440c60..a8311f5c9a2 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -3502,7 +3502,7 @@ For efficiency, we recommend writing these functions so that they usually assign faces to around 400 to 600 characters at each call. Note that, when the buffer text includes very long lines, these -functions are called as if they were in a @code{with-narrowing} form +functions are called as if they were in a @code{with-restriction} form (@pxref{Narrowing}), with a @code{long-line-optimizations-in-fontification-functions} label and with the buffer narrowed to a portion around @var{pos}. diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index bad83e1be2d..f6a0cf14476 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -1037,12 +1037,12 @@ positions. In an interactive call, @var{start} and @var{end} are set to the bounds of the current region (point and the mark, with the smallest first). -However, when the narrowing has been set by @code{with-narrowing} with +However, when the narrowing has been set by @code{with-restriction} with a label argument (see below), @code{narrow-to-region} can be used only within the limits of that narrowing. If @var{start} or @var{end} are outside these limits, the corresponding limit set by -@code{with-narrowing} is used instead. To gain access to other -portions of the buffer, use @code{without-narrowing} with the same +@code{with-restriction} is used instead. To gain access to other +portions of the buffer, use @code{without-restriction} with the same label. @end deffn @@ -1068,10 +1068,10 @@ It is equivalent to the following expression: (narrow-to-region 1 (1+ (buffer-size))) @end example -However, when a narrowing has been set by @code{with-narrowing} with a -label argument (see below), the limits set by @code{with-narrowing} +However, when a narrowing has been set by @code{with-restriction} with a +label argument (see below), the limits set by @code{with-restriction} are restored, instead of canceling the narrowing. To gain access to -other portions of the buffer, use @code{without-narrowing} with the +other portions of the buffer, use @code{without-restriction} with the same label. @end deffn @@ -1089,7 +1089,7 @@ abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). Therefore, this construct is a clean way to narrow a buffer temporarily. This construct also saves and restores the narrowings that were set by -@code{with-narrowing} with a label argument (see below). +@code{with-restriction} with a label argument (see below). The value returned by @code{save-restriction} is that returned by the last form in @var{body}, or @code{nil} if no body forms were given. @@ -1141,7 +1141,7 @@ This is the contents of foo@point{} @end example @end defspec -@defspec with-narrowing start end [:label label] body +@defspec with-restriction start end [:label label] body This special form saves the current bounds of the accessible portion of the buffer, sets the accessible portion to start at @var{start} and end at @var{end}, evaluates the @var{body} forms, and restores the @@ -1164,8 +1164,8 @@ and @code{widen} can be used only within the @var{start} and @var{end} limits. @item -To lift the restriction introduced by @code{with-narrowing} and gain -access to other portions of the buffer, use @code{without-narrowing} +To lift the restriction introduced by @code{with-restriction} and gain +access to other portions of the buffer, use @code{without-restriction} with the same @var{label} argument. (Another way to gain access to other portions of the buffer is to use an indirect buffer (@pxref{Indirect Buffers}).) @@ -1180,7 +1180,7 @@ user. @end itemize @end defspec -@defspec without-narrowing [:label label] body +@defspec without-restriction [:label label] body This special form saves the current bounds of the accessible portion of the buffer, widens the buffer, evaluates the @var{body} forms, and restores the saved bounds. In that case it is equivalent to @@ -1192,6 +1192,6 @@ restores the saved bounds. In that case it is equivalent to @end example When the optional @var{label} argument is present however, the -narrowing set by @code{with-narrowing} with the same @var{label} +narrowing set by @code{with-restriction} with the same @var{label} argument is lifted. @end defspec diff --git a/etc/NEWS b/etc/NEWS index f2f059119fd..db77fdfbb42 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -620,7 +620,7 @@ In buffers in which these display optimizations are in effect, the hooks are executed on a narrowed portion of the buffer, whose size is controlled by the variables 'long-line-optimizations-region-size' and 'long-line-optimizations-bol-search-limit', as if they were in a -'with-narrowing' form. This may, in particular, cause occasional +'with-restriction form. This may, in particular, cause occasional mis-fontifications in these buffers. The new function 'long-line-optimizations-p' returns non-nil when @@ -3820,7 +3820,7 @@ The default timeout value can be defined by the new variable 'set-transient-map-timeout'. +++ -** New forms 'with-narrowing' and 'without-narrowing'. +** New forms 'with-restriction' and 'without-restriction'. These forms can be used as enhanced alternatives to the 'save-restriction' form combined with, respectively, 'narrow-to-region' and 'widen'. They also accept an optional label diff --git a/lisp/subr.el b/lisp/subr.el index 58a8e85b61d..c26cbb9a56c 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -3941,7 +3941,7 @@ See also `locate-user-emacs-file'.") "Return non-nil if the current buffer is narrowed." (/= (- (point-max) (point-min)) (buffer-size))) -(defmacro with-narrowing (start end &rest rest) +(defmacro with-restriction (start end &rest rest) "Execute BODY with restrictions set to START and END. The current restrictions, if any, are restored upon return. @@ -3949,39 +3949,39 @@ The current restrictions, if any, are restored upon return. When the optional :label LABEL argument is present, in which LABEL is a symbol, inside BODY, `narrow-to-region' and `widen' can be used only within the START and END limits. To gain access -to other portions of the buffer, use `without-narrowing' with the +to other portions of the buffer, use `without-restriction' with the same LABEL argument. \(fn START END [:label LABEL] BODY)" (if (eq (car rest) :label) - `(internal--with-narrowing ,start ,end (lambda () ,@(cddr rest)) + `(internal--with-restriction ,start ,end (lambda () ,@(cddr rest)) ,(cadr rest)) - `(internal--with-narrowing ,start ,end (lambda () ,@rest)))) + `(internal--with-restriction ,start ,end (lambda () ,@rest)))) -(defun internal--with-narrowing (start end body &optional label) - "Helper function for `with-narrowing', which see." +(defun internal--with-restriction (start end body &optional label) + "Helper function for `with-restriction', which see." (save-restriction (narrow-to-region start end) (if label (internal--lock-narrowing label)) (funcall body))) -(defmacro without-narrowing (&rest rest) +(defmacro without-restriction (&rest rest) "Execute BODY without restrictions. The current restrictions, if any, are restored upon return. When the optional :label LABEL argument is present, the -restrictions set by `with-narrowing' with the same LABEL argument +restrictions set by `with-restriction' with the same LABEL argument are lifted. \(fn [:label LABEL] BODY)" (if (eq (car rest) :label) - `(internal--without-narrowing (lambda () ,@(cddr rest)) + `(internal--without-restriction (lambda () ,@(cddr rest)) ,(cadr rest)) - `(internal--without-narrowing (lambda () ,@rest)))) + `(internal--without-restriction (lambda () ,@rest)))) -(defun internal--without-narrowing (body &optional label) - "Helper function for `without-narrowing', which see." +(defun internal--without-restriction (body &optional label) + "Helper function for `without-restriction', which see." (save-restriction (if label (internal--unlock-narrowing label)) (widen) diff --git a/src/buffer.c b/src/buffer.c index 755061d0dee..df1f5206668 100644 --- a/src/buffer.c +++ b/src/buffer.c @@ -5924,7 +5924,7 @@ This variable has effect only in buffers in which `long-line-optimizations-p' is non-nil. For performance reasons, in such buffers, the `fontification-functions', `pre-command-hook' and `post-command-hook' hooks are executed on a narrowed buffer around -point, as if they were called in a `with-narrowing' form with a label. +point, as if they were called in a `with-restriction' form with a label. This variable specifies the size of the narrowed region around point. To disable that narrowing, set this variable to 0. @@ -5942,7 +5942,7 @@ This variable has effect only in buffers in which `long-line-optimizations-p' is non-nil. For performance reasons, in such buffers, the `fontification-functions', `pre-command-hook' and `post-command-hook' hooks are executed on a narrowed buffer around -point, as if they were called in a `with-narrowing' form with a label. +point, as if they were called in a `with-restriction' form with a label. The variable `long-line-optimizations-region-size' specifies the size of the narrowed region around point. This variable, which should be a small integer, specifies the number of characters by which that diff --git a/src/editfns.c b/src/editfns.c index f9879662168..ce133785e0b 100644 --- a/src/editfns.c +++ b/src/editfns.c @@ -2836,10 +2836,10 @@ DEFUN ("widen", Fwiden, Swiden, 0, 0, "", This allows the buffer's full text to be seen and edited. -However, when restrictions have been set by `with-narrowing' with a -label, `widen' restores the narrowing limits set by `with-narrowing'. +However, when restrictions have been set by `with-restriction' with a +label, `widen' restores the narrowing limits set by `with-restriction'. To gain access to other portions of the buffer, use -`without-narrowing' with the same label. */) +`without-restriction' with the same label. */) (void) { Fset (Qoutermost_narrowing, Qnil); @@ -2886,12 +2886,12 @@ When calling from Lisp, pass two arguments START and END: positions (integers or markers) bounding the text that should remain visible. -However, when restrictions have been set by `with-narrowing' with a +However, when restrictions have been set by `with-restriction' with a label, `narrow-to-region' can be used only within the limits of these restrictions. If the START or END arguments are outside these limits, -the corresponding limit set by `with-narrowing' is used instead of the +the corresponding limit set by `with-restriction' is used instead of the argument. To gain access to other portions of the buffer, use -`without-narrowing' with the same label. */) +`without-restriction' with the same label. */) (Lisp_Object start, Lisp_Object end) { EMACS_INT s = fix_position (start), e = fix_position (end); @@ -2944,7 +2944,7 @@ DEFUN ("internal--lock-narrowing", Finternal__lock_narrowing, Sinternal__lock_narrowing, 1, 1, 0, doc: /* Lock the current narrowing with LABEL. -This is an internal function used by `with-narrowing'. */) +This is an internal function used by `with-restriction'. */) (Lisp_Object tag) { Lisp_Object buf = Fcurrent_buffer (); @@ -2966,7 +2966,7 @@ DEFUN ("internal--unlock-narrowing", Finternal__unlock_narrowing, Sinternal__unlock_narrowing, 1, 1, 0, doc: /* Unlock a narrowing locked with LABEL. -This is an internal function used by `without-narrowing'. */) +This is an internal function used by `without-restriction'. */) (Lisp_Object tag) { Lisp_Object buf = Fcurrent_buffer (); @@ -3073,7 +3073,7 @@ DEFUN ("save-restriction", Fsave_restriction, Ssave_restriction, 0, UNEVALLED, 0 The buffer's restrictions make parts of the beginning and end invisible. \(They are set up with `narrow-to-region' and eliminated with `widen'.) This special form, `save-restriction', saves the current buffer's -restrictions, including those that were set by `with-narrowing' with a +restrictions, including those that were set by `with-restriction' with a label argument, when it is entered, and restores them when it is exited. So any `narrow-to-region' within BODY lasts only until the end of the form. The old restrictions settings are restored even in case of abnormal exit diff --git a/src/keyboard.c b/src/keyboard.c index 1d0b907bd8e..b2816f8270b 100644 --- a/src/keyboard.c +++ b/src/keyboard.c @@ -12732,7 +12732,7 @@ which the error occurred is unconditionally removed, since otherwise the error might happen repeatedly and make Emacs nonfunctional. Note that, when `long-line-optimizations-p' is non-nil in the buffer, -these functions are called as if they were in a `with-narrowing' form, +these functions are called as if they were in a `with-restriction' form, with a `long-line-optimizations-in-command-hooks' label and with the buffer narrowed to a portion around point whose size is specified by `long-line-optimizations-region-size'. @@ -12752,7 +12752,7 @@ unavoidable, wrap your code in `(while-no-input (redisplay) CODE)' to avoid making Emacs unresponsive while the user types. Note that, when `long-line-optimizations-p' is non-nil in the buffer, -these functions are called as if they were in a `with-narrowing' form, +these functions are called as if they were in a `with-restriction' form, with a `long-line-optimizations-in-command-hooks' label and with the buffer narrowed to a portion around point whose size is specified by `long-line-optimizations-region-size'. diff --git a/src/xdisp.c b/src/xdisp.c index 1450b869d20..5c5ecaa2bcb 100644 --- a/src/xdisp.c +++ b/src/xdisp.c @@ -36778,7 +36778,7 @@ fontify a region starting at POS in the current buffer, and give fontified regions the property `fontified' with a non-nil value. Note that, when `long-line-optimizations-p' is non-nil in the buffer, -these functions are called as if they were in a `with-narrowing' form, +these functions are called as if they were in a `with-restriction' form, with a `long-line-optimizations-in-fontification-functions' label and with the buffer narrowed to a portion around POS whose size is specified by `long-line-optimizations-region-size'. */); diff --git a/test/src/buffer-tests.el b/test/src/buffer-tests.el index 0ae78c8d9d9..45914b2b6b0 100644 --- a/test/src/buffer-tests.el +++ b/test/src/buffer-tests.el @@ -8540,12 +8540,12 @@ Finally, kill the buffer and its temporary file." ))) (ert-deftest test-labeled-narrowing () - "Test `with-narrowing' and `without-narrowing'." + "Test `with-restriction' and `without-restriction'." (with-current-buffer (generate-new-buffer " foo" t) (insert (make-string 5000 ?a)) (should (= (point-min) 1)) (should (= (point-max) 5001)) - (with-narrowing + (with-restriction 100 500 :label 'foo (should (= (point-min) 100)) (should (= (point-max) 500)) @@ -8564,11 +8564,11 @@ Finally, kill the buffer and its temporary file." (narrow-to-region 400 1000) (should (= (point-min) 400)) (should (= (point-max) 500)) - (without-narrowing + (without-restriction :label 'bar (should (= (point-min) 100)) (should (= (point-max) 500))) - (without-narrowing + (without-restriction :label 'foo (should (= (point-min) 1)) (should (= (point-max) 5001))) @@ -8577,18 +8577,18 @@ Finally, kill the buffer and its temporary file." (widen) (should (= (point-min) 100)) (should (= (point-max) 500)) - (with-narrowing + (with-restriction 50 250 :label 'bar (should (= (point-min) 100)) (should (= (point-max) 250)) (widen) (should (= (point-min) 100)) (should (= (point-max) 250)) - (without-narrowing + (without-restriction :label 'bar (should (= (point-min) 100)) (should (= (point-max) 500)) - (without-narrowing + (without-restriction :label 'foo (should (= (point-min) 1)) (should (= (point-max) 5001))) @@ -8598,39 +8598,39 @@ Finally, kill the buffer and its temporary file." (should (= (point-max) 250))) (should (= (point-min) 100)) (should (= (point-max) 500)) - (with-narrowing + (with-restriction 50 250 :label 'bar (should (= (point-min) 100)) (should (= (point-max) 250)) - (with-narrowing + (with-restriction 150 500 :label 'baz (should (= (point-min) 150)) (should (= (point-max) 250)) - (without-narrowing + (without-restriction :label 'bar (should (= (point-min) 150)) (should (= (point-max) 250))) - (without-narrowing + (without-restriction :label 'foo (should (= (point-min) 150)) (should (= (point-max) 250))) - (without-narrowing + (without-restriction :label 'baz (should (= (point-min) 100)) (should (= (point-max) 250)) - (without-narrowing + (without-restriction :label 'foo (should (= (point-min) 100)) (should (= (point-max) 250))) - (without-narrowing + (without-restriction :label 'bar (should (= (point-min) 100)) (should (= (point-max) 500)) - (without-narrowing + (without-restriction :label 'foobar (should (= (point-min) 100)) (should (= (point-max) 500))) - (without-narrowing + (without-restriction :label 'foo (should (= (point-min) 1)) (should (= (point-max) 5001))) -- 2.39.2