annotate lispref/text.texi @ 20389:e15a9b5e0a70

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