annotate lispref/text.texi @ 16842:72276b334084 before-thomas-posix1996 glibc-2_0_2 libc-970108 libc-970109 libc-970110 libc-970111 libc-970112 libc-970113 libc-970114 libc-970115 libc-970116 libc-970117 libc-970118 libc-970119 libc-970120 libc-970121 libc-970122 libc-970123 libc-970124 libc-970125 libc-970126 libc-970127 libc-970128 libc-970129 libc-970130 libc-970131 libc-970201 libc-970202 libc-970203 libc-970204 libc-970205 libc-970206 libc-970207 libc-970208 libc-970209 libc-970210 libc-970211 libc-970212 libc-970213 libc-970214 libc-970215 libc-970216 libc-970217 libc-970218 libc-970219 libc-970220 libc-970221 libc-970222 libc-970223 libc-970224 libc-970225 libc-970226 libc-970227 libc-970228 libc-970301 libc-970302 libc-970303 libc-970304 libc-970305 libc-970306 libc-970307 libc-970308 libc-970309 libc-970310 libc-970311 libc-970312 libc-970313 libc-970314 libc-970315 libc-970316 libc-970317 libc-970318 libc-970319 libc-970320 libc-970321 libc-970322 libc-970323 libc-970324 libc20x-970306 libc20x-97031 libc20x-970316 libc20x-970318 libc20x-970319 libc20x-970404 root-libc-2_0_x-branch

