Mercurial > emacs
annotate lispref/positions.texi @ 61403:008bb0675c5b
(readevalloop): Add args START and END as region in
current buffer to read. Callers changed.
When specified, narrow to this region only when reading,
not during eval. Track next point to read from during eval.
Also restore point to "real" buffer position before eval.
(Feval_region): Don't save excursion and restriction here, and
don't narrow to region. Just pass region to readevalloop.
Note: Point is now preserved even when PRINTFLAG is nil.
author | Kim F. Storm <storm@cua.dk> |
---|---|
date | Fri, 08 Apr 2005 23:33:28 +0000 |
parents | 951cb9c59174 |
children | 7a990909b5f9 4da4a09e8b1b |
rev | line source |
---|---|
6552 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
40039
d576274a42f4
(Text Lines): Describe behavior of `beginning-of-line'/`end-of-line' in
Miles Bader <miles@gnu.org>
parents:
39792
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001 |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
49553
diff
changeset
|
4 @c Free Software Foundation, Inc. |
6552 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/positions | |
7 @node Positions, Markers, Frames, Top | |
8 @chapter Positions | |
9 @cindex position (in buffer) | |
10 | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
11 A @dfn{position} is the index of a character in the text of a buffer. |
6552 | 12 More precisely, a position identifies the place between two characters |
13 (or before the first character, or after the last character), so we can | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
14 speak of the character before or after a given position. However, we |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
15 often speak of the character ``at'' a position, meaning the character |
6552 | 16 after that position. |
17 | |
18 Positions are usually represented as integers starting from 1, but can | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
19 also be represented as @dfn{markers}---special objects that relocate |
6552 | 20 automatically when text is inserted or deleted so they stay with the |
53103
d79cdcde0da3
(Positions): Mention that, if a marker is used a a position, its
Luc Teirlinck <teirllm@auburn.edu>
parents:
53026
diff
changeset
|
21 surrounding characters. Functions that expect an argument to be a |
d79cdcde0da3
(Positions): Mention that, if a marker is used a a position, its
Luc Teirlinck <teirllm@auburn.edu>
parents:
53026
diff
changeset
|
22 position (an integer), but accept a marker as a substitute, normally |
d79cdcde0da3
(Positions): Mention that, if a marker is used a a position, its
Luc Teirlinck <teirllm@auburn.edu>
parents:
53026
diff
changeset
|
23 ignore the marker buffer. Of course, markers used this way usually |
d79cdcde0da3
(Positions): Mention that, if a marker is used a a position, its
Luc Teirlinck <teirllm@auburn.edu>
parents:
53026
diff
changeset
|
24 point to a position in the buffer that the function operates on, but |
d79cdcde0da3
(Positions): Mention that, if a marker is used a a position, its
Luc Teirlinck <teirllm@auburn.edu>
parents:
53026
diff
changeset
|
25 that is entirely the programmer's responsibility. @xref{Markers}. |
6552 | 26 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
27 See also the ``field'' feature (@pxref{Fields}), which provides |
48701 | 28 functions that are used by many cursor-motion commands. |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
29 |
6552 | 30 @menu |
31 * Point:: The special position where editing takes place. | |
32 * Motion:: Changing point. | |
33 * Excursions:: Temporary motion and buffer changes. | |
34 * Narrowing:: Restricting editing to a portion of the buffer. | |
35 @end menu | |
36 | |
37 @node Point | |
38 @section Point | |
39 @cindex point | |
40 | |
41 @dfn{Point} is a special buffer position used by many editing | |
42 commands, including the self-inserting typed characters and text | |
43 insertion functions. Other commands move point through the text | |
44 to allow editing and insertion at different places. | |
45 | |
46 Like other positions, point designates a place between two characters | |
47 (or before the first character, or after the last character), rather | |
12098 | 48 than a particular character. Usually terminals display the cursor over |
49 the character that immediately follows point; point is actually before | |
50 the character on which the cursor sits. | |
6552 | 51 |
52 @cindex point with narrowing | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
53 The value of point is a number no less than 1, and no greater than the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
54 buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
55 point is constrained to fall within the accessible portion of the buffer |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
56 (possibly at one end of it). |
6552 | 57 |
58 Each buffer has its own value of point, which is independent of the | |
59 value of point in other buffers. Each window also has a value of point, | |
60 which is independent of the value of point in other windows on the same | |
61 buffer. This is why point can have different values in various windows | |
62 that display the same buffer. When a buffer appears in only one window, | |
63 the buffer's point and the window's point normally have the same value, | |
64 so the distinction is rarely important. @xref{Window Point}, for more | |
65 details. | |
66 | |
67 @defun point | |
68 @cindex current buffer position | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
69 This function returns the value of point in the current buffer, |
6552 | 70 as an integer. |
71 | |
72 @need 700 | |
73 @example | |
74 @group | |
75 (point) | |
76 @result{} 175 | |
77 @end group | |
78 @end example | |
79 @end defun | |
80 | |
81 @defun point-min | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
82 This function returns the minimum accessible value of point in the |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
83 current buffer. This is normally 1, but if narrowing is in effect, it |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
84 is the position of the start of the region that you narrowed to. |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
85 (@xref{Narrowing}.) |
6552 | 86 @end defun |
87 | |
88 @defun point-max | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
89 This function returns the maximum accessible value of point in the |
6552 | 90 current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is |
91 in effect, in which case it is the position of the end of the region | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
92 that you narrowed to. (@xref{Narrowing}.) |
6552 | 93 @end defun |
94 | |
95 @defun buffer-end flag | |
53026
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
96 This function returns @code{(point-max)} if @var{flag} is greater than |
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
97 0, @code{(point-min)} otherwise. The argument @var{flag} must be a |
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
98 number. |
6552 | 99 @end defun |
100 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
101 @defun buffer-size &optional buffer |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
102 This function returns the total number of characters in the current |
6552 | 103 buffer. In the absence of any narrowing (@pxref{Narrowing}), |
104 @code{point-max} returns a value one larger than this. | |
105 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
106 If you specify a buffer, @var{buffer}, then the value is the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
107 size of @var{buffer}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
108 |
6552 | 109 @example |
110 @group | |
111 (buffer-size) | |
112 @result{} 35 | |
113 @end group | |
114 @group | |
115 (point-max) | |
116 @result{} 36 | |
117 @end group | |
118 @end example | |
119 @end defun | |
120 | |
121 @node Motion | |
122 @section Motion | |
123 | |
124 Motion functions change the value of point, either relative to the | |
125 current value of point, relative to the beginning or end of the buffer, | |
126 or relative to the edges of the selected window. @xref{Point}. | |
127 | |
128 @menu | |
129 * Character Motion:: Moving in terms of characters. | |
130 * Word Motion:: Moving in terms of words. | |
131 * Buffer End Motion:: Moving to the beginning or end of the buffer. | |
132 * Text Lines:: Moving in terms of lines of text. | |
133 * Screen Lines:: Moving in terms of lines as displayed. | |
134 * List Motion:: Moving by parsing lists and sexps. | |
135 * Skipping Characters:: Skipping characters belonging to a certain set. | |
136 @end menu | |
137 | |
138 @node Character Motion | |
139 @subsection Motion by Characters | |
140 | |
141 These functions move point based on a count of characters. | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
142 @code{goto-char} is the fundamental primitive; the other functions use |
6552 | 143 that. |
144 | |
145 @deffn Command goto-char position | |
146 This function sets point in the current buffer to the value | |
147 @var{position}. If @var{position} is less than 1, it moves point to the | |
148 beginning of the buffer. If @var{position} is greater than the length | |
149 of the buffer, it moves point to the end. | |
150 | |
151 If narrowing is in effect, @var{position} still counts from the | |
152 beginning of the buffer, but point cannot go outside the accessible | |
153 portion. If @var{position} is out of range, @code{goto-char} moves | |
154 point to the beginning or the end of the accessible portion. | |
155 | |
156 When this function is called interactively, @var{position} is the | |
157 numeric prefix argument, if provided; otherwise it is read from the | |
158 minibuffer. | |
159 | |
160 @code{goto-char} returns @var{position}. | |
161 @end deffn | |
162 | |
163 @deffn Command forward-char &optional count | |
164 @c @kindex beginning-of-buffer | |
165 @c @kindex end-of-buffer | |
166 This function moves point @var{count} characters forward, towards the | |
167 end of the buffer (or backward, towards the beginning of the buffer, if | |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
168 @var{count} is negative). If @var{count} is @code{nil}, the default |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
169 is 1. |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
170 |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
171 If this attempts to move past the beginning or end of the buffer (or |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
172 the limits of the accessible portion, when narrowing is in effect), it |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
173 signals an error with error symbol @code{beginning-of-buffer} or |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
174 @code{end-of-buffer}. |
6552 | 175 |
176 In an interactive call, @var{count} is the numeric prefix argument. | |
177 @end deffn | |
178 | |
179 @deffn Command backward-char &optional count | |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
180 This is just like @code{forward-char} except that it moves |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
181 in the opposite direction. |
6552 | 182 @end deffn |
183 | |
184 @node Word Motion | |
185 @subsection Motion by Words | |
186 | |
187 These functions for parsing words use the syntax table to decide | |
188 whether a given character is part of a word. @xref{Syntax Tables}. | |
189 | |
52541
b0b4c9f22ee7
(Word Motion): forward-word, backward-word arg is optional. Reword.
Richard M. Stallman <rms@gnu.org>
parents:
52401
diff
changeset
|
190 @deffn Command forward-word &optional count |
6552 | 191 This function moves point forward @var{count} words (or backward if |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
192 @var{count} is negative). If @var{count} is @code{nil}, it moves |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
193 forward one word. |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
194 |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
195 ``Moving one word'' means moving until point crosses a |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
196 word-constituent character and then encounters a word-separator |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
197 character. However, this function cannot move point past the boundary |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
198 of the accessible portion of the buffer, or across a field boundary |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
199 (@pxref{Fields}). The most common case of a field boundary is the end |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
200 of the prompt in the minibuffer. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
201 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
202 If it is possible to move @var{count} words, without being stopped |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
203 prematurely by the buffer boundary or a field boundary, the value is |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
204 @code{t}. Otherwise, the return value is @code{nil} and point stops at |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
205 the buffer boundary or field boundary. |
6552 | 206 |
27093
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
207 If @code{inhibit-field-text-motion} is non-@code{nil}, |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
208 this function ignores field boundaries. |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
209 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
210 In an interactive call, @var{count} is specified by the numeric prefix |
52541
b0b4c9f22ee7
(Word Motion): forward-word, backward-word arg is optional. Reword.
Richard M. Stallman <rms@gnu.org>
parents:
52401
diff
changeset
|
211 argument. If @var{count} is omitted or @code{nil}, it defaults to 1. |
6552 | 212 @end deffn |
213 | |
52541
b0b4c9f22ee7
(Word Motion): forward-word, backward-word arg is optional. Reword.
Richard M. Stallman <rms@gnu.org>
parents:
52401
diff
changeset
|
214 @deffn Command backward-word &optional count |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
215 This function is just like @code{forward-word}, except that it moves |
6552 | 216 backward until encountering the front of a word, rather than forward. |
217 @end deffn | |
218 | |
219 @defvar words-include-escapes | |
220 @c Emacs 19 feature | |
221 This variable affects the behavior of @code{forward-word} and everything | |
222 that uses it. If it is non-@code{nil}, then characters in the | |
223 ``escape'' and ``character quote'' syntax classes count as part of | |
224 words. Otherwise, they do not. | |
225 @end defvar | |
226 | |
27093
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
227 @defvar inhibit-field-text-motion |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
228 @tindex inhibit-field-text-motion |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
229 If this variable is non-@code{nil}, certain motion functions including |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
230 @code{forward-word}, @code{forward-sentence}, and |
27193 | 231 @code{forward-paragraph} ignore field boundaries. |
27093
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
232 @end defvar |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
233 |
6552 | 234 @node Buffer End Motion |
235 @subsection Motion to an End of the Buffer | |
236 | |
237 To move point to the beginning of the buffer, write: | |
238 | |
239 @example | |
240 @group | |
241 (goto-char (point-min)) | |
242 @end group | |
243 @end example | |
244 | |
245 @noindent | |
246 Likewise, to move to the end of the buffer, use: | |
247 | |
248 @example | |
249 @group | |
250 (goto-char (point-max)) | |
251 @end group | |
252 @end example | |
253 | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
254 Here are two commands that users use to do these things. They are |
6552 | 255 documented here to warn you not to use them in Lisp programs, because |
256 they set the mark and display messages in the echo area. | |
257 | |
258 @deffn Command beginning-of-buffer &optional n | |
259 This function moves point to the beginning of the buffer (or the limits | |
260 of the accessible portion, when narrowing is in effect), setting the | |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
261 mark at the previous position (except in Transient Mark mode, if |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
262 the mark is already active, it does not set the mark.) |
6552 | 263 |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
264 If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
265 way from the beginning of the accessible portion of the buffer. In an |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
266 interactive call, @var{n} is the numeric prefix argument, if provided; |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
267 otherwise @var{n} defaults to @code{nil}. |
6552 | 268 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
269 @strong{Warning:} Don't use this function in Lisp programs! |
6552 | 270 @end deffn |
271 | |
272 @deffn Command end-of-buffer &optional n | |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
273 This function moves point to the end of the buffer (or the limits of |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
274 the accessible portion, when narrowing is in effect), setting the mark |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
275 at the previous position (except in Transient Mark mode when the mark |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
276 is already active). If @var{n} is non-@code{nil}, then it puts point |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
277 @var{n} tenths of the way from the end of the accessible portion of |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
278 the buffer. |
6552 | 279 |
280 In an interactive call, @var{n} is the numeric prefix argument, | |
281 if provided; otherwise @var{n} defaults to @code{nil}. | |
282 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
283 @strong{Warning:} Don't use this function in Lisp programs! |
6552 | 284 @end deffn |
285 | |
286 @node Text Lines | |
287 @subsection Motion by Text Lines | |
288 @cindex lines | |
289 | |
290 Text lines are portions of the buffer delimited by newline characters, | |
291 which are regarded as part of the previous line. The first text line | |
292 begins at the beginning of the buffer, and the last text line ends at | |
293 the end of the buffer whether or not the last character is a newline. | |
294 The division of the buffer into text lines is not affected by the width | |
295 of the window, by line continuation in display, or by how tabs and | |
296 control characters are displayed. | |
297 | |
298 @deffn Command goto-line line | |
299 This function moves point to the front of the @var{line}th line, | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
300 counting from line 1 at beginning of the buffer. If @var{line} is less |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
301 than 1, it moves point to the beginning of the buffer. If @var{line} is |
6552 | 302 greater than the number of lines in the buffer, it moves point to the |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
303 end of the buffer---that is, the @emph{end of the last line} of the |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
304 buffer. This is the only case in which @code{goto-line} does not |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
305 necessarily move to the beginning of a line. |
6552 | 306 |
307 If narrowing is in effect, then @var{line} still counts from the | |
308 beginning of the buffer, but point cannot go outside the accessible | |
309 portion. So @code{goto-line} moves point to the beginning or end of the | |
310 accessible portion, if the line number specifies an inaccessible | |
311 position. | |
312 | |
313 The return value of @code{goto-line} is the difference between | |
314 @var{line} and the line number of the line to which point actually was | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
315 able to move (in the full buffer, before taking account of narrowing). |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
316 Thus, the value is positive if the scan encounters the real end of the |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
317 buffer before finding the specified line. The value is zero if scan |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
318 encounters the end of the accessible portion but not the real end of the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
319 buffer. |
6552 | 320 |
321 In an interactive call, @var{line} is the numeric prefix argument if | |
322 one has been provided. Otherwise @var{line} is read in the minibuffer. | |
323 @end deffn | |
324 | |
325 @deffn Command beginning-of-line &optional count | |
326 This function moves point to the beginning of the current line. With an | |
327 argument @var{count} not @code{nil} or 1, it moves forward | |
328 @var{count}@minus{}1 lines and then to the beginning of the line. | |
329 | |
40066 | 330 This function does not move point across a field boundary |
40039
d576274a42f4
(Text Lines): Describe behavior of `beginning-of-line'/`end-of-line' in
Miles Bader <miles@gnu.org>
parents:
39792
diff
changeset
|
331 (@pxref{Fields}) unless doing so would move beyond there to a |
40066 | 332 different line; therefore, if @var{count} is @code{nil} or 1, and |
333 point starts at a field boundary, point does not move. To ignore | |
334 field boundaries, either bind @code{inhibit-field-text-motion} to | |
335 @code{t}, or use the @code{forward-line} function instead. For | |
336 instance, @code{(forward-line 0)} does the same thing as | |
40039
d576274a42f4
(Text Lines): Describe behavior of `beginning-of-line'/`end-of-line' in
Miles Bader <miles@gnu.org>
parents:
39792
diff
changeset
|
337 @code{(beginning-of-line)}, except that it ignores field boundaries. |
d576274a42f4
(Text Lines): Describe behavior of `beginning-of-line'/`end-of-line' in
Miles Bader <miles@gnu.org>
parents:
39792
diff
changeset
|
338 |
6552 | 339 If this function reaches the end of the buffer (or of the accessible |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
340 portion, if narrowing is in effect), it positions point there. No error |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
341 is signaled. |
6552 | 342 @end deffn |
343 | |
24702 | 344 @defun line-beginning-position &optional count |
345 @tindex line-beginning-position | |
346 Return the position that @code{(beginning-of-line @var{count})} | |
347 would move to. | |
348 @end defun | |
349 | |
6552 | 350 @deffn Command end-of-line &optional count |
351 This function moves point to the end of the current line. With an | |
352 argument @var{count} not @code{nil} or 1, it moves forward | |
353 @var{count}@minus{}1 lines and then to the end of the line. | |
354 | |
40066 | 355 This function does not move point across a field boundary |
40039
d576274a42f4
(Text Lines): Describe behavior of `beginning-of-line'/`end-of-line' in
Miles Bader <miles@gnu.org>
parents:
39792
diff
changeset
|
356 (@pxref{Fields}) unless doing so would move beyond there to a |
40066 | 357 different line; therefore, if @var{count} is @code{nil} or 1, and |
358 point starts at a field boundary, point does not move. To ignore | |
359 field boundaries, bind @code{inhibit-field-text-motion} to @code{t}. | |
40039
d576274a42f4
(Text Lines): Describe behavior of `beginning-of-line'/`end-of-line' in
Miles Bader <miles@gnu.org>
parents:
39792
diff
changeset
|
360 |
6552 | 361 If this function reaches the end of the buffer (or of the accessible |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
362 portion, if narrowing is in effect), it positions point there. No error |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
363 is signaled. |
6552 | 364 @end deffn |
365 | |
24702 | 366 @defun line-end-position &optional count |
367 @tindex line-end-position | |
368 Return the position that @code{(end-of-line @var{count})} | |
369 would move to. | |
370 @end defun | |
371 | |
6552 | 372 @deffn Command forward-line &optional count |
373 @cindex beginning of line | |
374 This function moves point forward @var{count} lines, to the beginning of | |
375 the line. If @var{count} is negative, it moves point | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
376 @minus{}@var{count} lines backward, to the beginning of a line. If |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
377 @var{count} is zero, it moves point to the beginning of the current |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
378 line. If @var{count} is @code{nil}, that means 1. |
6552 | 379 |
380 If @code{forward-line} encounters the beginning or end of the buffer (or | |
381 of the accessible portion) before finding that many lines, it sets point | |
382 there. No error is signaled. | |
383 | |
384 @code{forward-line} returns the difference between @var{count} and the | |
385 number of lines actually moved. If you attempt to move down five lines | |
386 from the beginning of a buffer that has only three lines, point stops at | |
387 the end of the last line, and the value will be 2. | |
388 | |
389 In an interactive call, @var{count} is the numeric prefix argument. | |
390 @end deffn | |
391 | |
392 @defun count-lines start end | |
393 @cindex lines in region | |
56484
17695367365d
(Text Lines): Add anchor for `count-lines'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54777
diff
changeset
|
394 @anchor{Definition of count-lines} |
6552 | 395 This function returns the number of lines between the positions |
396 @var{start} and @var{end} in the current buffer. If @var{start} and | |
397 @var{end} are equal, then it returns 0. Otherwise it returns at least | |
398 1, even if @var{start} and @var{end} are on the same line. This is | |
399 because the text between them, considered in isolation, must contain at | |
400 least one line unless it is empty. | |
401 | |
402 Here is an example of using @code{count-lines}: | |
403 | |
404 @example | |
405 @group | |
406 (defun current-line () | |
407 "Return the vertical position of point@dots{}" | |
408 (+ (count-lines (window-start) (point)) | |
54038
0bd7928bf5ac
(Text Lines): Don't add -1 in current-line.
Richard M. Stallman <rms@gnu.org>
parents:
53843
diff
changeset
|
409 (if (= (current-column) 0) 1 0))) |
6552 | 410 @end group |
411 @end example | |
412 @end defun | |
413 | |
53841
e1eb498238f9
(Text Lines): Add line-number-at-pos.
Kim F. Storm <storm@cua.dk>
parents:
53103
diff
changeset
|
414 @defun line-number-at-pos &optional pos |
e1eb498238f9
(Text Lines): Add line-number-at-pos.
Kim F. Storm <storm@cua.dk>
parents:
53103
diff
changeset
|
415 @cindex line number |
e1eb498238f9
(Text Lines): Add line-number-at-pos.
Kim F. Storm <storm@cua.dk>
parents:
53103
diff
changeset
|
416 This function returns the line number in the current buffer |
54777 | 417 corresponding the buffer position @var{pos}. If @var{pos} is @code{nil} |
418 or omitted, the current buffer position is used. | |
53843
86085872de07
* positions.texi (Text Lines): Added missing end defun.
Jan Djärv <jan.h.d@swipnet.se>
parents:
53841
diff
changeset
|
419 @end defun |
53841
e1eb498238f9
(Text Lines): Add line-number-at-pos.
Kim F. Storm <storm@cua.dk>
parents:
53103
diff
changeset
|
420 |
6552 | 421 @ignore |
422 @c ================ | |
423 The @code{previous-line} and @code{next-line} commands are functions | |
424 that should not be used in programs. They are for users and are | |
425 mentioned here only for completeness. | |
426 | |
427 @deffn Command previous-line count | |
428 @cindex goal column | |
429 This function moves point up @var{count} lines (down if @var{count} | |
430 is negative). In moving, it attempts to keep point in the ``goal column'' | |
431 (normally the same column that it was at the beginning of the move). | |
432 | |
433 If there is no character in the target line exactly under the current | |
434 column, point is positioned after the character in that line which | |
435 spans this column, or at the end of the line if it is not long enough. | |
436 | |
437 If it attempts to move beyond the top or bottom of the buffer (or clipped | |
438 region), then point is positioned in the goal column in the top or | |
439 bottom line. No error is signaled. | |
440 | |
441 In an interactive call, @var{count} will be the numeric | |
442 prefix argument. | |
443 | |
444 The command @code{set-goal-column} can be used to create a semipermanent | |
445 goal column to which this command always moves. Then it does not try to | |
446 move vertically. | |
447 | |
448 If you are thinking of using this in a Lisp program, consider using | |
449 @code{forward-line} with a negative argument instead. It is usually easier | |
450 to use and more reliable (no dependence on goal column, etc.). | |
451 @end deffn | |
452 | |
453 @deffn Command next-line count | |
454 This function moves point down @var{count} lines (up if @var{count} | |
455 is negative). In moving, it attempts to keep point in the ``goal column'' | |
456 (normally the same column that it was at the beginning of the move). | |
457 | |
458 If there is no character in the target line exactly under the current | |
459 column, point is positioned after the character in that line which | |
460 spans this column, or at the end of the line if it is not long enough. | |
461 | |
462 If it attempts to move beyond the top or bottom of the buffer (or clipped | |
463 region), then point is positioned in the goal column in the top or | |
464 bottom line. No error is signaled. | |
465 | |
466 In the case where the @var{count} is 1, and point is on the last | |
467 line of the buffer (or clipped region), a new empty line is inserted at the | |
468 end of the buffer (or clipped region) and point moved there. | |
469 | |
470 In an interactive call, @var{count} will be the numeric | |
471 prefix argument. | |
472 | |
473 The command @code{set-goal-column} can be used to create a semipermanent | |
474 goal column to which this command always moves. Then it does not try to | |
475 move vertically. | |
476 | |
477 If you are thinking of using this in a Lisp program, consider using | |
478 @code{forward-line} instead. It is usually easier | |
479 to use and more reliable (no dependence on goal column, etc.). | |
480 @end deffn | |
481 | |
482 @c ================ | |
483 @end ignore | |
484 | |
485 Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}. | |
486 These functions do not move point, but test whether it is already at the | |
487 beginning or end of a line. | |
488 | |
489 @node Screen Lines | |
490 @subsection Motion by Screen Lines | |
491 | |
492 The line functions in the previous section count text lines, delimited | |
493 only by newline characters. By contrast, these functions count screen | |
494 lines, which are defined by the way the text appears on the screen. A | |
495 text line is a single screen line if it is short enough to fit the width | |
496 of the selected window, but otherwise it may occupy several screen | |
497 lines. | |
498 | |
499 In some cases, text lines are truncated on the screen rather than | |
500 continued onto additional screen lines. In these cases, | |
501 @code{vertical-motion} moves point much like @code{forward-line}. | |
502 @xref{Truncation}. | |
503 | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
504 Because the width of a given string depends on the flags that control |
6552 | 505 the appearance of certain characters, @code{vertical-motion} behaves |
506 differently, for a given piece of text, depending on the buffer it is | |
507 in, and even on the selected window (because the width, the truncation | |
508 flag, and display table may vary between windows). @xref{Usual | |
509 Display}. | |
510 | |
9401
32ae92d81323
Document cache-long-line-scans in @node Text Lines.
Jim Blandy <jimb@redhat.com>
parents:
7734
diff
changeset
|
511 These functions scan text to determine where screen lines break, and |
32ae92d81323
Document cache-long-line-scans in @node Text Lines.
Jim Blandy <jimb@redhat.com>
parents:
7734
diff
changeset
|
512 thus take time proportional to the distance scanned. If you intend to |
32ae92d81323
Document cache-long-line-scans in @node Text Lines.
Jim Blandy <jimb@redhat.com>
parents:
7734
diff
changeset
|
513 use them heavily, Emacs provides caches which may improve the |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
514 performance of your code. @xref{Truncation, cache-long-line-scans}. |
9401
32ae92d81323
Document cache-long-line-scans in @node Text Lines.
Jim Blandy <jimb@redhat.com>
parents:
7734
diff
changeset
|
515 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
516 @defun vertical-motion count &optional window |
6552 | 517 This function moves point to the start of the screen line @var{count} |
518 screen lines down from the screen line containing point. If @var{count} | |
519 is negative, it moves up instead. | |
520 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
521 @code{vertical-motion} returns the number of screen lines over which it |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
522 moved point. The value may be less in absolute value than @var{count} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
523 if the beginning or end of the buffer was reached. |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
524 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
525 The window @var{window} is used for obtaining parameters such as the |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
526 width, the horizontal scrolling, and the display table. But |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
527 @code{vertical-motion} always operates on the current buffer, even if |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
528 @var{window} currently displays some other buffer. |
6552 | 529 @end defun |
530 | |
39167
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
531 @defun count-screen-lines &optional beg end count-final-newline window |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
532 This function returns the number of screen lines in the text from |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
533 @var{beg} to @var{end}. The number of screen lines may be different |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
534 from the number of actual lines, due to line continuation, the display |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
535 table, etc. If @var{beg} and @var{end} are @code{nil} or omitted, |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
536 they default to the beginning and end of the accessible portion of the |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
537 buffer. |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
538 |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
539 If the region ends with a newline, that is ignored unless the optional |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
540 third argument @var{count-final-newline} is non-@code{nil}. |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
541 |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
542 The optional fourth argument @var{window} specifies the window for |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
543 obtaining parameters such as width, horizontal scrolling, and so on. |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
544 The default is to use the selected window's parameters. |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
545 |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
546 Like @code{vertical-motion}, @code{count-screen-lines} always uses the |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
547 current buffer, regardless of which buffer is displayed in |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
548 @var{window}. This makes possible to use @code{count-screen-lines} in |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
549 any buffer, whether or not it is currently displayed in some window. |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
550 @end defun |
97f7986f0b80
Rewrite and move definition of count-screen-lines.
Richard M. Stallman <rms@gnu.org>
parents:
34943
diff
changeset
|
551 |
6552 | 552 @deffn Command move-to-window-line count |
553 This function moves point with respect to the text currently displayed | |
554 in the selected window. It moves point to the beginning of the screen | |
555 line @var{count} screen lines from the top of the window. If | |
556 @var{count} is negative, that specifies a position | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
557 @w{@minus{}@var{count}} lines from the bottom (or the last line of the |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
558 buffer, if the buffer ends above the specified screen position). |
6552 | 559 |
560 If @var{count} is @code{nil}, then point moves to the beginning of the | |
561 line in the middle of the window. If the absolute value of @var{count} | |
562 is greater than the size of the window, then point moves to the place | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
563 that would appear on that screen line if the window were tall enough. |
6552 | 564 This will probably cause the next redisplay to scroll to bring that |
565 location onto the screen. | |
566 | |
567 In an interactive call, @var{count} is the numeric prefix argument. | |
568 | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
569 The value returned is the window line number point has moved to, with |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
570 the top line in the window numbered 0. |
6552 | 571 @end deffn |
572 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
573 @defun compute-motion from frompos to topos width offsets window |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
574 This function scans the current buffer, calculating screen positions. |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
575 It scans the buffer forward from position @var{from}, assuming that is |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
576 at screen coordinates @var{frompos}, to position @var{to} or coordinates |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
577 @var{topos}, whichever comes first. It returns the ending buffer |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
578 position and screen coordinates. |
6552 | 579 |
580 The coordinate arguments @var{frompos} and @var{topos} are cons cells of | |
581 the form @code{(@var{hpos} . @var{vpos})}. | |
582 | |
583 The argument @var{width} is the number of columns available to display | |
60963
951cb9c59174
(Screen Lines): Document nil for width argument to compute-motion.
Richard M. Stallman <rms@gnu.org>
parents:
60785
diff
changeset
|
584 text; this affects handling of continuation lines. @code{nil} means |
951cb9c59174
(Screen Lines): Document nil for width argument to compute-motion.
Richard M. Stallman <rms@gnu.org>
parents:
60785
diff
changeset
|
585 the actual number of usable text columns in the window, which is |
951cb9c59174
(Screen Lines): Document nil for width argument to compute-motion.
Richard M. Stallman <rms@gnu.org>
parents:
60785
diff
changeset
|
586 equivalent to the value returned by @code{(window-width window)}. |
6552 | 587 |
588 The argument @var{offsets} is either @code{nil} or a cons cell of the | |
589 form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
590 the number of columns not being displayed at the left margin; most |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
591 callers get this by calling @code{window-hscroll}. Meanwhile, |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
592 @var{tab-offset} is the offset between column numbers on the screen and |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
593 column numbers in the buffer. This can be nonzero in a continuation |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
594 line, when the previous screen lines' widths do not add up to a multiple |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
595 of @code{tab-width}. It is always zero in a non-continuation line. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
596 |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
597 The window @var{window} serves only to specify which display table to |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
598 use. @code{compute-motion} always operates on the current buffer, |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
599 regardless of what buffer is displayed in @var{window}. |
6552 | 600 |
601 The return value is a list of five elements: | |
602 | |
603 @example | |
49183
b9d62d4d6921
(Screen Lines) <compute-motion>: Correct order of elts in return value.
Richard M. Stallman <rms@gnu.org>
parents:
48701
diff
changeset
|
604 (@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin}) |
6552 | 605 @end example |
606 | |
607 @noindent | |
608 Here @var{pos} is the buffer position where the scan stopped, @var{vpos} | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
609 is the vertical screen position, and @var{hpos} is the horizontal screen |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
610 position. |
6552 | 611 |
612 The result @var{prevhpos} is the horizontal position one character back | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
613 from @var{pos}. The result @var{contin} is @code{t} if the last line |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
614 was continued after (or within) the previous character. |
6552 | 615 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
616 For example, to find the buffer position of column @var{col} of screen line |
6552 | 617 @var{line} of a certain window, pass the window's display start location |
618 as @var{from} and the window's upper-left coordinates as @var{frompos}. | |
619 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
620 the end of the accessible portion of the buffer, and pass @var{line} and |
6552 | 621 @var{col} as @var{topos}. Here's a function that does this: |
622 | |
623 @example | |
624 (defun coordinates-of-position (col line) | |
625 (car (compute-motion (window-start) | |
626 '(0 . 0) | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
627 (point-max) |
6552 | 628 (cons col line) |
629 (window-width) | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
630 (cons (window-hscroll) 0) |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
631 (selected-window)))) |
6552 | 632 @end example |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
633 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
634 When you use @code{compute-motion} for the minibuffer, you need to use |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
635 @code{minibuffer-prompt-width} to get the horizontal position of the |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
636 beginning of the first screen line. @xref{Minibuffer Misc}. |
6552 | 637 @end defun |
638 | |
639 @node List Motion | |
640 @comment node-name, next, previous, up | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
49553
diff
changeset
|
641 @subsection Moving over Balanced Expressions |
6552 | 642 @cindex sexp motion |
643 @cindex Lisp expression motion | |
644 @cindex list motion | |
645 | |
646 Here are several functions concerned with balanced-parenthesis | |
647 expressions (also called @dfn{sexps} in connection with moving across | |
648 them in Emacs). The syntax table controls how these functions interpret | |
649 various characters; see @ref{Syntax Tables}. @xref{Parsing | |
650 Expressions}, for lower-level primitives for scanning sexps or parts of | |
50475
b65aa1d740eb
Fix cross references.
Juanma Barranquero <lekktu@gmail.com>
parents:
49600
diff
changeset
|
651 sexps. For user-level commands, see @ref{Parentheses,, Commands for |
b65aa1d740eb
Fix cross references.
Juanma Barranquero <lekktu@gmail.com>
parents:
49600
diff
changeset
|
652 Editing with Parentheses, emacs, The GNU Emacs Manual}. |
6552 | 653 |
30981
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
654 @deffn Command forward-list &optional arg |
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
655 This function moves forward across @var{arg} (default 1) balanced groups of |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
656 parentheses. (Other syntactic entities such as words or paired string |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
657 quotes are ignored.) |
6552 | 658 @end deffn |
659 | |
30981
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
660 @deffn Command backward-list &optional arg |
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
661 This function moves backward across @var{arg} (default 1) balanced groups of |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
662 parentheses. (Other syntactic entities such as words or paired string |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
663 quotes are ignored.) |
6552 | 664 @end deffn |
665 | |
30981
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
666 @deffn Command up-list &optional arg |
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
667 This function moves forward out of @var{arg} (default 1) levels of parentheses. |
6552 | 668 A negative argument means move backward but still to a less deep spot. |
669 @end deffn | |
670 | |
30981
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
671 @deffn Command down-list &optional arg |
53026
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
672 This function moves forward into @var{arg} (default 1) levels of |
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
673 parentheses. A negative argument means move backward but still go |
7734 | 674 deeper in parentheses (@minus{}@var{arg} levels). |
6552 | 675 @end deffn |
676 | |
30981
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
677 @deffn Command forward-sexp &optional arg |
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
678 This function moves forward across @var{arg} (default 1) balanced expressions. |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
679 Balanced expressions include both those delimited by parentheses and |
39792
664c63b19441
Make a xref to `parsing' from forward-sexp.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
39199
diff
changeset
|
680 other kinds, such as words and string constants |
664c63b19441
Make a xref to `parsing' from forward-sexp.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
39199
diff
changeset
|
681 @xref{Parsing Expressions}. For example, |
6552 | 682 |
683 @example | |
684 @group | |
685 ---------- Buffer: foo ---------- | |
686 (concat@point{} "foo " (car x) y z) | |
687 ---------- Buffer: foo ---------- | |
688 @end group | |
689 | |
690 @group | |
691 (forward-sexp 3) | |
692 @result{} nil | |
693 | |
694 ---------- Buffer: foo ---------- | |
695 (concat "foo " (car x) y@point{} z) | |
696 ---------- Buffer: foo ---------- | |
697 @end group | |
698 @end example | |
699 @end deffn | |
700 | |
30981
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
701 @deffn Command backward-sexp &optional arg |
fdbde2514fc3
(List Motion): Note optional args.
Dave Love <fx@gnu.org>
parents:
27385
diff
changeset
|
702 This function moves backward across @var{arg} (default 1) balanced expressions. |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
703 @end deffn |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
704 |
53026
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
705 @deffn Command beginning-of-defun &optional arg |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
706 This function moves back to the @var{arg}th beginning of a defun. If |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
707 @var{arg} is negative, this actually moves forward, but it still moves |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
708 to the beginning of a defun, not to the end of one. @var{arg} defaults |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
709 to 1. |
6552 | 710 @end deffn |
711 | |
53026
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
712 @deffn Command end-of-defun &optional arg |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
713 This function moves forward to the @var{arg}th end of a defun. If |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
714 @var{arg} is negative, this actually moves backward, but it still moves |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
715 to the end of a defun, not to the beginning of one. @var{arg} defaults |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
716 to 1. |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
717 @end deffn |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
718 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
719 @defopt defun-prompt-regexp |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
720 If non-@code{nil}, this variable holds a regular expression that |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
721 specifies what text can appear before the open-parenthesis that starts a |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
722 defun. That is to say, a defun begins on a line that starts with a |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
723 match for this regular expression, followed by a character with |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
724 open-parenthesis syntax. |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
725 @end defopt |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6552
diff
changeset
|
726 |
39199 | 727 @defopt open-paren-in-column-0-is-defun-start |
728 If this variable's value is non-@code{nil}, an open parenthesis in | |
729 column 0 is considered to be the start of a defun. If it is | |
730 @code{nil}, an open parenthesis in column 0 has no special meaning. | |
731 The default is @code{t}. | |
732 @end defopt | |
733 | |
27385
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
734 @defvar beginning-of-defun-function |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
735 @tindex beginning-of-defun-function |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
736 If non-@code{nil}, this variable holds a function for finding the |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
737 beginning of a defun. The function @code{beginning-of-defun} |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
738 calls this function instead of using its normal method. |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
739 @end defvar |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
740 |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
741 @defvar end-of-defun-function |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
742 @tindex end-of-defun-function |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
743 If non-@code{nil}, this variable holds a function for finding the end of |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
744 a defun. The function @code{end-of-defun} calls this function instead |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
745 of using its normal method. |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
746 @end defvar |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
747 |
6552 | 748 @node Skipping Characters |
749 @comment node-name, next, previous, up | |
750 @subsection Skipping Characters | |
751 @cindex skipping characters | |
752 | |
753 The following two functions move point over a specified set of | |
754 characters. For example, they are often used to skip whitespace. For | |
755 related functions, see @ref{Motion and Syntax}. | |
756 | |
49553
d51a733d4b6b
(Skipping Characters): Multibyte conversion and
Dave Love <fx@gnu.org>
parents:
49183
diff
changeset
|
757 These functions convert the set string to multibyte if the buffer is |
d51a733d4b6b
(Skipping Characters): Multibyte conversion and
Dave Love <fx@gnu.org>
parents:
49183
diff
changeset
|
758 multibyte, and they convert it to unibyte if the buffer is unibyte, as |
d51a733d4b6b
(Skipping Characters): Multibyte conversion and
Dave Love <fx@gnu.org>
parents:
49183
diff
changeset
|
759 the search functions do (@pxref{Searching and Matching}). |
d51a733d4b6b
(Skipping Characters): Multibyte conversion and
Dave Love <fx@gnu.org>
parents:
49183
diff
changeset
|
760 |
6552 | 761 @defun skip-chars-forward character-set &optional limit |
762 This function moves point in the current buffer forward, skipping over a | |
763 given set of characters. It examines the character following point, | |
764 then advances point if the character matches @var{character-set}. This | |
765 continues until it reaches a character that does not match. The | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
766 function returns the number of characters moved over. |
6552 | 767 |
59943
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
768 The argument @var{character-set} is a string, like the inside of a |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
769 @samp{[@dots{}]} in a regular expression except that @samp{]} does not |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
770 terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
771 Thus, @code{"a-zA-Z"} skips over all letters, stopping before the |
1b1724ddcdad
(Character Motion): Mention default arg for forward-char.
Richard M. Stallman <rms@gnu.org>
parents:
58397
diff
changeset
|
772 first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before |
60785
2d8b73599b7b
(Skipping Characters): skip-chars-forward allows character classes.
Richard M. Stallman <rms@gnu.org>
parents:
59943
diff
changeset
|
773 the first letter. See @xref{Regular Expressions}. Character classes |
2d8b73599b7b
(Skipping Characters): skip-chars-forward allows character classes.
Richard M. Stallman <rms@gnu.org>
parents:
59943
diff
changeset
|
774 can also be used, e.g. @code{"[:alnum:]"}. See @pxref{Char Classes}. |
6552 | 775 |
776 If @var{limit} is supplied (it must be a number or a marker), it | |
777 specifies the maximum position in the buffer that point can be skipped | |
778 to. Point will stop at or before @var{limit}. | |
779 | |
780 In the following example, point is initially located directly before the | |
781 @samp{T}. After the form is evaluated, point is located at the end of | |
782 that line (between the @samp{t} of @samp{hat} and the newline). The | |
783 function skips all letters and spaces, but not newlines. | |
784 | |
785 @example | |
786 @group | |
787 ---------- Buffer: foo ---------- | |
788 I read "@point{}The cat in the hat | |
789 comes back" twice. | |
790 ---------- Buffer: foo ---------- | |
791 @end group | |
792 | |
793 @group | |
794 (skip-chars-forward "a-zA-Z ") | |
795 @result{} nil | |
796 | |
797 ---------- Buffer: foo ---------- | |
798 I read "The cat in the hat@point{} | |
799 comes back" twice. | |
800 ---------- Buffer: foo ---------- | |
801 @end group | |
802 @end example | |
58397
b40efffdf96e
(Skipping Characters): Add missing `@end defun'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
58388
diff
changeset
|
803 @end defun |
49553
d51a733d4b6b
(Skipping Characters): Multibyte conversion and
Dave Love <fx@gnu.org>
parents:
49183
diff
changeset
|
804 |
6552 | 805 @defun skip-chars-backward character-set &optional limit |
806 This function moves point backward, skipping characters that match | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
807 @var{character-set}, until @var{limit}. It is just like |
6552 | 808 @code{skip-chars-forward} except for the direction of motion. |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
809 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
810 The return value indicates the distance traveled. It is an integer that |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
811 is zero or less. |
6552 | 812 @end defun |
813 | |
814 @node Excursions | |
815 @section Excursions | |
816 @cindex excursion | |
817 | |
818 It is often useful to move point ``temporarily'' within a localized | |
819 portion of the program, or to switch buffers temporarily. This is | |
820 called an @dfn{excursion}, and it is done with the @code{save-excursion} | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
821 special form. This construct initially remembers the identity of the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
822 current buffer, and its values of point and the mark, and restores them |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
823 after the completion of the excursion. |
6552 | 824 |
825 The forms for saving and restoring the configuration of windows are | |
826 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame | |
827 Configurations}). | |
828 | |
829 @defspec save-excursion forms@dots{} | |
830 @cindex mark excursion | |
831 @cindex point excursion | |
832 @cindex current buffer excursion | |
833 The @code{save-excursion} special form saves the identity of the current | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
834 buffer and the values of point and the mark in it, evaluates |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
835 @var{forms}, and finally restores the buffer and its saved values of |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
836 point and the mark. All three saved values are restored even in case of |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
837 an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). |
6552 | 838 |
839 The @code{save-excursion} special form is the standard way to switch | |
840 buffers or move point within one part of a program and avoid affecting | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
841 the rest of the program. It is used more than 4000 times in the Lisp |
6552 | 842 sources of Emacs. |
843 | |
844 @code{save-excursion} does not save the values of point and the mark for | |
845 other buffers, so changes in other buffers remain in effect after | |
846 @code{save-excursion} exits. | |
847 | |
848 @cindex window excursions | |
849 Likewise, @code{save-excursion} does not restore window-buffer | |
850 correspondences altered by functions such as @code{switch-to-buffer}. | |
851 One way to restore these correspondences, and the selected window, is to | |
852 use @code{save-window-excursion} inside @code{save-excursion} | |
853 (@pxref{Window Configurations}). | |
854 | |
855 The value returned by @code{save-excursion} is the result of the last of | |
856 @var{forms}, or @code{nil} if no @var{forms} are given. | |
857 | |
858 @example | |
859 @group | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
860 (save-excursion @var{forms}) |
6552 | 861 @equiv{} |
862 (let ((old-buf (current-buffer)) | |
863 (old-pnt (point-marker)) | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
864 @end group |
6552 | 865 (old-mark (copy-marker (mark-marker)))) |
866 (unwind-protect | |
867 (progn @var{forms}) | |
868 (set-buffer old-buf) | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
869 @group |
6552 | 870 (goto-char old-pnt) |
871 (set-marker (mark-marker) old-mark))) | |
872 @end group | |
873 @end example | |
874 @end defspec | |
875 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
876 @strong{Warning:} Ordinary insertion of text adjacent to the saved |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
877 point value relocates the saved value, just as it relocates all markers. |
53026
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
878 More precisely, the saved value is a marker with insertion type |
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
879 @code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved |
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
880 point value is restored, it normally comes before the inserted text. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
881 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
882 Although @code{save-excursion} saves the location of the mark, it does |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
883 not prevent functions which modify the buffer from setting |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
884 @code{deactivate-mark}, and thus causing the deactivation of the mark |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
885 after the command finishes. @xref{The Mark}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
886 |
6552 | 887 @node Narrowing |
888 @section Narrowing | |
889 @cindex narrowing | |
890 @cindex restriction (in a buffer) | |
891 @cindex accessible portion (of a buffer) | |
892 | |
893 @dfn{Narrowing} means limiting the text addressable by Emacs editing | |
894 commands to a limited range of characters in a buffer. The text that | |
895 remains addressable is called the @dfn{accessible portion} of the | |
896 buffer. | |
897 | |
898 Narrowing is specified with two buffer positions which become the | |
899 beginning and end of the accessible portion. For most editing commands | |
900 and most Emacs primitives, these positions replace the values of the | |
901 beginning and end of the buffer. While narrowing is in effect, no text | |
902 outside the accessible portion is displayed, and point cannot move | |
903 outside the accessible portion. | |
904 | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
905 Values such as positions or line numbers, which usually count from the |
6552 | 906 beginning of the buffer, do so despite narrowing, but the functions |
907 which use them refuse to operate on text that is inaccessible. | |
908 | |
909 The commands for saving buffers are unaffected by narrowing; they save | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
910 the entire buffer regardless of any narrowing. |
6552 | 911 |
912 @deffn Command narrow-to-region start end | |
913 This function sets the accessible portion of the current buffer to start | |
914 at @var{start} and end at @var{end}. Both arguments should be character | |
915 positions. | |
916 | |
917 In an interactive call, @var{start} and @var{end} are set to the bounds | |
918 of the current region (point and the mark, with the smallest first). | |
919 @end deffn | |
920 | |
53026
8fccd5a26c77
(Point): Change description of `buffer-end', so that it is also
Luc Teirlinck <teirllm@auburn.edu>
parents:
52978
diff
changeset
|
921 @deffn Command narrow-to-page &optional move-count |
6552 | 922 This function sets the accessible portion of the current buffer to |
923 include just the current page. An optional first argument | |
924 @var{move-count} non-@code{nil} means to move forward or backward by | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
925 @var{move-count} pages and then narrow to one page. The variable |
6552 | 926 @code{page-delimiter} specifies where pages start and end |
927 (@pxref{Standard Regexps}). | |
928 | |
929 In an interactive call, @var{move-count} is set to the numeric prefix | |
930 argument. | |
931 @end deffn | |
932 | |
933 @deffn Command widen | |
934 @cindex widening | |
935 This function cancels any narrowing in the current buffer, so that the | |
936 entire contents are accessible. This is called @dfn{widening}. | |
937 It is equivalent to the following expression: | |
938 | |
939 @example | |
940 (narrow-to-region 1 (1+ (buffer-size))) | |
941 @end example | |
942 @end deffn | |
943 | |
944 @defspec save-restriction body@dots{} | |
945 This special form saves the current bounds of the accessible portion, | |
946 evaluates the @var{body} forms, and finally restores the saved bounds, | |
947 thus restoring the same state of narrowing (or absence thereof) formerly | |
948 in effect. The state of narrowing is restored even in the event of an | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
949 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
950 Therefore, this construct is a clean way to narrow a buffer temporarily. |
6552 | 951 |
952 The value returned by @code{save-restriction} is that returned by the | |
953 last form in @var{body}, or @code{nil} if no body forms were given. | |
954 | |
955 @c Wordy to avoid overfull hbox. --rjc 16mar92 | |
956 @strong{Caution:} it is easy to make a mistake when using the | |
957 @code{save-restriction} construct. Read the entire description here | |
958 before you try it. | |
959 | |
960 If @var{body} changes the current buffer, @code{save-restriction} still | |
961 restores the restrictions on the original buffer (the buffer whose | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
14504
diff
changeset
|
962 restrictions it saved from), but it does not restore the identity of the |
6552 | 963 current buffer. |
964 | |
965 @code{save-restriction} does @emph{not} restore point and the mark; use | |
966 @code{save-excursion} for that. If you use both @code{save-restriction} | |
967 and @code{save-excursion} together, @code{save-excursion} should come | |
968 first (on the outside). Otherwise, the old point value would be | |
969 restored with temporary narrowing still in effect. If the old point | |
970 value were outside the limits of the temporary narrowing, this would | |
971 fail to restore it accurately. | |
972 | |
973 Here is a simple example of correct use of @code{save-restriction}: | |
974 | |
975 @example | |
976 @group | |
977 ---------- Buffer: foo ---------- | |
978 This is the contents of foo | |
979 This is the contents of foo | |
980 This is the contents of foo@point{} | |
981 ---------- Buffer: foo ---------- | |
982 @end group | |
983 | |
984 @group | |
985 (save-excursion | |
986 (save-restriction | |
987 (goto-char 1) | |
988 (forward-line 2) | |
989 (narrow-to-region 1 (point)) | |
990 (goto-char (point-min)) | |
991 (replace-string "foo" "bar"))) | |
992 | |
993 ---------- Buffer: foo ---------- | |
994 This is the contents of bar | |
995 This is the contents of bar | |
996 This is the contents of foo@point{} | |
997 ---------- Buffer: foo ---------- | |
998 @end group | |
999 @end example | |
1000 @end defspec | |
52401 | 1001 |
1002 @ignore | |
1003 arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87 | |
1004 @end ignore |