Add hppa1.1-hitachi-hiuxmpp support, passed along by rms.
author David J. MacKenzie <djm@gnu.org>
date Tue, 07 Jan 1997 19:29:28 +0000
parents 981e116b4ac6
children 853f638bbc81
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @c See the file elisp.texi for copying conditions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @setfilename ../info/text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @node Text, Searching and Matching, Markers, Top
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @chapter Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @cindex text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 This chapter describes the functions that deal with the text in a
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
11 buffer. Most examine, insert, or delete text in the current buffer,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 often in the vicinity of point. Many are interactive. All the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 functions that change the text provide for undoing the changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 (@pxref{Undo}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 Many text-related functions operate on a region of text defined by two
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 buffer positions passed in arguments named @var{start} and @var{end}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 These arguments should be either markers (@pxref{Markers}) or numeric
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 character positions (@pxref{Positions}). The order of these arguments
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 does not matter; it is all right for @var{start} to be the end of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 region and @var{end} the beginning. For example, @code{(delete-region 1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 10)} and @code{(delete-region 10 1)} are equivalent. An
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 @code{args-out-of-range} error is signaled if either @var{start} or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 @var{end} is outside the accessible portion of the buffer. In an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 interactive call, point and the mark are used for these arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 @cindex buffer contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 Throughout this chapter, ``text'' refers to the characters in the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
29 buffer, together with their properties (when relevant).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Near Point:: Examining text in the vicinity of point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 * Buffer Contents:: Examining text in a general fashion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 * Comparing Text:: Comparing substrings of buffers.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 * Insertion:: Adding new text to a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 * Commands for Insertion:: User-level commands to insert text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 * Deletion:: Removing text from a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 * User-Level Deletion:: User-level commands to delete text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 * The Kill Ring:: Where removed text sometimes is saved for later use.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 * Undo:: Undoing changes to the text of a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 * Maintaining Undo:: How to enable and disable undo information.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 How to control how much information is kept.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 * Filling:: Functions for explicit filling.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
44 * Margins:: How to specify margins for filling commands.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 * Auto Filling:: How auto-fill mode is implemented to break lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 * Sorting:: Functions for sorting parts of the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 * Columns:: Computing horizontal positions, and using them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 * Indentation:: Functions to insert or adjust indentation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 * Case Changes:: Case conversion of parts of the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 * Text Properties:: Assigning Lisp property lists to text characters.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 * Substitution:: Replacing a given character wherever it appears.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
52 * Transposition:: Swapping two portions of a buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 * Registers:: How registers are implemented. Accessing the text or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 position stored in a register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 * Change Hooks:: Supplying functions to be run when text is changed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 @node Near Point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 @section Examining Text Near Point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 Many functions are provided to look at the characters around point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 Several simple functions are described here. See also @code{looking-at}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 in @ref{Regexp Search}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @defun char-after position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 This function returns the character in the current buffer at (i.e.,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 immediately after) position @var{position}. If @var{position} is out of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 range for this purpose, either before the beginning of the buffer, or at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 or beyond the end, then the value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 In the following example, assume that the first character in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 buffer is @samp{@@}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 (char-to-string (char-after 1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 @result{} "@@"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 @defun following-char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 This function returns the character following point in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 buffer. This is similar to @code{(char-after (point))}. However, if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 point is at the end of the buffer, then @code{following-char} returns 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 Remember that point is always between characters, and the terminal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 cursor normally appears over the character following point. Therefore,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 the character returned by @code{following-char} is the character the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 cursor is over.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 In this example, point is between the @samp{a} and the @samp{c}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 Gentlemen may cry ``Pea@point{}ce! Peace!,''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 but there is no peace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 (char-to-string (preceding-char))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @result{} "a"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 (char-to-string (following-char))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @result{} "c"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @defun preceding-char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 This function returns the character preceding point in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 buffer. See above, under @code{following-char}, for an example. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 point is at the beginning of the buffer, @code{preceding-char} returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @defun bobp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 This function returns @code{t} if point is at the beginning of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 buffer. If narrowing is in effect, this means the beginning of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 accessible portion of the text. See also @code{point-min} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @ref{Point}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @defun eobp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 This function returns @code{t} if point is at the end of the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 If narrowing is in effect, this means the end of accessible portion of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 the text. See also @code{point-max} in @xref{Point}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @defun bolp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 This function returns @code{t} if point is at the beginning of a line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @xref{Text Lines}. The beginning of the buffer (or its accessible
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
134 portion) always counts as the beginning of a line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @defun eolp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 This function returns @code{t} if point is at the end of a line. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 end of the buffer (or of its accessible portion) is always considered
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 the end of a line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 @node Buffer Contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 @section Examining Buffer Contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 This section describes two functions that allow a Lisp program to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 convert any portion of the text in the buffer into a string.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 @defun buffer-substring start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 This function returns a string containing a copy of the text of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 region defined by positions @var{start} and @var{end} in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 buffer. If the arguments are not positions in the accessible portion of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 error.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 It is not necessary for @var{start} to be less than @var{end}; the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 arguments can be given in either order. But most often the smaller
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 argument is written first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
160 If the text being copied has any text properties, these are copied into
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
161 the string along with the characters they belong to. @xref{Text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
162 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
163 their properties are ignored, not copied.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
164
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 This is the contents of buffer foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 (buffer-substring 1 10)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @result{} "This is t"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 (buffer-substring (point-max) 10)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @result{} "he contents of buffer foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184
13109
acb0ab49f4e7 Fix name of buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 12775
diff changeset
185 @defun buffer-substring-no-properties start end
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
186 This is like @code{buffer-substring}, except that it does not copy text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
187 properties, just the characters themselves. @xref{Text Properties}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
188 Here's an example of using this function to get a word to look up in an
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
189 alist:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
190
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
191 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
192 (setq flammable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
193 (assoc (buffer-substring start end)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
194 '(("wood" . t) ("paper" . t)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
195 ("steel" . nil) ("asbestos" . nil))))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
196 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
197
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
198 If this were written using @code{buffer-substring} instead, it would not
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
199 work reliably; any text properties that happened to be in the word
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
200 copied from the buffer would make the comparisons fail.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
201 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
202
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 @defun buffer-string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 This function returns the contents of the accessible portion of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 current buffer as a string. This is the portion between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 @code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 This is the contents of buffer foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 (buffer-string)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 @result{} "This is the contents of buffer foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 @node Comparing Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @section Comparing Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 @cindex comparing buffer text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 This function lets you compare portions of the text in a buffer, without
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 copying them into strings first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 This function lets you compare two substrings of the same buffer or two
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 different buffers. The first three arguments specify one substring,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 giving a buffer and two positions within the buffer. The last three
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 arguments specify the other substring in the same way. You can use
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
234 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 The value is negative if the first substring is less, positive if the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 first is greater, and zero if they are equal. The absolute value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 the result is one plus the index of the first differing characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 within the substrings.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 This function ignores case when comparing characters
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
243 if @code{case-fold-search} is non-@code{nil}. It always ignores
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
244 text properties.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 Suppose the current buffer contains the text @samp{foobarbar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 haha!rara!}; then in this example the two substrings are @samp{rbar }
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 and @samp{rara!}. The value is 2 because the first substring is greater
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 at the second character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 (compare-buffer-substring nil 6 11 nil 16 21)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 @result{} 2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 @node Insertion
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
258 @section Inserting Text
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @cindex insertion of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @cindex text insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @dfn{Insertion} means adding new text to a buffer. The inserted text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 goes at point---between the character before point and the character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 after point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 Insertion relocates markers that point at positions after the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 insertion point, so that they stay with the surrounding text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 (@pxref{Markers}). When a marker points at the place of insertion,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 insertion normally doesn't relocate the marker, so that it points to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 beginning of the inserted text; however, certain special functions such
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 as @code{insert-before-markers} relocate such markers to point after the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 inserted text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 @cindex insertion before point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 @cindex before point, insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 Some insertion functions leave point before the inserted text, while
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
277 other functions leave it after. We call the former insertion @dfn{after
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
278 point} and the latter insertion @dfn{before point}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 Insertion functions signal an error if the current buffer is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 read-only.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
283 These functions copy text characters from strings and buffers along
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
284 with their properties. The inserted characters have exactly the same
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
285 properties as the characters they were copied from. By contrast,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
286 characters specified as separate arguments, not part of a string or
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
287 buffer, inherit their text properties from the neighboring text.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
288
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 @defun insert &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 This function inserts the strings and/or characters @var{args} into the
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
291 current buffer, at point, moving point forward. In other words, it
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
292 inserts the text before point. An error is signaled unless all
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
293 @var{args} are either strings or characters. The value is @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @defun insert-before-markers &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 This function inserts the strings and/or characters @var{args} into the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 current buffer, at point, moving point forward. An error is signaled
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 unless all @var{args} are either strings or characters. The value is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 This function is unlike the other insertion functions in that it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 relocates markers initially pointing at the insertion point, to point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 after the inserted text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
307 @defun insert-char character count &optional inherit
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 This function inserts @var{count} instances of @var{character} into the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 current buffer before point. The argument @var{count} must be a number,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 and @var{character} must be a character. The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @c It's unfortunate that count comes second. Not like make-string, etc.
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
312
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
313 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
314 sticky text properties from the two characters before and after the
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
315 insertion point. @xref{Sticky Properties}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @defun insert-buffer-substring from-buffer-or-name &optional start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 This function inserts a portion of buffer @var{from-buffer-or-name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 (which must already exist) into the current buffer before point. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 text inserted is the region from @var{start} and @var{end}. (These
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 arguments default to the beginning and end of the accessible portion of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 that buffer.) This function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 In this example, the form is executed with buffer @samp{bar} as the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 current buffer. We assume that buffer @samp{bar} is initially empty.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 We hold these truths to be self-evident, that all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 (insert-buffer-substring "foo" 1 20)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 ---------- Buffer: bar ----------
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
340 We hold these truth@point{}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 @xref{Sticky Properties}, for other insertion functions that inherit
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
347 text properties from the nearby text in addition to inserting it.
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
348 Whitespace inserted by indentation functions also inherits text
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
349 properties.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 @node Commands for Insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @section User-Level Insertion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 This section describes higher-level commands for inserting text,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 commands intended primarily for the user but useful also in Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 programs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 @deffn Command insert-buffer from-buffer-or-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 This command inserts the entire contents of @var{from-buffer-or-name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 (which must exist) into the current buffer after point. It leaves
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 the mark after the inserted text. The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 @deffn Command self-insert-command count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @cindex character insertion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @cindex self-insertion
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
367 This command inserts the last character typed; it does so @var{count}
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
368 times, before point, and returns @code{nil}. Most printing characters
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
369 are bound to this command. In routine use, @code{self-insert-command}
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
370 is the most frequently called function in Emacs, but programs rarely use
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
371 it except to install it on a keymap.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 In an interactive call, @var{count} is the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
375 This command calls @code{auto-fill-function} whenever that is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
376 non-@code{nil} and the character inserted is a space or a newline
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
377 (@pxref{Auto Filling}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
380 This command performs abbrev expansion if Abbrev mode is enabled and
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 the inserted character does not have word-constituent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
384 This is also responsible for calling @code{blink-paren-function} when
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
385 the inserted character has close parenthesis syntax (@pxref{Blinking}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @deffn Command newline &optional number-of-newlines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 This command inserts newlines into the current buffer before point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 If @var{number-of-newlines} is supplied, that many newline characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 are inserted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @cindex newline and Auto Fill mode
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
394 This function calls @code{auto-fill-function} if the current column
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
395 number is greater than the value of @code{fill-column} and
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
396 @var{number-of-newlines} is @code{nil}. Typically what
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
397 @code{auto-fill-function} does is insert a newline; thus, the overall
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
398 result in this case is to insert two newlines at different places: one
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
399 at point, and another earlier in the line. @code{newline} does not
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
400 auto-fill if @var{number-of-newlines} is non-@code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
402 This command indents to the left margin if that is not zero.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
403 @xref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
404
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 The value returned is @code{nil}. In an interactive call, @var{count}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 is the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @deffn Command split-line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 This command splits the current line, moving the portion of the line
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
411 after point down vertically so that it is on the next line directly
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 below where it was before. Whitespace is inserted as needed at the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 beginning of the lower line, using the @code{indent-to} function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 @code{split-line} returns the position of point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 Programs hardly ever use this function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 @defvar overwrite-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 This variable controls whether overwrite mode is in effect: a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 non-@code{nil} value enables the mode. It is automatically made
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 buffer-local when set in any fashion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 @node Deletion
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
426 @section Deleting Text
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 @cindex deletion vs killing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 Deletion means removing part of the text in a buffer, without saving
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
432 Some deletion functions do save text in the kill ring in some special
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
433 cases.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 All of the deletion functions operate on the current buffer, and all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 return a value of @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 @defun erase-buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 This function deletes the entire text of the current buffer, leaving it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 error. Otherwise, it deletes the text without asking for any
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 confirmation. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 Normally, deleting a large amount of text from a buffer inhibits further
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 auto-saving of that buffer ``because it has shrunk''. However,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @code{erase-buffer} does not do this, the idea being that the future
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 text is not really related to the former text, and its size should not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 be compared with that of the former text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @deffn Command delete-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 This command deletes the text in the current buffer in the region
12775
a8cd9be43025 Explain how delete-region alters point.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
453 defined by @var{start} and @var{end}. The value is @code{nil}. If
a8cd9be43025 Explain how delete-region alters point.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
454 point was inside the deleted region, its value afterward is @var{start}.
a8cd9be43025 Explain how delete-region alters point.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
455 Otherwise, point relocates with the surrounding text, as markers do.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @deffn Command delete-char count &optional killp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 This command deletes @var{count} characters directly after point, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 before point if @var{count} is negative. If @var{killp} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 non-@code{nil}, then it saves the deleted characters in the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 argument is supplied, the text is saved in the kill ring. If no prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @deffn Command delete-backward-char count &optional killp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 @cindex delete previous char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 This command deletes @var{count} characters directly before point, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 after point if @var{count} is negative. If @var{killp} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 non-@code{nil}, then it saves the deleted characters in the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 argument is supplied, the text is saved in the kill ring. If no prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 @deffn Command backward-delete-char-untabify count &optional killp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 @cindex tab deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 This command deletes @var{count} characters backward, changing tabs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 into spaces. When the next character to be deleted is a tab, it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 first replaced with the proper number of spaces to preserve alignment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 and then one of those spaces is deleted instead of the tab. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @var{killp} is non-@code{nil}, then the command saves the deleted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 characters in the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 Conversion of tabs to spaces happens only if @var{count} is positive.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 If it is negative, exactly @minus{}@var{count} characters after point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498 are deleted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 In an interactive call, @var{count} is the numeric prefix argument, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 argument is supplied, the text is saved in the kill ring. If no prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 argument is supplied, then one character is deleted, but not saved in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 The value returned is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 @node User-Level Deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 @section User-Level Deletion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 This section describes higher-level commands for deleting text,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 commands intended primarily for the user but useful also in Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 programs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 @deffn Command delete-horizontal-space
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 @cindex deleting whitespace
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 This function deletes all spaces and tabs around point. It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 In the following examples, we call @code{delete-horizontal-space} four
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 times, once on each line, with point between the second and third
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
523 characters on the line each time.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 I @point{}thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 I @point{} thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 We@point{} thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531 Yo@point{}u thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 (delete-horizontal-space) ; @r{Four times.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 Ithought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 Ithought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 Wethought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 You thought
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @deffn Command delete-indentation &optional join-following-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 This function joins the line point is on to the previous line, deleting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 any whitespace at the join and in some cases replacing it with one
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 space. If @var{join-following-p} is non-@code{nil},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @code{delete-indentation} joins this line to the following line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 instead. The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 If there is a fill prefix, and the second of the lines being joined
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 starts with the prefix, then @code{delete-indentation} deletes the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
558 fill prefix before joining the lines. @xref{Margins}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 In the example below, point is located on the line starting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 @samp{events}, and it makes no difference if there are trailing spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 in the preceding line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @smallexample
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
565 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 When in the course of human
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @point{} events, it becomes necessary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 ---------- Buffer: foo ----------
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
570 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 (delete-indentation)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
575 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 When in the course of human@point{} events, it becomes necessary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 ---------- Buffer: foo ----------
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
579 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 After the lines are joined, the function @code{fixup-whitespace} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 responsible for deciding whether to leave a space at the junction.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @defun fixup-whitespace
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 This function replaces all the white space surrounding point with either
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 one space or no space, according to the context. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 At the beginning or end of a line, the appropriate amount of space is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 none. Before a character with close parenthesis syntax, or after a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 character with open parenthesis or expression-prefix syntax, no space is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 Class Table}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 In the example below, @code{fixup-whitespace} is called the first time
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
597 with point before the word @samp{spaces} in the first line. For the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
598 second invocation, point is directly after the @samp{(}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 This has too many @point{}spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 This has too many spaces at the start of (@point{} this list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 (fixup-whitespace)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 (fixup-whitespace)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 This has too many spaces
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 This has too many spaces at the start of (this list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @deffn Command just-one-space
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 This command replaces any spaces and tabs around point with a single
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 space. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @deffn Command delete-blank-lines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 This function deletes blank lines surrounding point. If point is on a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 blank line with one or more blank lines before or after it, then all but
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 one of them are deleted. If point is on an isolated blank line, then it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 is deleted. If point is on a nonblank line, the command deletes all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 blank lines following it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 A blank line is defined as a line containing only tabs and spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 @code{delete-blank-lines} returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 @node The Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 @section The Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @cindex kill ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @dfn{Kill} functions delete text like the deletion functions, but save
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 it so that the user can reinsert it by @dfn{yanking}. Most of these
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 functions have @samp{kill-} in their name. By contrast, the functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 whose names start with @samp{delete-} normally do not save text for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 yanking (though they can still be undone); these are ``deletion''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 functions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 Most of the kill commands are primarily for interactive use, and are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 not described here. What we do describe are the functions provided for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 use in writing such commands. You can use these functions to write
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
656 commands for killing text. When you need to delete text for internal
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 purposes within a Lisp function, you should normally use deletion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 functions, so as not to disturb the kill ring contents.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 @xref{Deletion}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 Killed text is saved for later yanking in the @dfn{kill ring}. This
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
662 is a list that holds a number of recent kills, not just the last text
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
663 kill. We call this a ``ring'' because yanking treats it as having
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
664 elements in a cyclic order. The list is kept in the variable
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
665 @code{kill-ring}, and can be operated on with the usual functions for
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
666 lists; there are also specialized functions, described in this section,
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
667 that treat it as a ring.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 Some people think this use of the word ``kill'' is unfortunate, since
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
670 it refers to operations that specifically @emph{do not} destroy the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 entities ``killed''. This is in sharp contrast to ordinary life, in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 which death is permanent and ``killed'' entities do not come back to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 life. Therefore, other metaphors have been proposed. For example, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 term ``cut ring'' makes sense to people who, in pre-computer days, used
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 scissors and paste to cut up and rearrange manuscripts. However, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 would be difficult to change the terminology now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 * Kill Ring Concepts:: What text looks like in the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 * Kill Functions:: Functions that kill text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 * Yank Commands:: Commands that access the kill ring.
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
682 * Low-Level Kill Ring:: Functions and variables for kill ring access.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 * Internals of Kill Ring:: Variables that hold kill-ring data.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 @node Kill Ring Concepts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @subsection Kill Ring Concepts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 The kill ring records killed text as strings in a list, most recent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 first. A short kill ring, for example, might look like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 ("some text" "a different piece of text" "even older text")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 When the list reaches @code{kill-ring-max} entries in length, adding a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 new entry automatically deletes the last entry.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 When kill commands are interwoven with other commands, each kill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 command makes a new entry in the kill ring. Multiple kill commands in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 succession build up a single entry in the kill ring, which would be
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
704 yanked as a unit; the second and subsequent consecutive kill commands
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 add text to the entry made by the first one.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 For yanking, one entry in the kill ring is designated the ``front'' of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 the ring. Some yank commands ``rotate'' the ring by designating a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 different element as the ``front.'' But this virtual rotation doesn't
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 change the list itself---the most recent entry always comes first in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 @node Kill Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @subsection Functions for Killing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 @code{kill-region} is the usual subroutine for killing text. Any
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 command that calls this function is a ``kill command'' (and should
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 probably have @samp{kill} in its name). @code{kill-region} puts the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 newly killed text in a new element at the beginning of the kill ring or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 adds it to the most recent element. It uses the @code{last-command}
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
722 variable to determine whether the previous command was a kill command,
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
723 and if so appends the killed text to the most recent entry.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 @deffn Command kill-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 This function kills the text in the region defined by @var{start} and
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
727 @var{end}. The text is deleted but saved in the kill ring, along with
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
728 its text properties. The value is always @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 In an interactive call, @var{start} and @var{end} are point and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 the mark.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 If the buffer is read-only, @code{kill-region} modifies the kill ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 just the same, then signals an error without modifying the buffer. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 is convenient because it lets the user use all the kill commands to copy
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 text into the kill ring from a read-only buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 @deffn Command copy-region-as-kill start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 This command saves the region defined by @var{start} and @var{end} on
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
742 the kill ring (including text properties), but does not delete the text
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
743 from the buffer. It returns @code{nil}. It also indicates the extent
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
744 of the text copied by moving the cursor momentarily, or by displaying a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
745 message in the echo area.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
747 The command does not set @code{this-command} to @code{kill-region}, so a
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
748 subsequent kill command does not append to the same kill ring entry.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
749
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
752 @code{kill-append} instead. @xref{Low-Level Kill Ring}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 @node Yank Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @subsection Functions for Yanking
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 @dfn{Yanking} means reinserting an entry of previously killed text
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
760 from the kill ring. The text properties are copied too.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 @deffn Command yank &optional arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @cindex inserting killed text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 This command inserts before point the text in the first entry in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 kill ring. It positions the mark at the beginning of that text, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 point at the end.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 If @var{arg} is a list (which occurs interactively when the user
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 types @kbd{C-u} with no digits), then @code{yank} inserts the text as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 described above, but puts point before the yanked text and puts the mark
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 after it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 recently killed text---the @var{arg}th element of the kill ring list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 @code{yank} does not alter the contents of the kill ring or rotate it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 @deffn Command yank-pop arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 This command replaces the just-yanked entry from the kill ring with a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782 different entry from the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 This is allowed only immediately after a @code{yank} or another
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 @code{yank-pop}. At such a time, the region contains text that was just
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 inserted by yanking. @code{yank-pop} deletes that text and inserts in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 its place a different piece of killed text. It does not add the deleted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 text to the kill ring, since it is already in the kill ring somewhere.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 If @var{arg} is @code{nil}, then the replacement text is the previous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 element of the kill ring. If @var{arg} is numeric, the replacement is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 kill is the replacement.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 The sequence of kills in the kill ring wraps around, so that after the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 oldest one comes the newest one, and before the newest one goes the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 oldest.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 The value is always @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
802 @node Low-Level Kill Ring
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
803 @subsection Low-Level Kill Ring
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 These functions and variables provide access to the kill ring at a lower
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 level, but still convenient for use in Lisp programs. They take care of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807 interaction with X Window selections. They do not exist in Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 version 18.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 @defun current-kill n &optional do-not-move
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
811 The function @code{current-kill} rotates the yanking pointer which
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
812 designates the ``front'' of the kill ring by @var{n} places (from newer
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
813 kills to older ones), and returns the text at that place in the ring.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 If the optional second argument @var{do-not-move} is non-@code{nil},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 then @code{current-kill} doesn't alter the yanking pointer; it just
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
817 returns the @var{n}th kill, counting from the current yanking pointer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 If @var{n} is zero, indicating a request for the latest kill,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 @code{current-kill} calls the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 @code{interprogram-paste-function} (documented below) before consulting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 the kill ring.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 @defun kill-new string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 This function puts the text @var{string} into the kill ring as a new
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 entry at the front of the ring. It discards the oldest entry if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 appropriate. It also invokes the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @code{interprogram-cut-function} (see below).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 @defun kill-append string before-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 This function appends the text @var{string} to the first entry in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 kill ring. Normally @var{string} goes at the end of the entry, but if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 @var{before-p} is non-@code{nil}, it goes at the beginning. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 function also invokes the value of @code{interprogram-cut-function} (see
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 below).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 @defvar interprogram-paste-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 This variable provides a way of transferring killed text from other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 programs, when you are using a window system. Its value should be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @code{nil} or a function of no arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 If the value is a function, @code{current-kill} calls it to get the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 ``most recent kill''. If the function returns a non-@code{nil} value,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 then that value is used as the ``most recent kill''. If it returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 @code{nil}, then the first element of @code{kill-ring} is used.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 The normal use of this hook is to get the X server's primary selection
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 as the most recent kill, even if the selection belongs to another X
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 client. @xref{X Selections}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 @defvar interprogram-cut-function
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
856 This variable provides a way of communicating killed text to other
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
857 programs, when you are using a window system. Its value should be
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858 @code{nil} or a function of one argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 If the value is a function, @code{kill-new} and @code{kill-append} call
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 it with the new first element of the kill ring as an argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 The normal use of this hook is to set the X server's primary selection
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 to the newly killed text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @node Internals of Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 @subsection Internals of the Kill Ring
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871 The variable @code{kill-ring} holds the kill ring contents, in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 form of a list of strings. The most recent kill is always at the front
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 of the list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 The @code{kill-ring-yank-pointer} variable points to a link in the
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
876 kill ring list, whose @sc{car} is the text to yank next. We say it
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
877 identifies the ``front'' of the ring. Moving
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878 @code{kill-ring-yank-pointer} to a different link is called
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
879 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
880 the functions that move the yank pointer wrap around from the end of the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
881 list to the beginning, or vice-versa. Rotation of the kill ring is
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
882 virtual; it does not change the value of @code{kill-ring}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 variables whose values are normally lists. The word ``pointer'' in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 name of the @code{kill-ring-yank-pointer} indicates that the variable's
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 purpose is to identify one element of the list for use by the next yank
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 command.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 of the links in the kill ring list. The element it identifies is the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 @sc{car} of that link. Kill commands, which change the kill ring, also
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
893 set this variable to the value of @code{kill-ring}. The effect is to
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
894 rotate the ring so that the newly killed text is at the front.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 pointing to the second entry in the kill ring @code{("some text" "a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 different piece of text" "yet older text")}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 kill-ring kill-ring-yank-pointer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 | ___ ___ ---> ___ ___ ___ ___
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 --> |___|___|------> |___|___|--> |___|___|--> nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 | | -->"yet older text"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 | --> "a different piece of text"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 --> "some text"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 This state of affairs might occur after @kbd{C-y} (@code{yank})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 immediately followed by @kbd{M-y} (@code{yank-pop}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 @defvar kill-ring
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
921 This variable holds the list of killed text sequences, most recently
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
922 killed first.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 @defvar kill-ring-yank-pointer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 This variable's value indicates which element of the kill ring is at the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 ``front'' of the ring for yanking. More precisely, the value is a tail
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 of the value of @code{kill-ring}, and its @sc{car} is the kill string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 that @kbd{C-y} should yank.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
931
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 @defopt kill-ring-max
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 The value of this variable is the maximum length to which the kill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 ring can grow, before elements are thrown away at the end. The default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 value for @code{kill-ring-max} is 30.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 @node Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 @section Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 @cindex redo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
943 Most buffers have an @dfn{undo list}, which records all changes made
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
944 to the buffer's text so that they can be undone. (The buffers that
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
945 don't have one are usually special-purpose buffers for which Emacs
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
946 assumes that undoing is not useful.) All the primitives that modify the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
947 text in the buffer automatically add elements to the front of the undo
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
948 list, which is in the variable @code{buffer-undo-list}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 @defvar buffer-undo-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951 This variable's value is the undo list of the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 A value of @code{t} disables the recording of undo information.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 Here are the kinds of elements an undo list can have:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
958 @item @var{integer}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959 This kind of element records a previous value of point. Ordinary cursor
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960 motion does not get any sort of undo record, but deletion commands use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 these entries to record where point was before the command.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 @item (@var{beg} . @var{end})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 This kind of element indicates how to delete text that was inserted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967
10364
981b97215c46 Fix buffer-undo-list.
Richard M. Stallman <rms@gnu.org>
parents: 9980
diff changeset
968 @item (@var{text} . @var{position})
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 This kind of element indicates how to reinsert text that was deleted.
10364
981b97215c46 Fix buffer-undo-list.
Richard M. Stallman <rms@gnu.org>
parents: 9980
diff changeset
970 The deleted text itself is the string @var{text}. The place to
981b97215c46 Fix buffer-undo-list.
Richard M. Stallman <rms@gnu.org>
parents: 9980
diff changeset
971 reinsert it is @code{(abs @var{position})}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 @item (t @var{high} . @var{low})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 This kind of element indicates that an unmodified buffer became
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 modified. The elements @var{high} and @var{low} are two integers, each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 recording 16 bits of the visited file's modification time as of when it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 was previously visited or saved. @code{primitive-undo} uses those
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978 values to determine whether to mark the buffer as unmodified once again;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 it does so only if the file's modification time matches those numbers.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 @item (nil @var{property} @var{value} @var{beg} . @var{end})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 This kind of element records a change in a text property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 Here's how you might undo the change:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 (put-text-property @var{beg} @var{end} @var{property} @var{value})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988
15760
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
989 @item (@var{marker} . @var{adjustment})
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
990 This kind of element records the fact that the marker @var{marker} was
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
991 relocated due to deletion of surrounding text, and that it moved
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
992 @var{adjustment} character positions. Undoing this element moves
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
993 @var{marker} @minus{} @var{adjustment} characters.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
994
10364
981b97215c46 Fix buffer-undo-list.
Richard M. Stallman <rms@gnu.org>
parents: 9980
diff changeset
995 @item @var{position}
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
996 This element indicates where point was at an earlier time. Undoing this
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
997 element sets point to @var{position}. Deletion normally creates an
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
998 element of this kind as well as a reinsertion element.
10364
981b97215c46 Fix buffer-undo-list.
Richard M. Stallman <rms@gnu.org>
parents: 9980
diff changeset
999
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @item nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 This element is a boundary. The elements between two boundaries are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 called a @dfn{change group}; normally, each change group corresponds to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 one keyboard command, and undo commands normally undo an entire group as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 a unit.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 @defun undo-boundary
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 This function places a boundary element in the undo list. The undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 command stops at such a boundary, and successive undo commands undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 to earlier and earlier boundaries. This function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011
11555
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1012 The editor command loop automatically creates an undo boundary before
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1013 each key sequence is executed. Thus, each undo normally undoes the
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1014 effects of one command. Self-inserting input characters are an
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1015 exception. The command loop makes a boundary for the first such
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1016 character; the next 19 consecutive self-inserting input characters do
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1017 not make boundaries, and then the 20th does, and so on as long as
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1018 self-inserting characters continue.
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1019
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1020 All buffer modifications add a boundary whenever the previous undoable
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1021 change was made in some other buffer. This way, a command that modifies
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1022 several buffers makes a boundary in each buffer it changes.
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1023
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1024 Calling this function explicitly is useful for splitting the effects of
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1025 a command into more than one unit. For example, @code{query-replace}
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1026 calls @code{undo-boundary} after each replacement, so that the user can
4cc0a5e1bdac Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents: 10364
diff changeset
1027 undo individual replacements one by one.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 @defun primitive-undo count list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031 This is the basic function for undoing elements of an undo list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 It undoes the first @var{count} elements of @var{list}, returning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 the rest of @var{list}. You could write this function in Lisp,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 but it is convenient to have it in C.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036 @code{primitive-undo} adds elements to the buffer's undo list when it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 changes the buffer. Undo commands avoid confusion by saving the undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 list value at the beginning of a sequence of undo operations. Then the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 undo operations use and update the saved value. The new elements added
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1040 by undoing are not part of this saved value, so they don't interfere with
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 continuing to undo.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 @node Maintaining Undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045 @section Maintaining Undo Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 This section describes how to enable and disable undo information for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048 a given buffer. It also explains how the undo list is truncated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 automatically so it doesn't get too big.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 Recording of undo information in a newly created buffer is normally
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 enabled to start with; but if the buffer name starts with a space, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 undo recording is initially disabled. You can explicitly enable or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 disable undo recording with the following two functions, or by setting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 @code{buffer-undo-list} yourself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 @deffn Command buffer-enable-undo &optional buffer-or-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 This command enables recording undo information for buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 @var{buffer-or-name}, so that subsequent changes can be undone. If no
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 argument is supplied, then the current buffer is used. This function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 does nothing if undo recording is already enabled in the buffer. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 In an interactive call, @var{buffer-or-name} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 You cannot specify any other buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 @defun buffer-disable-undo &optional buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 @defunx buffer-flush-undo &optional buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070 @cindex disable undo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 This function discards the undo list of @var{buffer}, and disables
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 further recording of undo information. As a result, it is no longer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073 possible to undo either previous changes or any subsequent changes. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 the undo list of @var{buffer} is already disabled, this function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 has no effect.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077 This function returns @code{nil}. It cannot be called interactively.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079 The name @code{buffer-flush-undo} is not considered obsolete, but the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 preferred name @code{buffer-disable-undo} is new as of Emacs versions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081 19.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 As editing continues, undo lists get longer and longer. To prevent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 them from using up all available memory space, garbage collection trims
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 them back to size limits you can set. (For this purpose, the ``size''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 of an undo list measures the cons cells that make up the list, plus the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 strings of deleted text.) Two variables control the range of acceptable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 sizes: @code{undo-limit} and @code{undo-strong-limit}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091 @defvar undo-limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092 This is the soft limit for the acceptable size of an undo list. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 change group at which this size is exceeded is the last one kept.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @defvar undo-strong-limit
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1097 This is the upper limit for the acceptable size of an undo list. The
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1098 change group at which this size is exceeded is discarded itself (along
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1099 with all older change groups). There is one exception: the very latest
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1100 change group is never discarded no matter how big it is.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 @node Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105 @section Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106 @cindex filling, explicit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108 @dfn{Filling} means adjusting the lengths of lines (by moving the line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 breaks) so that they are nearly (but no greater than) a specified
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 maximum width. Additionally, lines can be @dfn{justified}, which means
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1111 inserting spaces to make the left and/or right margins line up
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1112 precisely. The width is controlled by the variable @code{fill-column}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1113 For ease of reading, lines should be no longer than 70 or so columns.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 automatically as you insert it, but changes to existing text may leave
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117 it improperly filled. Then you must fill the text explicitly.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1119 Most of the commands in this section return values that are not
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1120 meaningful. All the functions that do filling take note of the current
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1121 left margin, current right margin, and current justification style
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1122 (@pxref{Margins}). If the current justification style is
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1123 @code{none}, the filling functions don't actually do anything.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1124
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1125 Several of the filling functions have an argument @var{justify}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1126 If it is non-@code{nil}, that requests some kind of justification. It
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1127 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1128 request a specific style of justification. If it is @code{t}, that
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1129 means to use the current justification style for this part of the text
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1130 (see @code{current-justification}, below).
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1131
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1132 When you call the filling functions interactively, using a prefix
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1133 argument implies the value @code{full} for @var{justify}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1134
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1135 @deffn Command fill-paragraph justify
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 @cindex filling a paragraph
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 This command fills the paragraph at or after point. If
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1138 @var{justify} is non-@code{nil}, each line is justified as well.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 It uses the ordinary paragraph motion commands to find paragraph
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1143 @deffn Command fill-region start end &optional justify
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144 This command fills each of the paragraphs in the region from @var{start}
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1145 to @var{end}. It justifies as well if @var{justify} is
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 non-@code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 The variable @code{paragraph-separate} controls how to distinguish
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149 paragraphs. @xref{Standard Regexps}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1152 @deffn Command fill-individual-paragraphs start end &optional justify mail-flag
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 This command fills each paragraph in the region according to its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154 individual fill prefix. Thus, if the lines of a paragraph were indented
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 with spaces, the filled paragraph will remain indented in the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 fashion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 The first two arguments, @var{start} and @var{end}, are the beginning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 and end of the region to be filled. The third and fourth arguments,
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1160 @var{justify} and @var{mail-flag}, are optional. If
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1161 @var{justify} is non-@code{nil}, the paragraphs are justified as
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 well as filled. If @var{mail-flag} is non-@code{nil}, it means the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 function is operating on a mail message and therefore should not fill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 the header lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 Ordinarily, @code{fill-individual-paragraphs} regards each change in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 indentation as starting a new paragraph. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168 @code{fill-individual-varying-indent} is non-@code{nil}, then only
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1169 separator lines separate paragraphs. That mode can handle indented
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1170 paragraphs with additional indentation on the first line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 @defopt fill-individual-varying-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 This variable alters the action of @code{fill-individual-paragraphs} as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 described above.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1178 @deffn Command fill-region-as-paragraph start end &optional justify
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 This command considers a region of text as a paragraph and fills it. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 the region was made up of many paragraphs, the blank lines between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 paragraphs are removed. This function justifies as well as filling when
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1182 @var{justify} is non-@code{nil}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1183
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1184 In an interactive call, any prefix argument requests justification.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 16702
diff changeset
1186 In Adaptive Fill mode, which is enabled by default, calling the function
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 @code{fill-region-as-paragraph} on an indented paragraph when there is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 no fill prefix uses the indentation of the second line of the paragraph
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 as the fill prefix.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1192 @deffn Command justify-current-line how eop nosqueeze
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 This command inserts spaces between the words of the current line so
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 that the line ends exactly at @code{fill-column}. It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 @code{nil}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1196
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1197 The argument @var{how}, if non-@code{nil} specifies explicitly the style
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1198 of justification. It can be @code{left}, @code{right}, @code{full},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1199 @code{center}, or @code{none}. If it is @code{t}, that means to do
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1200 follow specified justification style (see @code{current-justification},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1201 below). @code{nil} means to do full justification.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1202
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 16702
diff changeset
1203 If @var{eop} is non-@code{nil}, that means do left-justification if
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1204 @code{current-justification} specifies full justification. This is used
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1205 for the last line of a paragraph; even if the paragraph as a whole is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1206 fully justified, the last line should not be.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1207
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1208 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1209 whitespace.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1212 @defopt default-justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1213 This variable's value specifies the style of justification to use for
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1214 text that doesn't specify a style with a text property. The possible
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1215 values are @code{left}, @code{right}, @code{full}, @code{center}, or
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1216 @code{none}. The default value is @code{left}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1217 @end defopt
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1218
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1219 @defun current-justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1220 This function returns the proper justification style to use for filling
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1221 the text around point.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1222 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1223
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1224 @defvar fill-paragraph-function
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1225 This variable provides a way for major modes to override the filling of
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1226 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1227 this function to do the work. If the function returns a non-@code{nil}
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1228 value, @code{fill-paragraph} assumes the job is done, and immediately
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1229 returns that value.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1230
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1231 The usual use of this feature is to fill comments in programming
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1232 language modes. If the function needs to fill a paragraph in the usual
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1233 way, it can do so as follows:
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1234
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1235 @example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1236 (let ((fill-paragraph-function nil))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1237 (fill-paragraph arg))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1238 @end example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1239 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1240
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1241 @defvar use-hard-newlines
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1242 If this variable is non-@code{nil}, the filling functions do not delete
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1243 newlines that have the @code{hard} text property. These ``hard
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1244 newlines'' act as paragraph separators.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1245 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1246
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1247 @node Margins
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1248 @section Margins for Filling
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1249
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1250 @defopt fill-prefix
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1251 This variable specifies a string of text that appears at the beginning
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1252 of normal text lines and should be disregarded when filling them. Any
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1253 line that fails to start with the fill prefix is considered the start of
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1254 a paragraph; so is any line that starts with the fill prefix followed by
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1255 additional whitespace. Lines that start with the fill prefix but no
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1256 additional whitespace are ordinary text lines that can be filled
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1257 together. The resulting filled lines also start with the fill prefix.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1258
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1259 The fill prefix follows the left margin whitespace, if any.
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1260 @end defopt
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1261
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262 @defopt fill-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 This buffer-local variable specifies the maximum width of filled
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 lines. Its value should be an integer, which is a number of columns.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 All the filling, justification and centering commands are affected by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 this variable, including Auto Fill mode (@pxref{Auto Filling}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 As a practical matter, if you are writing text for other people to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 read, you should set @code{fill-column} to no more than 70. Otherwise
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 the line will be too long for people to read comfortably, and this can
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271 make the text seem clumsy.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274 @defvar default-fill-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275 The value of this variable is the default value for @code{fill-column} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276 buffers that do not override it. This is the same as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 @code{(default-value 'fill-column)}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1279 The default value for @code{default-fill-column} is 70.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1280 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1281
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1282 @deffn Command set-left-margin from to margin
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1283 This sets the @code{left-margin} property on the text from @var{from} to
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1284 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1285 command also refills the region to fit the new margin.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1286 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1287
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1288 @deffn Command set-right-margin from to margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1289 This sets the @code{right-margin} property on the text from @var{from}
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1290 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1291 this command also refills the region to fit the new margin.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1292 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1293
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1294 @defun current-left-margin
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1295 This function returns the proper left margin value to use for filling
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1296 the text around point. The value is the sum of the @code{left-margin}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1297 property of the character at the start of the current line (or zero if
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1298 none), and the value of the variable @code{left-margin}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1299 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1300
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1301 @defun current-fill-column
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1302 This function returns the proper fill column value to use for filling
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1303 the text around point. The value is the value of the @code{fill-column}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1304 variable, minus the value of the @code{right-margin} property of the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1305 character after point.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1306 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1307
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1308 @deffn Command move-to-left-margin &optional n force
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1309 This function moves point to the left margin of the current line. The
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1310 column moved to is determined by calling the function
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1311 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1312 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1313
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1314 If @var{force} is non-@code{nil}, that says to fix the line's
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1315 indentation if that doesn't match the left margin value.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1316 @end deffn
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1317
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1318 @defun delete-to-left-margin from to
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1319 This function removes left margin indentation from the text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1320 between @var{from} and @var{to}. The amount of indentation
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1321 to delete is determined by calling @code{current-left-margin}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1322 In no case does this function delete non-whitespace.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1323 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1324
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1325 @defun indent-to-left-margin
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1326 This is the default @code{indent-line-function}, used in Fundamental
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1327 mode, Text mode, etc. Its effect is to adjust the indentation at the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1328 beginning of the current line to the value specified by the variable
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1329 @code{left-margin}. This may involve either inserting or deleting
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1330 whitespace.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1331 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1332
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1333 @defvar left-margin
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1334 This variable specifies the base left margin column. In Fundamental
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1335 mode, @key{LFD} indents to this column. This variable automatically
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1336 becomes buffer-local when set in any fashion.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1337 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1338
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339 @node Auto Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341 @section Auto Filling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 @cindex filling, automatic
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343 @cindex Auto Fill mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1344
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1345 Auto Fill mode is a minor mode that fills lines automatically as text
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1346 is inserted. This section describes the hook used by Auto Fill mode.
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1347 For a description of functions that you can call explicitly to fill and
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1348 justify existing text, see @ref{Filling}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1350 Auto Fill mode also enables the functions that change the margins and
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1351 justification style to refill portions of the text. @xref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1352
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 @defvar auto-fill-function
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1354 The value of this variable should be a function (of no arguments) to be
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1355 called after self-inserting a space or a newline. It may be @code{nil},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
1356 in which case nothing special is done in that case.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 The value of @code{auto-fill-function} is @code{do-auto-fill} when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359 Auto-Fill mode is enabled. That is a function whose sole purpose is to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360 implement the usual strategy for breaking a line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1362 @quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 In older Emacs versions, this variable was named @code{auto-fill-hook},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364 but since it is not called with the standard convention for hooks, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 was renamed to @code{auto-fill-function} in version 19.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366 @end quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368
16702
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1369 @defvar normal-auto-fill-function
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1370 This variable specifies the function to use for
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1371 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1372 modes can set this locally to alter how Auto Fill works.
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1373 @end defvar
7704b62dafa8 Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents: 16398
diff changeset
1374
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 @node Sorting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376 @section Sorting Text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1377 @cindex sorting text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379 The sorting functions described in this section all rearrange text in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380 a buffer. This is in contrast to the function @code{sort}, which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1381 rearranges the order of the elements of a list (@pxref{Rearrangement}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1382 The values returned by these functions are not meaningful.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1385 This function is the general text-sorting routine that divides a buffer
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1386 into records and sorts them. Most of the commands in this section use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1387 this function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1388
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1389 To understand how @code{sort-subr} works, consider the whole accessible
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390 portion of the buffer as being divided into disjoint pieces called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1391 @dfn{sort records}. The records may or may not be contiguous; they may
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1392 not overlap. A portion of each sort record (perhaps all of it) is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1393 designated as the sort key. Sorting rearranges the records in order by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1394 their sort keys.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1395
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1396 Usually, the records are rearranged in order of ascending sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397 If the first argument to the @code{sort-subr} function, @var{reverse},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398 is non-@code{nil}, the sort records are rearranged in order of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1399 descending sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1400
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401 The next four arguments to @code{sort-subr} are functions that are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402 called to move point across a sort record. They are called many times
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1403 from within @code{sort-subr}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405 @enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 @var{nextrecfun} is called with point at the end of a record. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 function moves point to the start of the next record. The first record
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 is assumed to start at the position of point when @code{sort-subr} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 called. Therefore, you should usually move point to the beginning of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411 the buffer before calling @code{sort-subr}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413 This function can indicate there are no more sort records by leaving
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414 point at the end of the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1416 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417 @var{endrecfun} is called with point within a record. It moves point to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 the end of the record.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421 @var{startkeyfun} is called to move point from the start of a record to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422 the start of the sort key. This argument is optional; if it is omitted,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423 the whole record is the sort key. If supplied, the function should
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 either return a non-@code{nil} value to be used as the sort key, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1425 return @code{nil} to indicate that the sort key is in the buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426 starting at point. In the latter case, @var{endkeyfun} is called to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1427 find the end of the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1430 @var{endkeyfun} is called to move point from the start of the sort key
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431 to the end of the sort key. This argument is optional. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1433 @code{nil}), then the sort key extends to the end of the record. There
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1434 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1435 non-@code{nil} value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1436 @end enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1437
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1438 As an example of @code{sort-subr}, here is the complete function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1439 definition for @code{sort-lines}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 ;; @r{Note that the first two lines of doc string}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 ;; @r{are effectively one line when viewed by a user.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 (defun sort-lines (reverse beg end)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446 "Sort lines in region alphabetically.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 Called from a program, there are three arguments:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450 REVERSE (non-nil means reverse order),
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451 and BEG and END (the region to sort)."
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452 (interactive "P\nr")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 (save-restriction
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 (narrow-to-region beg end)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 (goto-char (point-min))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 (sort-subr reverse
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 'forward-line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458 'end-of-line)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 Here @code{forward-line} moves point to the start of the next record,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 and @code{end-of-line} moves point to the end of record. We do not pass
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 record is used as the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 The @code{sort-paragraphs} function is very much the same, except that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 its @code{sort-subr} call looks like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472 (sort-subr reverse
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 (function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 (lambda ()
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 (skip-chars-forward "\n \t\f")))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 'forward-paragraph)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482 This command sorts the region between @var{start} and @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484 If @var{reverse} is a negative integer, then sorting is in reverse
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1485 order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 Alphabetical sorting means that two sort keys are compared by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488 comparing the first characters of each, the second characters of each,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1489 and so on. If a mismatch is found, it means that the sort keys are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1490 unequal; the sort key whose character is less at the point of first
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1491 mismatch is the lesser sort key. The individual characters are compared
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492 according to their numerical values. Since Emacs uses the @sc{ASCII}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1493 character set, the ordering in that set determines alphabetical order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494 @c version 19 change
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496 The value of the @var{record-regexp} argument specifies how to divide
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497 the buffer into sort records. At the end of each record, a search is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1498 done for this regular expression, and the text that matches it is the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1499 next record. For example, the regular expression @samp{^.+$}, which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 matches lines with at least one character besides a newline, would make
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1501 each such line into a sort record. @xref{Regular Expressions}, for a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1502 description of the syntax and meaning of regular expressions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1503
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1504 The value of the @var{key-regexp} argument specifies what part of each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 record is the sort key. The @var{key-regexp} could match the whole
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1506 record, or only a part. In the latter case, the rest of the record has
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507 no effect on the sorted order of records, but it is carried along when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508 the record moves to its new position.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1509
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 The @var{key-regexp} argument can refer to the text matched by a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511 subexpression of @var{record-regexp}, or it can be a regular expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 on its own.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1513
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1514 If @var{key-regexp} is:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1516 @table @asis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 @item @samp{\@var{digit}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519 grouping in @var{record-regexp} is the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521 @item @samp{\&}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522 then the whole record is the sort key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524 @item a regular expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525 then @code{sort-regexp-fields} searches for a match for the regular
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 expression within the record. If such a match is found, it is the sort
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1527 key. If there is no match for @var{key-regexp} within a record then
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528 that record is ignored, which means its position in the buffer is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1529 changed. (The other records may move around it.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532 For example, if you plan to sort all the lines in the region by the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533 first word on each line starting with the letter @samp{f}, you should
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535 @samp{\<f\w*\>}. The resulting expression looks like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 (region-beginning)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541 (region-end))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 If you call @code{sort-regexp-fields} interactively, it prompts for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546 @var{record-regexp} and @var{key-regexp} in the minibuffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1547 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549 @deffn Command sort-lines reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550 This command alphabetically sorts lines in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555 @deffn Command sort-paragraphs reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1556 This command alphabetically sorts paragraphs in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1557 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1558 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1560
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561 @deffn Command sort-pages reverse start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562 This command alphabetically sorts pages in the region between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1565 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1566
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1567 @deffn Command sort-fields field start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1568 This command sorts lines in the region between @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1569 @var{end}, comparing them alphabetically by the @var{field}th field
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1570 of each line. Fields are separated by whitespace and numbered starting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1571 from 1. If @var{field} is negative, sorting is by the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1572 @w{@minus{}@var{field}th} field from the end of the line. This command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573 is useful for sorting tables.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1575
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1576 @deffn Command sort-numeric-fields field start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1577 This command sorts lines in the region between @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 @var{end}, comparing them numerically by the @var{field}th field of each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579 line. The specified field must contain a number in each line of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1580 region. Fields are separated by whitespace and numbered starting from
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1581 1. If @var{field} is negative, sorting is by the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1582 @w{@minus{}@var{field}th} field from the end of the line. This command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1583 is useful for sorting tables.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1584 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1585
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1586 @deffn Command sort-columns reverse &optional beg end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1587 This command sorts the lines in the region between @var{beg} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1588 @var{end}, comparing them alphabetically by a certain range of columns.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1589 The column positions of @var{beg} and @var{end} bound the range of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1590 columns to sort on.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1592 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1593
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1594 One unusual thing about this command is that the entire line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1595 containing position @var{beg}, and the entire line containing position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1596 @var{end}, are included in the region sorted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1597
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1598 Note that @code{sort-columns} uses the @code{sort} utility program,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1599 and so cannot work properly on text containing tab characters. Use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1600 @kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1601 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1602
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1603 @node Columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1604 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1605 @section Counting Columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606 @cindex columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607 @cindex counting columns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1608 @cindex horizontal position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1609
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1610 The column functions convert between a character position (counting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1611 characters from the beginning of the buffer) and a column position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1612 (counting screen characters from the beginning of a line).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1613
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1614 A character counts according to the number of columns it occupies on
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1615 the screen. This means control characters count as occupying 2 or 4
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1616 columns, depending upon the value of @code{ctl-arrow}, and tabs count as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1617 occupying a number of columns that depends on the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1618 @code{tab-width} and on the column where the tab begins. @xref{Usual Display}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620 Column number computations ignore the width of the window and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1621 amount of horizontal scrolling. Consequently, a column value can be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1622 arbitrarily high. The first (or leftmost) column is numbered 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1623
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1624 @defun current-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1625 This function returns the horizontal position of point, measured in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1626 columns, counting from 0 at the left margin. The column position is the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627 sum of the widths of all the displayed representations of the characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628 between the start of the current line and point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 For an example of using @code{current-column}, see the description of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 @code{count-lines} in @ref{Text Lines}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1632 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1633
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634 @defun move-to-column column &optional force
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1635 This function moves point to @var{column} in the current line. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1636 calculation of @var{column} takes into account the widths of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1637 displayed representations of the characters between the start of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638 line and point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1639
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640 If column @var{column} is beyond the end of the line, point moves to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1641 end of the line. If @var{column} is negative, point moves to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1642 beginning of the line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1643
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1644 If it is impossible to move to column @var{column} because that is in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1645 the middle of a multicolumn character such as a tab, point moves to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1646 end of that character. However, if @var{force} is non-@code{nil}, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1647 @var{column} is in the middle of a tab, then @code{move-to-column}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1648 converts the tab into spaces so that it can move precisely to column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1649 @var{column}. Other multicolumn characters can cause anomalies despite
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1650 @var{force}, since there is no way to split them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1651
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1652 The argument @var{force} also has an effect if the line isn't long
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1653 enough to reach column @var{column}; in that case, it says to add
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1654 whitespace at the end of the line to reach that column.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1655
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1656 If @var{column} is not an integer, an error is signaled.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1657
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1658 The return value is the column number actually moved to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1659 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1660
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1661 @node Indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1662 @section Indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1663 @cindex indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1664
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1665 The indentation functions are used to examine, move to, and change
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1666 whitespace that is at the beginning of a line. Some of the functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1667 can also change whitespace elsewhere on a line. Columns and indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1668 count from zero at the left margin.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1669
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1670 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1671 * Primitive Indent:: Functions used to count and insert indentation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1672 * Mode-Specific Indent:: Customize indentation for different modes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1673 * Region Indent:: Indent all the lines in a region.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1674 * Relative Indent:: Indent the current line based on previous lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1675 * Indent Tabs:: Adjustable, typewriter-like tab stops.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1676 * Motion by Indent:: Move to first non-blank character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1677 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1678
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1679 @node Primitive Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1680 @subsection Indentation Primitives
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1681
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1682 This section describes the primitive functions used to count and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1683 insert indentation. The functions in the following sections use these
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1684 primitives.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1685
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1686 @defun current-indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1687 @comment !!Type Primitive Function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1688 @comment !!SourceFile indent.c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1689 This function returns the indentation of the current line, which is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1690 the horizontal position of the first nonblank character. If the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1691 contents are entirely blank, then this is the horizontal position of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1692 end of the line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1693 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1694
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1695 @deffn Command indent-to column &optional minimum
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1696 @comment !!Type Primitive Function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1697 @comment !!SourceFile indent.c
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1698 This function indents from point with tabs and spaces until @var{column}
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1699 is reached. If @var{minimum} is specified and non-@code{nil}, then at
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1700 least that many spaces are inserted even if this requires going beyond
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1701 @var{column}. Otherwise the function does nothing if point is already
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1702 beyond @var{column}. The value is the column at which the inserted
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1703 indentation ends.
8644
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1704
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1705 The inserted whitespace characters inherit text properties from the
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1706 surrounding text (usually, from the preceding text only). @xref{Sticky
ebda9d1e7d48 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1707 Properties}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1708 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1709
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1710 @defopt indent-tabs-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1711 @comment !!SourceFile indent.c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1712 If this variable is non-@code{nil}, indentation functions can insert
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1713 tabs as well as spaces. Otherwise, they insert only spaces. Setting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1714 this variable automatically makes it local to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1715 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1716
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1717 @node Mode-Specific Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1718 @subsection Indentation Controlled by Major Mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1719
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1720 An important function of each major mode is to customize the @key{TAB}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1721 key to indent properly for the language being edited. This section
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1722 describes the mechanism of the @key{TAB} key and how to control it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1723 The functions in this section return unpredictable values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1725 @defvar indent-line-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1726 This variable's value is the function to be used by @key{TAB} (and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1727 various commands) to indent the current line. The command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1728 @code{indent-according-to-mode} does no more than call this function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1729
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1730 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1731 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1732 In Fundamental mode, Text mode, and many other modes with no standard
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1733 for indentation, the value is @code{indent-to-left-margin} (which is the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1734 default value).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1735 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1736
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1737 @deffn Command indent-according-to-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1738 This command calls the function in @code{indent-line-function} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1739 indent the current line in a way appropriate for the current major mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1740 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1741
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1742 @deffn Command indent-for-tab-command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1743 This command calls the function in @code{indent-line-function} to indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1744 the current line; except that if that function is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1745 @code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1746 is a trivial command that inserts a tab character.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1747 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1748
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1749 @deffn Command newline-and-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1750 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1751 This function inserts a newline, then indents the new line (the one
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1752 following the newline just inserted) according to the major mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1753
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1754 It does indentation by calling the current @code{indent-line-function}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1755 In programming language modes, this is the same thing @key{TAB} does,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1756 but in some text modes, where @key{TAB} inserts a tab,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1757 @code{newline-and-indent} indents to the column specified by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1758 @code{left-margin}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1759 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1760
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1761 @deffn Command reindent-then-newline-and-indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1762 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1763 This command reindents the current line, inserts a newline at point,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1764 and then reindents the new line (the one following the newline just
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1765 inserted).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1766
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1767 This command does indentation on both lines according to the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1768 major mode, by calling the current value of @code{indent-line-function}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1769 In programming language modes, this is the same thing @key{TAB} does,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770 but in some text modes, where @key{TAB} inserts a tab,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771 @code{reindent-then-newline-and-indent} indents to the column specified
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1772 by @code{left-margin}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1773 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1774
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1775 @node Region Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1776 @subsection Indenting an Entire Region
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1777
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1778 This section describes commands that indent all the lines in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1779 region. They return unpredictable values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1780
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1781 @deffn Command indent-region start end to-column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1782 This command indents each nonblank line starting between @var{start}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1783 (inclusive) and @var{end} (exclusive). If @var{to-column} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1784 @code{nil}, @code{indent-region} indents each nonblank line by calling
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1785 the current mode's indentation function, the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1786 @code{indent-line-function}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1787
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1788 If @var{to-column} is non-@code{nil}, it should be an integer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1789 specifying the number of columns of indentation; then this function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1790 gives each line exactly that much indentation, by either adding or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1791 deleting whitespace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1792
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1793 If there is a fill prefix, @code{indent-region} indents each line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1794 by making it start with the fill prefix.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1795 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1796
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1797 @defvar indent-region-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1798 The value of this variable is a function that can be used by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1799 @code{indent-region} as a short cut. You should design the function so
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1800 that it will produce the same results as indenting the lines of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1801 region one by one, but presumably faster.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1802
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1803 If the value is @code{nil}, there is no short cut, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1804 @code{indent-region} actually works line by line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1805
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1806 A short-cut function is useful in modes such as C mode and Lisp mode,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1807 where the @code{indent-line-function} must scan from the beginning of
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1808 the function definition: applying it to each line would be quadratic in
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1809 time. The short cut can update the scan information as it moves through
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1810 the lines indenting them; this takes linear time. In a mode where
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1811 indenting a line individually is fast, there is no need for a short cut.
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1812
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1813 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1814 a different meaning and does not use this variable.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1815 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1816
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1817 @deffn Command indent-rigidly start end count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1818 @comment !!SourceFile indent.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1819 This command indents all lines starting between @var{start}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1820 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1821 This ``preserves the shape'' of the affected region, moving it as a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1822 rigid unit. Consequently, this command is useful not only for indenting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1823 regions of unindented text, but also for indenting regions of formatted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1824 code.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1825
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1826 For example, if @var{count} is 3, this command adds 3 columns of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1827 indentation to each of the lines beginning in the region specified.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1828
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1829 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1830 @code{indent-rigidly} to indent the text copied from the message being
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1831 replied to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1832 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1833
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1834 @defun indent-code-rigidly start end columns &optional nochange-regexp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1835 This is like @code{indent-rigidly}, except that it doesn't alter lines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1836 that start within strings or comments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1837
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1838 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1839 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1840 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1841
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1842 @node Relative Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1843 @subsection Indentation Relative to Previous Lines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1844
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1845 This section describes two commands that indent the current line
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1846 based on the contents of previous lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1847
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1848 @deffn Command indent-relative &optional unindented-ok
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1849 This command inserts whitespace at point, extending to the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1850 column as the next @dfn{indent point} of the previous nonblank line. An
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1851 indent point is a non-whitespace character following whitespace. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1852 next indent point is the first one at a column greater than the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1853 column of point. For example, if point is underneath and to the left of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1854 the first non-blank character of a line of text, it moves to that column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1855 by inserting whitespace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1856
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1857 If the previous nonblank line has no next indent point (i.e., none at a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1858 great enough column position), @code{indent-relative} either does
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1859 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1860 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1861 of the last column of a short line of text, this command ordinarily
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1862 moves point to the next tab stop by inserting whitespace.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1863
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1864 The return value of @code{indent-relative} is unpredictable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1865
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1866 In the following example, point is at the beginning of the second
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1867 line:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1868
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1869 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1870 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1871 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1872 @point{}The quick brown fox jumped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1873 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1874 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1875
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1876 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1877 Evaluation of the expression @code{(indent-relative nil)} produces the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1878 following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1879
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1880 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1881 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1882 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1883 @point{}The quick brown fox jumped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1884 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1885 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1886
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1887 In this example, point is between the @samp{m} and @samp{p} of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1888 @samp{jumped}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1889
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1890 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1891 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1892 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1893 The quick brown fox jum@point{}ped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1894 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1895 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1896
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1897 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1898 Evaluation of the expression @code{(indent-relative nil)} produces the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1899 following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1900
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1901 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1902 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1903 This line is indented twelve spaces.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1904 The quick brown fox jum @point{}ped.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1905 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1906 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1907 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1908
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1909 @deffn Command indent-relative-maybe
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1910 @comment !!SourceFile indent.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1911 This command indents the current line like the previous nonblank line.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1912 It calls @code{indent-relative} with @code{t} as the @var{unindented-ok}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1913 argument. The return value is unpredictable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1914
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1915 If the previous nonblank line has no indent points beyond the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1916 column, this command does nothing.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1917 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1918
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1919 @node Indent Tabs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1920 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1921 @subsection Adjustable ``Tab Stops''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1922 @cindex tabs stops for indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1923
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1924 This section explains the mechanism for user-specified ``tab stops''
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1925 and the mechanisms that use and set them. The name ``tab stops'' is
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1926 used because the feature is similar to that of the tab stops on a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1927 typewriter. The feature works by inserting an appropriate number of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1928 spaces and tab characters to reach the next tab stop column; it does not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1929 affect the display of tab characters in the buffer (@pxref{Usual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1930 Display}). Note that the @key{TAB} character as input uses this tab
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1931 stop feature only in a few major modes, such as Text mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1932
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1933 @deffn Command tab-to-tab-stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1934 This command inserts spaces or tabs up to the next tab stop column
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1935 defined by @code{tab-stop-list}. It searches the list for an element
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1936 greater than the current column number, and uses that element as the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1937 column to indent to. It does nothing if no such element is found.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1938 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1939
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1940 @defopt tab-stop-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1941 This variable is the list of tab stop columns used by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1942 @code{tab-to-tab-stops}. The elements should be integers in increasing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1943 order. The tab stop columns need not be evenly spaced.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1944
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1945 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1946 interactively.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1947 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1948
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1949 @node Motion by Indent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1950 @subsection Indentation-Based Motion Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1951
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1952 These commands, primarily for interactive use, act based on the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1953 indentation in the text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1954
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1955 @deffn Command back-to-indentation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1956 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1957 This command moves point to the first non-whitespace character in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1958 current line (which is the line in which point is located). It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1959 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1960 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1961
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1962 @deffn Command backward-to-indentation arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1963 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1964 This command moves point backward @var{arg} lines and then to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1965 first nonblank character on that line. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1966 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1967
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1968 @deffn Command forward-to-indentation arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1969 @comment !!SourceFile simple.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 This command moves point forward @var{arg} lines and then to the first
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1971 nonblank character on that line. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1973
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1974 @node Case Changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1975 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1976 @section Case Changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1977 @cindex case changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1978
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1979 The case change commands described here work on text in the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1980 buffer. @xref{Character Case}, for case conversion commands that work
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1981 on strings and characters. @xref{Case Table}, for how to customize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1982 which characters are upper or lower case and how to convert them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1983
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1984 @deffn Command capitalize-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1985 This function capitalizes all words in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1986 @var{start} and @var{end}. To capitalize means to convert each word's
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987 first character to upper case and convert the rest of each word to lower
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1988 case. The function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1989
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1990 If one end of the region is in the middle of a word, the part of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1991 word within the region is treated as an entire word.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1992
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1993 When @code{capitalize-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1994 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1995
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1996 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1997 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1998 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1999 This is the contents of the 5th foo.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2000 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2001 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2002
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2003 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2004 (capitalize-region 1 44)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2005 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2006
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2007 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2008 This Is The Contents Of The 5th Foo.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2009 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2010 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2011 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2012 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2013
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2014 @deffn Command downcase-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2015 This function converts all of the letters in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2016 @var{start} and @var{end} to lower case. The function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2017 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2018
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2019 When @code{downcase-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2020 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2021 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2022
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2023 @deffn Command upcase-region start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2024 This function converts all of the letters in the region defined by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2025 @var{start} and @var{end} to upper case. The function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2026 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2027
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2028 When @code{upcase-region} is called interactively, @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2029 @var{end} are point and the mark, with the smallest first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2030 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2031
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2032 @deffn Command capitalize-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2033 This function capitalizes @var{count} words after point, moving point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2034 over as it does. To capitalize means to convert each word's first
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2035 character to upper case and convert the rest of each word to lower case.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2036 If @var{count} is negative, the function capitalizes the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2037 @minus{}@var{count} previous words but does not move point. The value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2038 is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2039
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2040 If point is in the middle of a word, the part of the word before point
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2041 is ignored when moving forward. The rest is treated as an entire word.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2042
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2043 When @code{capitalize-word} is called interactively, @var{count} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2044 set to the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2045 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2046
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2047 @deffn Command downcase-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2048 This function converts the @var{count} words after point to all lower
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2049 case, moving point over as it does. If @var{count} is negative, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2050 converts the @minus{}@var{count} previous words but does not move point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2051 The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2052
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2053 When @code{downcase-word} is called interactively, @var{count} is set
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2054 to the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2055 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2056
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2057 @deffn Command upcase-word count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2058 This function converts the @var{count} words after point to all upper
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2059 case, moving point over as it does. If @var{count} is negative, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2060 converts the @minus{}@var{count} previous words but does not move point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2061 The value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2062
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2063 When @code{upcase-word} is called interactively, @var{count} is set to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2064 the numeric prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2065 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2066
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2067 @node Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2068 @section Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2069 @cindex text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2070 @cindex attributes of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2071 @cindex properties of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2072
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2073 Each character position in a buffer or a string can have a @dfn{text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2074 property list}, much like the property list of a symbol (@pxref{Property
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2075 Lists}). The properties belong to a particular character at a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2076 particular place, such as, the letter @samp{T} at the beginning of this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2077 sentence or the first @samp{o} in @samp{foo}---if the same character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2078 occurs in two different places, the two occurrences generally have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2079 different properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2080
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2081 Each property has a name and a value. Both of these can be any Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2082 object, but the name is normally a symbol. The usual way to access the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2083 property list is to specify a name and ask what value corresponds to it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2084
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2085 If a character has a @code{category} property, we call it the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2086 @dfn{category} of the character. It should be a symbol. The properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2087 of the symbol serve as defaults for the properties of the character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2088
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2089 Copying text between strings and buffers preserves the properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2090 along with the characters; this includes such diverse functions as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2091 @code{substring}, @code{insert}, and @code{buffer-substring}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2092
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2093 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2094 * Examining Properties:: Looking at the properties of one character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2095 * Changing Properties:: Setting the properties of a range of text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2096 * Property Search:: Searching for where a property changes value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2097 * Special Properties:: Particular properties with special meanings.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2098 * Format Properties:: Properties for representing formatting of text.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2099 * Sticky Properties:: How inserted text gets properties from
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2100 neighboring text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2101 * Saving Properties:: Saving text properties in files, and reading
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2102 them back.
15760
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2103 * Lazy Properties:: Computing text properties in a lazy fashion
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2104 only when text is examined.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2105 * Not Intervals:: Why text properties do not use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2106 Lisp-visible text intervals.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2107 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2108
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2109 @node Examining Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2110 @subsection Examining Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2111
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2112 The simplest way to examine text properties is to ask for the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2113 a particular property of a particular character. For that, use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2114 @code{get-text-property}. Use @code{text-properties-at} to get the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2115 entire property list of a character. @xref{Property Search}, for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2116 functions to examine the properties of a number of characters at once.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2117
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2118 These functions handle both strings and buffers. Keep in mind that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2119 positions in a string start from 0, whereas positions in a buffer start
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2120 from 1.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2121
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2122 @defun get-text-property pos prop &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2123 This function returns the value of the @var{prop} property of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2124 character after position @var{pos} in @var{object} (a buffer or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2125 string). The argument @var{object} is optional and defaults to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2126 current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2127
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2128 If there is no @var{prop} property strictly speaking, but the character
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2129 has a category that is a symbol, then @code{get-text-property} returns
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2130 the @var{prop} property of that symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2131 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2132
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2133 @defun get-char-property pos prop &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2134 This function is like @code{get-text-property}, except that it checks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2135 overlays first and then text properties. @xref{Overlays}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2136
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2137 The argument @var{object} may be a string, a buffer, or a window. If it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2138 is a window, then the buffer displayed in that window is used for text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2139 properties and overlays, but only the overlays active for that window
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2140 are considered. If @var{object} is a buffer, then all overlays in that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2141 buffer are considered, as well as text properties. If @var{object} is a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2142 string, only text properties are considered, since strings never have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2143 overlays.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2144 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2145
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2146 @defun text-properties-at position &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2147 This function returns the entire property list of the character at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2148 @var{position} in the string or buffer @var{object}. If @var{object} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2149 @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2150 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2151
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2152 @defvar default-text-properties
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2153 This variable holds a property list giving default values for text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2154 properties. Whenever a character does not specify a value for a
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2155 property, neither directly nor through a category symbol, the value
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2156 stored in this list is used instead. Here is an example:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2157
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2158 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2159 (setq default-text-properties '(foo 69))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2160 ;; @r{Make sure character 1 has no properties of its own.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2161 (set-text-properties 1 2 nil)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2162 ;; @r{What we get, when we ask, is the default value.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2163 (get-text-property 1 'foo)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2164 @result{} 69
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2165 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2166 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2167
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2168 @node Changing Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2169 @subsection Changing Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2170
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2171 The primitives for changing properties apply to a specified range of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2172 text. The function @code{set-text-properties} (see end of section) sets
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2173 the entire property list of the text in that range; more often, it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2174 useful to add, change, or delete just certain properties specified by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2175 name.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2176
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2177 Since text properties are considered part of the buffer's contents, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2178 can affect how the buffer looks on the screen, any change in the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2179 properties is considered a buffer modification. Buffer text property
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2180 changes are undoable (@pxref{Undo}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2181
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2182 @defun put-text-property start end prop value &optional object
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2183 This function sets the @var{prop} property to @var{value} for the text
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2184 between @var{start} and @var{end} in the string or buffer @var{object}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2185 If @var{object} is @code{nil}, it defaults to the current buffer.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2186 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2187
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2188 @defun add-text-properties start end props &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2189 This function modifies the text properties for the text between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2190 @var{start} and @var{end} in the string or buffer @var{object}. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2191 @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2192
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2193 The argument @var{props} specifies which properties to change. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2194 should have the form of a property list (@pxref{Property Lists}): a list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2195 whose elements include the property names followed alternately by the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2196 corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2197
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2198 The return value is @code{t} if the function actually changed some
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2199 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2200 its values agree with those in the text).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2201
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2202 For example, here is how to set the @code{comment} and @code{face}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2203 properties of a range of text:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2204
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2205 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2206 (add-text-properties @var{start} @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2207 '(comment t face highlight))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2208 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2209 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2210
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2211 @defun remove-text-properties start end props &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2212 This function deletes specified text properties from the text between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2213 @var{start} and @var{end} in the string or buffer @var{object}. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2214 @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2215
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2216 The argument @var{props} specifies which properties to delete. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2217 should have the form of a property list (@pxref{Property Lists}): a list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2218 whose elements are property names alternating with corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2219 But only the names matter---the values that accompany them are ignored.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2220 For example, here's how to remove the @code{face} property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2221
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2222 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2223 (remove-text-properties @var{start} @var{end} '(face nil))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2224 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2225
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2226 The return value is @code{t} if the function actually changed some
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2227 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2228 if no character in the specified text had any of those properties).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2229 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2230
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2231 @defun set-text-properties start end props &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2232 This function completely replaces the text property list for the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2233 between @var{start} and @var{end} in the string or buffer @var{object}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2234 If @var{object} is @code{nil}, it defaults to the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2235
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2236 The argument @var{props} is the new property list. It should be a list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2237 whose elements are property names alternating with corresponding values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2238
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2239 After @code{set-text-properties} returns, all the characters in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2240 specified range have identical properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2241
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2242 If @var{props} is @code{nil}, the effect is to get rid of all properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2243 from the specified range of text. Here's an example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2244
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2245 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2246 (set-text-properties @var{start} @var{end} nil)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2247 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2248 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2249
13109
acb0ab49f4e7 Fix name of buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents: 12775
diff changeset
2250 See also the function @code{buffer-substring-no-properties}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2251 (@pxref{Buffer Contents}) which copies text from the buffer
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2252 but does not copy its properties.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2253
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2254 @node Property Search
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2255 @subsection Property Search Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2256
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2257 In typical use of text properties, most of the time several or many
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2258 consecutive characters have the same value for a property. Rather than
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2259 writing your programs to examine characters one by one, it is much
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2260 faster to process chunks of text that have the same property value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2261
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2262 Here are functions you can use to do this. They use @code{eq} for
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2263 comparing property values. In all cases, @var{object} defaults to the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2264 current buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2265
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2266 For high performance, it's very important to use the @var{limit}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2267 argument to these functions, especially the ones that search for a
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2268 single property---otherwise, they may spend a long time scanning to the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2269 end of the buffer, if the property you are interested in does not change.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2270
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2271 Remember that a position is always between two characters; the position
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2272 returned by these functions is between two characters with different
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2273 properties.
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2274
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2275 @defun next-property-change pos &optional object limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2276 The function scans the text forward from position @var{pos} in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2277 string or buffer @var{object} till it finds a change in some text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2278 property, then returns the position of the change. In other words, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2279 returns the position of the first character beyond @var{pos} whose
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2280 properties are not identical to those of the character just after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2281 @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2282
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2283 If @var{limit} is non-@code{nil}, then the scan ends at position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2284 @var{limit}. If there is no property change before that point,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2285 @code{next-property-change} returns @var{limit}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2286
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2287 The value is @code{nil} if the properties remain unchanged all the way
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2288 to the end of @var{object} and @var{limit} is @code{nil}. If the value
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2289 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2290 The value equals @var{pos} only when @var{limit} equals @var{pos}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2291
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2292 Here is an example of how to scan the buffer by chunks of text within
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2293 which all properties are constant:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2294
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2295 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2296 (while (not (eobp))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2297 (let ((plist (text-properties-at (point)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2298 (next-change
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2299 (or (next-property-change (point) (current-buffer))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2300 (point-max))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2301 @r{Process text from point to @var{next-change}@dots{}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2302 (goto-char next-change)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2303 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2304 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2305
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2306 @defun next-single-property-change pos prop &optional object limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2307 The function scans the text forward from position @var{pos} in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2308 string or buffer @var{object} till it finds a change in the @var{prop}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2309 property, then returns the position of the change. In other words, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2310 returns the position of the first character beyond @var{pos} whose
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2311 @var{prop} property differs from that of the character just after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2312 @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2313
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2314 If @var{limit} is non-@code{nil}, then the scan ends at position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2315 @var{limit}. If there is no property change before that point,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2316 @code{next-single-property-change} returns @var{limit}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2317
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2318 The value is @code{nil} if the property remains unchanged all the way to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2319 the end of @var{object} and @var{limit} is @code{nil}. If the value is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2320 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2321 equals @var{pos} only if @var{limit} equals @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2322 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2323
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2324 @defun previous-property-change pos &optional object limit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2325 This is like @code{next-property-change}, but scans back from @var{pos}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2326 instead of forward. If the value is non-@code{nil}, it is a position
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2327 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2328 equals @var{pos}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2329 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2330
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2331 @defun previous-single-property-change pos prop &optional object limit
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2332 This is like @code{next-single-property-change}, but scans back from
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2333 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2334 position less than or equal to @var{pos}; it equals @var{pos} only if
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2335 @var{limit} equals @var{pos}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2336 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2337
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2338 @defun text-property-any start end prop value &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2339 This function returns non-@code{nil} if at least one character between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2340 @var{start} and @var{end} has a property @var{prop} whose value is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2341 @var{value}. More precisely, it returns the position of the first such
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2342 character. Otherwise, it returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2343
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2344 The optional fifth argument, @var{object}, specifies the string or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2345 buffer to scan. Positions are relative to @var{object}. The default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2346 for @var{object} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2347 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2348
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2349 @defun text-property-not-all start end prop value &optional object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2350 This function returns non-@code{nil} if at least one character between
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2351 @var{start} and @var{end} has a property @var{prop} whose value differs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2352 from @var{value}. More precisely, it returns the position of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2353 first such character. Otherwise, it returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2354
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2355 The optional fifth argument, @var{object}, specifies the string or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2356 buffer to scan. Positions are relative to @var{object}. The default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2357 for @var{object} is the current buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2358 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2359
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2360 @node Special Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2361 @subsection Properties with Special Meanings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2362
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2363 Here is a table of text property names that have special built-in
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2364 meanings. The following section lists a few more special property names
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2365 that are used to control filling. All other names have no standard
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2366 meaning, and you can use them as you like.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2367
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2368 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2369 @cindex category of text character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2370 @kindex category @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2371 @item category
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2372 If a character has a @code{category} property, we call it the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2373 @dfn{category} of the character. It should be a symbol. The properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2374 of the symbol serve as defaults for the properties of the character.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2375
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2376 @item face
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2377 @cindex face codes of text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2378 @kindex face @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2379 You can use the property @code{face} to control the font and color of
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2380 text. Its value is a face name or a list of face names. @xref{Faces},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2381 for more information. This feature may be temporary; in the future, we
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2382 may replace it with other ways of specifying how to display text.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2383
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2384 @item mouse-face
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2385 @kindex mouse-face @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2386 The property @code{mouse-face} is used instead of @code{face} when the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2387 mouse is on or near the character. For this purpose, ``near'' means
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2388 that all text between the character and where the mouse is have the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2389 @code{mouse-face} property value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2390
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2391 @item local-map
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2392 @cindex keymap of character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2393 @kindex local-map @r{(text property)}
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2394 You can specify a different keymap for a portion of the text by means of
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2395 a @code{local-map} property. The property's value for the character
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2396 after point, if non-@code{nil}, replaces the buffer's local map.
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2397 @xref{Active Keymaps}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2398
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2399 @item read-only
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2400 @cindex read-only character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2401 @kindex read-only @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2402 If a character has the property @code{read-only}, then modifying that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2403 character is not allowed. Any command that would do so gets an error.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2404
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2405 Insertion next to a read-only character is an error if inserting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2406 ordinary text there would inherit the @code{read-only} property due to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2407 stickiness. Thus, you can control permission to insert next to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2408 read-only text by controlling the stickiness. @xref{Sticky Properties}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2409
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2410 Since changing properties counts as modifying the buffer, it is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2411 possible to remove a @code{read-only} property unless you know the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2412 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2413 and then remove the property. @xref{Read Only Buffers}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2414
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2415 @item invisible
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2416 @kindex invisible @r{(text property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2417 A non-@code{nil} @code{invisible} property can make a character invisible
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2418 on the screen. @xref{Invisible Text}, for details.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2419
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2420 @item intangible
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2421 @kindex intangible @r{(text property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2422 If a group of consecutive characters have equal and non-@code{nil}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2423 @code{intangible} properties, then you cannot place point between them.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2424 If you try to move point forward into the group, point actually moves to
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2425 the end of the group. If you try to move point backward into the group,
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2426 point actually moves to the start of the group.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2427
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2428 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2429 the @code{intangible} property is ignored.
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2430
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2431 @item modification-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2432 @cindex change hooks for a character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2433 @cindex hooks for changing a character
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2434 @kindex modification-hooks @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2435 If a character has the property @code{modification-hooks}, then its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2436 value should be a list of functions; modifying that character calls all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2437 of those functions. Each function receives two arguments: the beginning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2438 and end of the part of the buffer being modified. Note that if a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2439 particular modification hook function appears on several characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2440 being modified by a single primitive, you can't predict how many times
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2441 the function will be called.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2442
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2443 @item insert-in-front-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2444 @itemx insert-behind-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2445 @kindex insert-in-front-hooks @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2446 @kindex insert-behind-hooks @r{(text property)}
16398
71e49abd5906 Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents: 15760
diff changeset
2447 The operation of inserting text in a buffer also calls the functions
71e49abd5906 Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents: 15760
diff changeset
2448 listed in the @code{insert-in-front-hooks} property of the following
71e49abd5906 Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents: 15760
diff changeset
2449 character and in the @code{insert-behind-hooks} property of the
71e49abd5906 Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents: 15760
diff changeset
2450 preceding character. These functions receive two arguments, the
71e49abd5906 Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents: 15760
diff changeset
2451 beginning and end of the inserted text. The functions are called
71e49abd5906 Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents: 15760
diff changeset
2452 @emph{after} the actual insertion takes place.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2453
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2454 See also @ref{Change Hooks}, for other hooks that are called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2455 when you change text in a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2456
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2457 @item point-entered
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2458 @itemx point-left
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2459 @cindex hooks for motion of point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2460 @kindex point-entered @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2461 @kindex point-left @r{(text property)}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2462 The special properties @code{point-entered} and @code{point-left}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2463 record hook functions that report motion of point. Each time point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2464 moves, Emacs compares these two property values:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2465
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2466 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2467 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2468 the @code{point-left} property of the character after the old location,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2469 and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2470 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2471 the @code{point-entered} property of the character after the new
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2472 location.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2473 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2474
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2475 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2476 If these two values differ, each of them is called (if not @code{nil})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2477 with two arguments: the old value of point, and the new one.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2478
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2479 The same comparison is made for the characters before the old and new
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2480 locations. The result may be to execute two @code{point-left} functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2481 (which may be the same function) and/or two @code{point-entered}
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2482 functions (which may be the same function). In any case, all the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2483 @code{point-left} functions are called first, followed by all the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2484 @code{point-entered} functions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2485
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2486 A primitive function may examine characters at various positions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2487 without moving point to those positions. Only an actual change in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2488 value of point runs these hook functions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2489 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2490
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2491 @defvar inhibit-point-motion-hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2492 When this variable is non-@code{nil}, @code{point-left} and
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2493 @code{point-entered} hooks are not run, and the @code{intangible}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2494 property has no effect.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2495 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2496
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2497 @node Format Properties
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2498 @subsection Formatted Text Properties
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2499
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2500 These text properties affect the behavior of the fill commands. They
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2501 are used for representing formatted text. @xref{Filling}, and
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2502 @ref{Margins}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2503
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2504 @table @code
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2505 @item hard
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2506 If a newline character has this property, it is a ``hard'' newline.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2507 The fill commands do not alter hard newlines and do not move words
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2508 across them. However, this property takes effect only if the variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2509 @code{use-hard-newlines} is non-@code{nil}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2510
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2511 @item right-margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2512 This property specifies an extra right margin for filling this part of the
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2513 text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2514
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2515 @item left-margin
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2516 This property specifies an extra left margin for filling this part of the
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2517 text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2518
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2519 @item justification
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2520 This property specifies the style of justification for filling this part
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2521 of the text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2522 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11555
diff changeset
2523
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2524 @node Sticky Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2525 @subsection Stickiness of Text Properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2526 @cindex sticky text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2527 @cindex inheritance of text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2528
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2529 Self-inserting characters normally take on the same properties as the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2530 preceding character. This is called @dfn{inheritance} of properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2531
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2532 In a Lisp program, you can do insertion with inheritance or without,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2533 depending on your choice of insertion primitive. The ordinary text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2534 insertion functions such as @code{insert} do not inherit any properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2535 They insert text with precisely the properties of the string being
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2536 inserted, and no others. This is correct for programs that copy text
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2537 from one context to another---for example, into or out of the kill ring.
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2538 To insert with inheritance, use the special primitives described in this
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2539 section. Self-inserting characters inherit properties because they work
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2540 using these primitives.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2541
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2542 When you do insertion with inheritance, @emph{which} properties are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2543 inherited depends on two specific properties: @code{front-sticky} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2544 @code{rear-nonsticky}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2545
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2546 Insertion after a character inherits those of its properties that are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2547 @dfn{rear-sticky}. Insertion before a character inherits those of its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2548 properties that are @dfn{front-sticky}. By default, a text property is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2549 rear-sticky but not front-sticky. Thus, the default is to inherit all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2550 the properties of the preceding character, and nothing from the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2551 following character. You can request different behavior by specifying
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2552 the stickiness of certain properties.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2553
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2554 If a character's @code{front-sticky} property is @code{t}, then all
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2555 its properties are front-sticky. If the @code{front-sticky} property is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2556 a list, then the sticky properties of the character are those whose
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2557 names are in the list. For example, if a character has a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2558 @code{front-sticky} property whose value is @code{(face read-only)},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2559 then insertion before the character can inherit its @code{face} property
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2560 and its @code{read-only} property, but no others.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2561
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2562 The @code{rear-nonsticky} works the opposite way. Every property is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2563 rear-sticky by default, so the @code{rear-nonsticky} property says which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2564 properties are @emph{not} rear-sticky. If a character's
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2565 @code{rear-nonsticky} property is @code{t}, then none of its properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2566 are rear-sticky. If the @code{rear-nonsticky} property is a list,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2567 properties are rear-sticky @emph{unless} their names are in the list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2568
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2569 When you insert text with inheritance, it inherits all the rear-sticky
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2570 properties of the preceding character, and all the front-sticky
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2571 properties of the following character. The previous character's
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2572 properties take precedence when both sides offer different sticky values
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2573 for the same property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2574
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2575 Here are the functions that insert text with inheritance of properties:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2576
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2577 @defun insert-and-inherit &rest strings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2578 Insert the strings @var{strings}, just like the function @code{insert},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2579 but inherit any sticky properties from the adjoining text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2580 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2581
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2582 @defun insert-before-markers-and-inherit &rest strings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2583 Insert the strings @var{strings}, just like the function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2584 @code{insert-before-markers}, but inherit any sticky properties from the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2585 adjoining text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2586 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2587
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2588 @node Saving Properties
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2589 @subsection Saving Text Properties in Files
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2590 @cindex text properties in files
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2591 @cindex saving text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2592
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2593 You can save text properties in files, and restore text properties
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2594 when inserting the files, using these two hooks:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2595
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2596 @defvar write-region-annotate-functions
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2597 This variable's value is a list of functions for @code{write-region} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2598 run to encode text properties in some fashion as annotations to the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2599 being written in the file. @xref{Writing to Files}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2600
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2601 Each function in the list is called with two arguments: the start and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2602 end of the region to be written. These functions should not alter the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2603 contents of the buffer. Instead, they should return lists indicating
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2604 annotations to write in the file in addition to the text in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2605 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2606
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2607 Each function should return a list of elements of the form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2608 @code{(@var{position} . @var{string})}, where @var{position} is an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2609 integer specifying the relative position in the text to be written, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2610 @var{string} is the annotation to add there.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2611
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2612 Each list returned by one of these functions must be already sorted in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2613 increasing order by @var{position}. If there is more than one function,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2614 @code{write-region} merges the lists destructively into one sorted list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2615
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2616 When @code{write-region} actually writes the text from the buffer to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2617 file, it intermixes the specified annotations at the corresponding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2618 positions. All this takes place without modifying the buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2619 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2620
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2621 @defvar after-insert-file-functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2622 This variable holds a list of functions for @code{insert-file-contents}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2623 to call after inserting a file's contents. These functions should scan
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2624 the inserted text for annotations, and convert them to the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2625 properties they stand for.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2626
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2627 Each function receives one argument, the length of the inserted text;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2628 point indicates the start of that text. The function should scan that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2629 text for annotations, delete them, and create the text properties that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2630 the annotations specify. The function should return the updated length
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2631 of the inserted text, as it stands after those changes. The value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2632 returned by one function becomes the argument to the next function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2633
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2634 These functions should always return with point at the beginning of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2635 the inserted text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2636
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2637 The intended use of @code{after-insert-file-functions} is for converting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2638 some sort of textual annotations into actual text properties. But other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2639 uses may be possible.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2640 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2641
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2642 We invite users to write Lisp programs to store and retrieve text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2643 properties in files, using these hooks, and thus to experiment with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2644 various data formats and find good ones. Eventually we hope users
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2645 will produce good, general extensions we can install in Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2646
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2647 We suggest not trying to handle arbitrary Lisp objects as property
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2648 names or property values---because a program that general is probably
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2649 difficult to write, and slow. Instead, choose a set of possible data
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2650 types that are reasonably flexible, and not too hard to encode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2651
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2652 @xref{Format Conversion}, for a related feature.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2653
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2654 @c ??? In next edition, merge this info Format Conversion.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2655
15760
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2656 @node Lazy Properties
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2657 @subsection Lazy Computation of Text Properties
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2658
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2659 Instead of computing text properties for all the text in the buffer,
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2660 you can arrange to compute the text properties for parts of the text
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2661 when and if something depends on them.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2662
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2663 The primitive that extracts text from the buffer along with its
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2664 properties is @code{buffer-substring}. Before examining the properties,
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2665 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2666
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2667 @defvar buffer-access-fontify-functions
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2668 This variable holds a list of functions for computing text properties.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2669 Before @code{buffer-substring} copies the text and text properties for a
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2670 portion of the buffer, it calls all the functions in this list. Each of
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2671 the functions receives two arguments that specify the range of the
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2672 buffer being accessed. (The buffer itself is always the current
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2673 buffer.)
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2674 @end defvar
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2675
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2676 The function @code{buffer-substring-no-properties} does not call these
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2677 functions, since it ignores text properties anyway.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2678
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2679 In order to prevent the hook functions from being called more than
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2680 once for the same part of the buffer, you can use the variable
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2681 @code{buffer-access-fontified-property}.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2682
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2683 @defvar buffer-access-fontified-property
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2684 If this value's variable is non-@code{nil}, it is a symbol which is used
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2685 as a text property name. A non-@code{nil} value for that text property
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2686 means, ``the other text properties for this character have already been
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2687 computed.''
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2688
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2689 If all the characters in the range specified for @code{buffer-substring}
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2690 have a non-@code{nil} value for this property, @code{buffer-substring}
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2691 does not call the @code{buffer-access-fontify-functions} functions. It
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2692 assumes these characters already have the right text properties, and
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2693 just copies the properties they already have.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2694
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2695 The normal way to use this feature is that the
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2696 @code{buffer-access-fontify-functions} functions add this property, as
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2697 well as others, to the characters they operate on. That way, they avoid
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2698 being called over and over for the same text.
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2699 @end defvar
0489cb739a5f (Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents: 13109
diff changeset
2700
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2701 @node Not Intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2702 @subsection Why Text Properties are not Intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2703 @cindex intervals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2704
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2705 Some editors that support adding attributes to text in the buffer do
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2706 so by letting the user specify ``intervals'' within the text, and adding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2707 the properties to the intervals. Those editors permit the user or the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2708 programmer to determine where individual intervals start and end. We
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2709 deliberately provided a different sort of interface in Emacs Lisp to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2710 avoid certain paradoxical behavior associated with text modification.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2711
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2712 If the actual subdivision into intervals is meaningful, that means you
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2713 can distinguish between a buffer that is just one interval with a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2714 certain property, and a buffer containing the same text subdivided into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2715 two intervals, both of which have that property.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2716
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2717 Suppose you take the buffer with just one interval and kill part of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2718 the text. The text remaining in the buffer is one interval, and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2719 copy in the kill ring (and the undo list) becomes a separate interval.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2720 Then if you yank back the killed text, you get two intervals with the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2721 same properties. Thus, editing does not preserve the distinction
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2722 between one interval and two.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2723
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2724 Suppose we ``fix'' this problem by coalescing the two intervals when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2725 the text is inserted. That works fine if the buffer originally was a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2726 single interval. But suppose instead that we have two adjacent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2727 intervals with the same properties, and we kill the text of one interval
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2728 and yank it back. The same interval-coalescence feature that rescues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2729 the other case causes trouble in this one: after yanking, we have just
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2730 one interval. One again, editing does not preserve the distinction
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2731 between one interval and two.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2732
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2733 Insertion of text at the border between intervals also raises
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2734 questions that have no satisfactory answer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2735
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2736 However, it is easy to arrange for editing to behave consistently for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2737 questions of the form, ``What are the properties of this character?''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2738 So we have decided these are the only questions that make sense; we have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2739 not implemented asking questions about where intervals start or end.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2740
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2741 In practice, you can usually use the property search functions in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2742 place of explicit interval boundaries. You can think of them as finding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2743 the boundaries of intervals, assuming that intervals are always
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2744 coalesced whenever possible. @xref{Property Search}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2745
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2746 Emacs also provides explicit intervals as a presentation feature; see
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2747 @ref{Overlays}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2748
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2749 @node Substitution
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2750 @section Substituting for a Character Code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2751
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2752 The following functions replace characters within a specified region
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2753 based on their character codes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2754
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2755 @defun subst-char-in-region start end old-char new-char &optional noundo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2756 @cindex replace characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2757 This function replaces all occurrences of the character @var{old-char}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2758 with the character @var{new-char} in the region of the current buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2759 defined by @var{start} and @var{end}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2760
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2761 @cindex Outline mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2762 @cindex undo avoidance
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2763 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2764 not record the change for undo and does not mark the buffer as modified.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2765 This feature is used for controlling selective display (@pxref{Selective
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2766 Display}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2767
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2768 @code{subst-char-in-region} does not move point and returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2769 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2770
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2771 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2772 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2773 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2774 This is the contents of the buffer before.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2775 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2776 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2777
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2778 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2779 (subst-char-in-region 1 20 ?i ?X)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2780 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2781
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2782 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2783 ThXs Xs the contents of the buffer before.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2784 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2785 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2786 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2787 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2788
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2789 @defun translate-region start end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2790 This function applies a translation table to the characters in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2791 buffer between positions @var{start} and @var{end}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2792
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2793 The translation table @var{table} is a string; @code{(aref @var{table}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2794 @var{ochar})} gives the translated character corresponding to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2795 @var{ochar}. If the length of @var{table} is less than 256, any
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2796 characters with codes larger than the length of @var{table} are not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2797 altered by the translation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2798
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2799 The return value of @code{translate-region} is the number of
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2800 characters that were actually changed by the translation. This does
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2801 not count characters that were mapped into themselves in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2802 translation table.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2803 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2804
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2805 @node Registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2806 @section Registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2807 @cindex registers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2808
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2809 A register is a sort of variable used in Emacs editing that can hold a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2810 marker, a string, a rectangle, a window configuration (of one frame), or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2811 a frame configuration (of all frames). Each register is named by a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2812 single character. All characters, including control and meta characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2813 (but with the exception of @kbd{C-g}), can be used to name registers.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2814 Thus, there are 255 possible registers. A register is designated in
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2815 Emacs Lisp by a character that is its name.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2816
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2817 The functions in this section return unpredictable values unless
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2818 otherwise stated.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2819 @c Will change in version 19
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2820
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2821 @defvar register-alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2822 This variable is an alist of elements of the form @code{(@var{name} .
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2823 @var{contents})}. Normally, there is one element for each Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2824 register that has been used.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2825
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2826 The object @var{name} is a character (an integer) identifying the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2827 register. The object @var{contents} is a string, marker, or list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2828 representing the register contents. A string represents text stored in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2829 the register. A marker represents a position. A list represents a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2830 rectangle; its elements are strings, one per line of the rectangle.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2831 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2832
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2833 @defun get-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2834 This function returns the contents of the register
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2835 @var{reg}, or @code{nil} if it has no contents.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2836 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2837
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2838 @defun set-register reg value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2839 This function sets the contents of register @var{reg} to @var{value}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2840 A register can be set to any value, but the other register functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2841 expect only certain data types. The return value is @var{value}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2842 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2843
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2844 @deffn Command view-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2845 This command displays what is contained in register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2846 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2847
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2848 @ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2849 @deffn Command point-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2850 This command stores both the current location of point and the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2851 buffer in register @var{reg} as a marker.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2852 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2853
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2854 @deffn Command jump-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2855 @deffnx Command register-to-point reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2856 @comment !!SourceFile register.el
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2857 This command restores the status recorded in register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2858
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2859 If @var{reg} contains a marker, it moves point to the position stored in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2860 the marker. Since both the buffer and the location within the buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2861 are stored by the @code{point-to-register} function, this command can
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2862 switch you to another buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2863
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2864 If @var{reg} contains a window configuration or a frame configuration.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2865 @code{jump-to-register} restores that configuration.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2866 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2867 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2868
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2869 @deffn Command insert-register reg &optional beforep
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2870 This command inserts contents of register @var{reg} into the current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2871 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2872
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2873 Normally, this command puts point before the inserted text, and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2874 mark after it. However, if the optional second argument @var{beforep}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2875 is non-@code{nil}, it puts the mark before and point after.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2876 You can pass a non-@code{nil} second argument @var{beforep} to this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2877 function interactively by supplying any prefix argument.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2878
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2879 If the register contains a rectangle, then the rectangle is inserted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2880 with its upper left corner at point. This means that text is inserted
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2881 in the current line and underneath it on successive lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2882
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2883 If the register contains something other than saved text (a string) or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2884 a rectangle (a list), currently useless things happen. This may be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2885 changed in the future.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2886 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2887
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2888 @ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2889 @deffn Command copy-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2890 This command copies the region from @var{start} to @var{end} into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2891 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2892 the region from the buffer after copying it into the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2893 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2894
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2895 @deffn Command prepend-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2896 This command prepends the region from @var{start} to @var{end} into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2897 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2898 the region from the buffer after copying it to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2899 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2900
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2901 @deffn Command append-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2902 This command appends the region from @var{start} to @var{end} to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2903 text already in register @var{reg}. If @var{delete-flag} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2904 non-@code{nil}, it deletes the region from the buffer after copying it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2905 to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2906 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2907
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2908 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2909 This command copies a rectangular region from @var{start} to @var{end}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2910 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2911 deletes the region from the buffer after copying it to the register.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2912 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2913
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2914 @deffn Command window-configuration-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2915 This function stores the window configuration of the selected frame in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2916 register @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2917 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2918
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2919 @deffn Command frame-configuration-to-register reg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2920 This function stores the current frame configuration in register
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2921 @var{reg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2922 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2923 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2924
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2925 @node Transposition
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2926 @section Transposition of Text
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2927
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2928 This subroutine is used by the transposition commands.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2929
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2930 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2931 This function exchanges two nonoverlapping portions of the buffer.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2932 Arguments @var{start1} and @var{end1} specify the bounds of one portion
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2933 and arguments @var{start2} and @var{end2} specify the bounds of the
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2934 other portion.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2935
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2936 Normally, @code{transpose-regions} relocates markers with the transposed
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2937 text; a marker previously positioned within one of the two transposed
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2938 portions moves along with that portion, thus remaining between the same
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2939 two characters in their new position. However, if @var{leave-markers}
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2940 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2941 all markers unrelocated.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2942 @end defun
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2943
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2944 @node Change Hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2945 @section Change Hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2946 @cindex change hooks
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2947 @cindex hooks for text changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2948
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2949 These hook variables let you arrange to take notice of all changes in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2950 all buffers (or in a particular buffer, if you make them buffer-local).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2951 See also @ref{Special Properties}, for how to detect changes to specific
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2952 parts of the text.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2953
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2954 The functions you use in these hooks should save and restore the match
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2955 data if they do anything that uses regular expressions; otherwise, they
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2956 will interfere in bizarre ways with the editing operations that call
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2957 them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2958
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2959 @defvar before-change-functions
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2960 This variable holds a list of a functions to call before any buffer
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2961 modification. Each function gets two arguments, the beginning and end
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2962 of the region that is about to change, represented as integers. The
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2963 buffer that is about to change is always the current buffer.
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2964 @end defvar
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2965
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2966 @defvar after-change-functions
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2967 This variable holds a list of a functions to call after any buffer
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2968 modification. Each function receives three arguments: the beginning and
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2969 end of the region just changed, and the length of the text that existed
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2970 before the change. (To get the current length, subtract the region
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2971 beginning from the region end.) All three arguments are integers. The
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2972 buffer that's about to change is always the current buffer.
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2973 @end defvar
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2974
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2975 @defvar before-change-function
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2976 This obsolete variable holds one function to call before any buffer
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2977 modification (or @code{nil} for no function). It is called just like
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2978 the functions in @code{before-change-functions}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2979 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2980
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2981 @defvar after-change-function
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2982 This obsolete variable holds one function to call after any buffer modification
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2983 (or @code{nil} for no function). It is called just like the functions in
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2984 @code{after-change-functions}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2985 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2986
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2987 The four variables above are temporarily bound to @code{nil} during the
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2988 time that any of these functions is running. This means that if one of
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2989 these functions changes the buffer, that change won't run these
6782
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2990 functions. If you do want a hook function to make changes that run
5b07647ec8f7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
2991 these functions, make it bind these variables back to their usual
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2992 values.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2993
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2994 One inconvenient result of this protective feature is that you cannot
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2995 have a function in @code{after-change-functions} or
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2996 @code{before-change-functions} which changes the value of that variable.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2997 But that's not a real limitation. If you want those functions to change
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2998 the list of functions to run, simply add one fixed function to the hook,
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
2999 and code that function to look in another variable for other functions
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3000 to call. Here is an example:
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3001
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3002 @example
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3003 (setq my-own-after-change-functions nil)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3004 (defun indirect-after-change-function (beg end len)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3005 (let ((list my-own-after-change-functions))
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3006 (while list
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3007 (funcall (car list) beg end len)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3008 (setq list (cdr list)))))
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3009 (add-hooks 'after-change-functions
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3010 'indirect-after-change-function)
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3011 @end example
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6782
diff changeset
3012
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3013 @defvar first-change-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3014 This variable is a normal hook that is run whenever a buffer is changed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3015 that was previously in the unmodified state.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3016 @end defvar